Com escriure una SPEC que realment funcioni (SDD, IA i agents)

No escric specs perquè m’agradi documentar. Les escric perquè em vaig cansar de malentesos, de converses circulars i d’haver de reinterpretar decisions quan ja hi ha codi, tests i prompts en marxa. Aquesta és la manera més senzilla que he trobat d’escriure specs que després sí que es poden executar, per persones i per agents d’IA, sense burocràcia i sense soroll.

Aquest article és la continuació natural de la Guia completa de Spec-Driven Development (SDD) amb IA. Allà explicava a grans trets què és això de l’SDD i com funciona per sobre. Aquí vaig a una cosa molt més pràctica: com escriure una spec que no es trenqui tan bon punt algú la faci servir.

Per què la majoria de specs no funcionen

Podria dir que fa anys que em barallo amb specs dolentes, però seria enganyar-me a mi mateix i a tu. La realitat és que fins fa relativament poc els agents no eren prou consistents perquè compensés l’esforç d’escriure specs “de veritat”.

El 2026, però, el problema ja no és aquest. Les specs solen fallar per una cosa més bàsica: deixen massa espai a la interpretació. Semblen clares quan les escriu qui ho té tot al cap, però es tornen ambigües quan una altra persona, o un agent, intenta executar-les.

En el fons, a l’agent li passa el mateix que ens ha passat sempre als programadors quan ens arriba documentació vaga i poc definida.

En la meva experiència, quan una spec surt malament sol tenir algun d’aquests símptomes:

• Barreja requisits amb decisions tècniques
• Fa servir un llenguatge còmode, però imprecís
• Dona coses per enteses
• No deixa clar on acaba l’abast
• Deixa càlculs o límits sense definir: unitats, arrodoniments, llindars

Amb IA això no s’arregla. Es magnifica. L’agent no et preguntarà què volies dir: decidirà pel seu compte i, si et despistes, et generarà legacy des del minut zero.

Què intento aconseguir quan escric una SPEC

Amb el temps he deixat de pensar en la spec com un document i he començat a veure-la com una eina per prendre decisions abans.

Per a mi, una spec funciona quan supera una prova molt simple: al final del desenvolupament puc dir, sense discutir, si s’ha complert o no.

Quan no puc fer-ho, la discussió gairebé mai és sobre el codi. Sempre acaba sent sobre alguna cosa que vam donar per feta i que mai vam deixar per escrit.

Quan això passa, gairebé sempre hi ha una raó al darrere. Normalment alguna d’aquestes tres coses no estava ben tancada:

• El problema no estava ben acotat
• El comportament esperat no era verificable
• Les exclusions no estaven explícites

L’estructura que faig servir (i per què)

No hi ha una plantilla màgica. Cada cas necessita cura i context.

El que sí que he après és que hi ha estructures que t’obliguen a pensar millor, fins i tot quan la idea encara està verda.

La que faig servir gairebé sempre separa tres coses que convé no barrejar:

• quin problema estem resolent i en quin context,
• com s’hauria de comportar el sistema des de fora,
• i com sabrem, sense discutir, si està ben fet.

No és casualitat que aquestes capes encaixin força bé amb Requirements, Design i criteris d’acceptació. No perquè calgui seguir-les per dogma, sinó perquè et forcen a prendre decisions en l’ordre correcte.

Requirements: baixar la idea a un problema concret

Aquesta és la part menys glamurosa i, de llarg, la més important.

Aquí no intento escriure bonic. Intento eliminar ambigüitat.

Quan començo una spec, m’obligo a deixar clar:

• Quin problema concret estem resolent
• En quin context real es farà servir
• Quin objectiu volem assolir
• I, sobretot, què queda fora

Amb el temps he après que el bloc de No inclou és el que aporta més valor. No perquè limiti, sinó perquè evita que altres persones, humanes o IA, prenguin decisions que mai haurien d’haver pres.

Més d’una vegada, només omplir aquesta part ja m’ha fet adonar que la idea original no estava tan clara com semblava.

