Sèrie d'entrevistes AI 16: Com hauria de ser un bon Spec Coding?

Un bon Spec Coding (programació basada en especificacions) consisteix a convertir "idees vagues" en "contractes precisos, verificables i executables". No es tracta només d'escriure un document, sinó d'establir un llenguatge de comunicació sense ambigüitats entre humans i IA (o entre humans). A continuació, des de quatre dimensions —estructura del contingut de l'especificació, principis de redacció, procés de col·laboració amb la IA i verificació de qualitat— mostraré com ha de ser un bon spec.

1. Estructura estàndard d'un document d'especificació (amb un mòdul de funcionalitat com a exemple)

Secció	Contingut obligatori	Exemple
1. Objectiu i abast	Una frase que indiqui què es fa, i especificar clarament què no es fa	"Implementar l'API de registre d'usuari, sense incloure verificació de correu electrònic"
2. Contracte d'entrada/sortida	Tipus de dada, tipus, camps obligatoris/opcionals, valors d'exemple	Cos de la sol·licitud `POST /register` `{email: string, password: string}`, resposta `201` o `400` amb codi d'error
3. Comportament i lògica	Regles de negoci, condicions límit, transicions d'estat	"Longitud de contrasenya de 8-20 caràcters, almenys un número; si el correu electrònic ja existeix, retorna `409`"
4. Gestió d'errors	Tots els escenaris d'excepció possibles i els codis d'error/missatges corresponents	"La connexió a la base de dades falla → retorna `503`, sense exposar la pila"
5. Requisits no funcionals	Rendiment (temps de resposta < 200ms), seguretat (consultes parametritzades), registre, observabilitat	"Totes les SQL han d'utilitzar precompilació; registrar `email` però no `password`"
6. Casos de prova (clau)	Almenys 3 entrades típiques + 2 entrades límit/excepcionals, amb sortida esperada	Vegeu la taula següent
7. Dependències i restriccions	Quines biblioteques, versions, variables d'entorn utilitzar	"Python 3.10+, FastAPI, variable d'entorn `DB_URL`"