Design: descriure comportament sense decidir implementació

Aquí és on moltes specs es desvien sense que ningú se n’adoni.

L’objectiu d’aquesta secció no és dissenyar el sistema per dins, sinó descriure què ha de passar des de fora. Què passa en el flux normal, què passa quan alguna cosa falla i quins casos límit mereixen atenció.

Si en llegir aquesta part algú comença a discutir frameworks, patrons o llibreries, sol ser un senyal que la spec està barrejant nivells.

Quan l’escric bé, aquesta secció té una cosa curiosa: permet que diferents persones arribin a solucions tècniques diferents i que totes siguin vàlides.

Criteris d’acceptació: on s’acaba la discussió

Si m’hagués de quedar amb una sola part de la spec, seria aquesta.

Els criteris d’acceptació són el punt on el llenguatge deixa de ser interpretatiu i passa a ser comprovable. No descriuen com implementar res. Descriuen quan alguna cosa està bé i quan no.

Sempre els escric pensant en una pregunta molt concreta: podria algú que no va ser a la conversa decidir si això compleix la spec?

Per això evito adjectius còmodes i em recolzo en estructures simples del tipus Donat / Quan / Aleshores. No perquè sigui BDD, sinó perquè obliga a concretar.

Quan els criteris estan ben escrits, moltes discussions desapareixen soles.

Un exemple complet (i deliberadament acotat)

Nota important sobre anonimització: la spec original usada en el projecte defineix amb precisió contractual la identitat de sincronització de respostes, el model mínim del fitxer i la regla de certesa per format. En aquesta versió pública aquests detalls s’ometen deliberadament per anonimització, però en una spec executable real són obligatoris i no negociables.

Perquè tot això no quedi en teoria, faré servir una spec real que he aplicat en un projecte de feina, reescrita i anonimitzada per no exposar detalls interns ni decisions sensibles.

La versió original era una bona especificació tècnica: explicava bé el flux, l’arquitectura i els components implicats. El problema és que, com a SPEC en sentit SDD, deixava massa decisions implícites.

Aquesta és la mateixa idea, però escrita com una spec que governa decisions i que es pot executar sense interpretar ni inventar regles.

⚠️ A partir d’aquí comença la SPEC

Spec — Importació i processament de resultats d’avaluacions (pensada per treballar amb Junie)

Problema que es vol resoldre

Necessitem importar resultats d’avaluacions des de sistemes externs i persistir-los de manera consistent, garantint que:

• els resultats s’associen correctament a l’avaluació corresponent,
• no es generen duplicats en reimportar informació,
• i es preserva l’estructura i la semàntica de les respostes dels participants.

Aquest procés ha de permetre reimportacions segures i repetibles sense introduir inconsistències en les dades existents.

Context d’ús

El sistema rep fitxers generats per plataformes externes que contenen els resultats d’una avaluació. Aquests fitxers poden variar en format, però segueixen una estructura tabular coherent.

El sistema és responsable d’interpretar aquestes dades, transformar-les en entitats de domini i emmagatzemar-les com a font de veritat interna.

Objectiu

Donat un fitxer de resultats vàlid i les metadades mínimes de l’avaluació:

• el sistema importa les dades,
• crea o actualitza l’avaluació corresponent,
• i persisteix les respostes dels participants de manera consistent.

El procés ha de ser idempotent i determinista: importar el mateix fitxer més d’una vegada no ha de generar duplicats ni inconsistències.

Contracte mínim (abstracte):

• Entrades: fitxer de resultats + evaluation_external_id + metadades mínimes (definides en annex intern).
• Sortides: avaluació persistida amb respostes associades.
• Invariants: sense duplicats, ordre preservat per participant, mateix estat final després de N reimportacions.

Abast

Inclou

• Recepció d’un fitxer de resultats juntament amb metadades bàsiques de l’avaluació.
• Detecció i ús del parser adequat segons el format del fitxer.
• Transformació de les dades en entitats de domini.
• Persistència de l’avaluació i de les seves respostes associades.
• Sincronització de respostes en cas de reimportació.