Exemple de casos de prova (incrustats a l'spec)

Escenari	Entrada	Sortida esperada
Registre normal	email: `a@b.com`, pwd: `Pass1234`	`201`, retorna `user_id`
Contrasenya massa curta	pwd: `Ab1`	`400`, codi d'error `WEAK_PASSWORD`
Correu electrònic ja existeix	email mateix	`409`, codi d'error `EMAIL_EXISTS`

Un bon spec ha d'escriure primer els casos de prova, perquè la IA pot generar directament proves unitàries a partir d'ells i verificar automàticament un cop acabades.

2. Principis bàsics per escriure un spec (variant SMART)

Principi	Explicació	Contraexemple
Precis (Precise)	Utilitzar nombres concrets, tipus, condicions booleanes; evitar "tant com sigui possible", "normalment"	❌ "La contrasenya ha de ser prou segura" → ✅ "Contrasenya d'almenys 8 caràcters, amb majúscules, minúscules i números"
Verificable (Verifiable)	Cada requisit ha de poder ser avaluat com a aprovat/fallit mitjançant proves automàtiques o revisió manual	❌ "El codi ha de ser elegant" → ✅ "Complexitat ciclomàtica de la funció ≤ 10, sense blocs de codi duplicats"
Sense ambigüitats (Unambiguous)	El mateix terme ha de tenir el mateix significat a tot el document; si cal, proporcionar un glossari	❌ "Si l'usuari no existeix, retorna error" → ✅ "Usuari no existeix → retorna `404` i `{code: 'USER_NOT_FOUND'}`"
Complet (Complete)	Cobrir el camí feliç, tots els camins d'excepció i requisits no funcionals	❌ Només s'ha escrit l'escenari d'èxit → ✅ Incloure temps d'espera de base de dades, permisos insuficients, etc.
Atòmic (Atomic)	Un spec descriu un sol punt de funcionalitat que es pugui lliurar de manera independent (perquè la IA el completi d'una vegada)	❌ Escriure "tot el sistema de pagament" en un sol spec → ✅ Dividir en "generar ordre de pagament", "verificar signatura de callback", "reemborsament"

3. Procés de Spec Coding en col·laboració amb la IA

La persona escriu l'spec (amb l'estructura anterior, especialment els casos de prova i les signatures de funció).
Donar l'spec a la IA d'una sola vegada (no afegir requisits de manera conversacional per evitar contaminació de vibe).
La IA genera codi + proves unitàries (la IA ha de generar proves executables segons els casos de prova de l'spec).
Executar les proves: si totes passen, passar al següent pas; si no, modificar l'spec o corregir directament el codi (en aquest punt es pot entrar en un bucle petit, però cal registrar els canvis).
Revisió manual: comprovar si s'han introduït funcionalitats fora de l'spec (scope creep), revisar seguretat/rendiment.
Consolidació: enviar el document de l'spec juntament amb el codi final al repositori com a documentació permanent.

Pràctica clau: Codificar l'spec — utilitzar spec.md + test_spec.py, on el fitxer de proves prové directament dels exemples de l'spec, de manera que en modificar el codi posteriorment només cal executar les proves per verificar si l'spec s'ha trencat.

4. Efectes d'un bon spec (es poden utilitzar com a criteris d'acceptació)

Determinisme: el mateix spec donat a diferents IA (o persones) produeix implementacions similars.
Testabilitat: un cop escrit el codi, es pot verificar automàticament el 90% de la correcció.
Mantenibilitat: al cap de sis mesos, qualsevol persona que miri l'spec pot entendre les intencions de disseny originals.
Cost de comunicació baix: durant les discussions d'equip, només es parla de l'spec, no de línies de codi concretes.
Seguretat/qualitat integrades: els requisits de seguretat (com consultes parametritzades) i les condicions límit s'especifiquen a l'spec, i la IA ha de complir-los.

5. Exemple d'un bon spec (versió minimalista)

# Spec: API de registre d'usuari

## Abast
- Rep email, password
- No envia correu de verificació ni comprova la validesa del correu

## Contracte
POST /register
Content-Type: application/json
Request: { "email": string, "password": string }
Response 201: { "user_id": string }
Response 400: { "code": "INVALID_PASSWORD" | "INVALID_EMAIL" }
Response 409: { "code": "EMAIL_ALREADY_EXISTS" }

## Comportament
- L'email ha de complir el format bàsic RFC 5322 (a@b.c)
- password: longitud 8-20, almenys un número i una lletra majúscula
- Utilitza xifratge bcrypt per emmagatzemar, cost de sal 10
- Si es descobreix que l'email ja existeix abans d'emmagatzemar a la base de dades → 409

## Casos de prova (entrada -> codi d'estat esperat + camp de resposta)
| email d'entrada | password | Esperat |
|-----------------|----------|---------|
| test@x.com | Pass1234 | 201, user_id existeix |
| test@x.com | pass | 400, INVALID_PASSWORD |
| bad | Pass1234 | 400, INVALID_EMAIL |
| (email ja existent) | Pass1234 | 409, EMAIL_ALREADY_EXISTS |

## No funcionals
- Les SQL han d'utilitzar consultes parametritzades (prevenció d'injecció)
- El registre ha de registrar l'IP d'origen, sense registrar la contrasenya
- Temps de resposta: 95% de les sol·licituds < 100ms (sense incloure bcrypt)

## Dependències
- Python 3.10+, FastAPI, bcrypt, asyncpg

Un bon Spec Coding = escriure les "decisions de disseny" humanes com a "casos de prova + signatures de tipus + restriccions de comportament" per a la màquina , de manera que la IA només s'encarrega d'omplir la implementació, mentre que els humans sempre controlen la qualitat i la direcció.