No inclou

• Validació semàntica del contingut acadèmic de les respostes.
• Correcció manual o edició posterior dels resultats.
• Generació d’informes o visualitzacions.
• Gestió d’autenticació o autorització.
• Gestió avançada d’errors de format més enllà del rebuig del fitxer.

Regles de negoci rellevants

• Una avaluació s’identifica de manera única pel seu identificador extern.
• Les respostes s’associen a participants individuals.
• Identitat de resposta: definida per una clau de sincronització estable (OMÈS PER ANONIMITZACIÓ).
• Algunes files del fitxer representen valors de certesa o confiança associats a una resposta.
• Regla de certesa: determinada per una regla posicional dependent del format (OMÈS PER ANONIMITZACIÓ; vegeu annex intern de formats).
• L’ordre de les respostes és rellevant i s’ha de preservar.
• L’absència de valors de certesa no invalida una resposta.

Comportament esperat

Flux principal

1. El sistema rep un fitxer de resultats i les metadades de l’avaluació.
2. Se selecciona un parser compatible amb el format del fitxer.
3. El fitxer es processa fila a fila, transformant cada fila en una resposta de participant.
4. Les respostes s’agrupen per participant.
5. Es construeix una entitat d’avaluació que conté totes les respostes processades.
6. L’avaluació es persisteix:
   • si no existeix prèviament, es crea,
   • si ja existeix, se’n sincronitzen les respostes.

Reimportació

• Si l’avaluació ja existeix:
  • se n’actualitzen les metadades,
  • s’hi afegeixen respostes noves,
  • s’actualitzen les existents,
  • i s’eliminen les respostes que ja no apareixen al fitxer importat.

Atomicitat

• Si qualsevol fila falla durant el parseig o la transformació, es rebutja el fitxer complet i no es persisteix cap dada.

Criteris d’acceptació

• Donat un fitxer vàlid d’una avaluació inexistent, quan es processa la importació, aleshores es crea una nova avaluació amb totes les seves respostes associades.
• Donat un fitxer vàlid d’una avaluació ja existent, quan es processa la importació, aleshores no augmenta el nombre total de respostes en reimportar el mateix fitxer; per participant, el conjunt de respostes definit per la clau de sincronització és únic.
• Donat un fitxer amb un format no suportat, quan s’intenta importar, aleshores el procés falla sense persistir cap dada.
• Donada una fila que compleix la regla de posició definida per a certesa, quan es processa, aleshores la resposta es marca com a valor de certesa.
• Donat el mateix fitxer importat N vegades, quan es processa repetidament, aleshores l’estat final és idèntic: mateixos valors, mateix ordre per participant i mateix nombre total de respostes.

Restriccions

• El procés ha de ser determinista: el mateix input produeix sempre el mateix resultat.
• La importació s’ha de completar com una operació atòmica.
• El sistema ha de ser tolerant a reintents.
• El tractament de dades personals ha de complir la normativa aplicable.

Notes obertes

• La definició exacta dels formats suportats es manté fora d’aquesta spec.
• La gestió d’errors detallada es documentarà en una spec separada si cal.

⚠️ Fi de la SPEC

Descansa una mica, ja hem acabat amb l’exemple.

Com faig servir aquesta SPEC amb Junie (sense convertir-la en “prompt engineering”)

Quan tinc la spec tancada, no començo a improvisar prompts. Amb Junie això és encara més evident: l’agent viu dins de l’IDE, veu el codi i tendeix de manera natural a omplir buits si no els tanques bé.

La spec és el que evita això. No la faig servir per inspirar Junie, sinó per limitar el seu espai de decisió.

En comptes d’escriure un prompt creatiu, el que faig és llançar una tasca explícita, assumint que Junie ja té context del projecte.

Aquest és, més o menys, el text que acostumo a fer servir:

Tasca: implementar la importació de resultats d'avaluacions

Font de veritat:
- La SPEC "Importació i processament de resultats d'avaluacions" és l'única referència funcional vàlida.
- No infereixis regles que no estiguin explícites a la spec.

Context:
- Estàs treballant dins d'un projecte existent obert a l'IDE.
- L'objectiu no és redissenyar el sistema, sinó implementar exactament el comportament descrit.

Què espero de tu:
1. Implementar el flux descrit a la spec sense afegir comportament extra.
2. Identificar qualsevol ambigüitat que impedeixi implementar un criteri d'acceptació.
3. Proposar tests que validin cada criteri d'acceptació de manera verificable.

Restriccions:
- No modifiquis regles de negoci sense demanar confirmació explícita.
- No introdueixis formats nous, dreceres ni "millores".
- Mantén el comportament determinista i repetible.

Forma de treball:
- Resumeix primer la spec en passos operatius.
- Assenyala possibles punts conflictius abans de tocar codi.
- Implementa de manera incremental, validant cada criteri.

La diferència clau aquí és que Junie ja veu el codi i l’entorn, de manera que qualsevol ambigüitat a la spec es tradueix directament en decisions implícites dins de l’IDE.

⚠️ Compte amb el context global del projecte

Aquesta spec defineix què ha de passar i quan està ben fet.
No defineix com s’ha d’estructurar el projecte ni les regles generals de desenvolupament.

Per això, en projectes reals, és important tenir artefactes separats i estables (Agents.md, guidelines.md, convencions de tests, estil, etc.) on quedi clar:

• com esperem que treballi l’agent,
• quins estàndards ha de seguir,
• i quines coses no ha de decidir pel seu compte.

D’aquesta manera, la spec es manté centrada en el problema, i Junie no ha d’inferir decisions globals a partir de codi solt.

Si Junie s’equivoca, gairebé mai és perquè “la IA sigui dolenta”. És perquè la spec no va tancar una decisió que donàvem per òbvia.

Els errors que veig una vegada i una altra

Hi ha errors que es repeteixen tant que gairebé s’han normalitzat.

Specs que semblen documentació, specs que intenten dissenyar tot el sistema, specs que no diuen mai què queda fora o specs on els criteris són tan vagues que ningú s’atreveix a fer-los servir com a referència.

Cadascun d’aquests errors mereix una explicació en detall, i per això els tracto a fons a l’article específic sobre errors comuns en Spec-Driven Development.

Checklist final abans de donar una spec per vàlida

Copia i enganxa aquesta llista. Si una resposta no és un sí clar, la spec no està llesta:

• Està definit l’input mínim?
• Estan definits l’output i els seus invariants?
• Les identitats / claus estan explícites?
• Errors i atomicitat estan definits?
• Idempotència i determinisme són verificables?
• Els casos límit estan llistats?
• El No inclou és explícit?
• Els criteris tenen oracle mesurable?
• No queda res “segons el format” sense referència a un annex/spec interna?
• Es pot decidir compliment sense conversa?

Ajustar una spec aquí continua sent infinitament més barat que fer-ho quan ja hi ha codi, tests o agents en producció.

Per què aquesta spec funciona millor que una spec purament tècnica

Després de veure-la sencera, la diferència clau no és la longitud ni el format, sinó quines decisions deixa tancades i quines no.

Aquesta spec funciona millor que una spec purament tècnica perquè:

• Comença pel problema i l’objectiu, no per l’arquitectura.
• Defineix explícitament què entra i què queda fora, reduint suposicions.
• Aïlla les regles de negoci importants, protegint-les de canvis accidentals.
• Descriu comportament esperat sense imposar implementació.
• Inclou criteris d’acceptació que permeten dir, sense discutir, si alguna cosa compleix o no.
• Pot ser executada per una persona o per un agent sense inventar regles noves.

Una spec tècnica descriu el sistema. Aquesta spec governa com es prenen decisions abans d’escriure codi.