Desenvolupament dirigit per especificació: una guia amb SDD i GSD

Qualsevol que hagi treballat unes hores seguides amb un agent de codi coneix el moment. Les primeres dues hores van bé. A la tercera, l’agent comença a refer coses que ja estaven fetes, a contradir decisions que havíeu pres al principi, o a resoldre un problema diferent del que li havies plantejat.

La reacció habitual és culpar el model. Però el mecanisme és més avorrit: la finestra de context s’ha omplert de conversa. Discussió acumulada, decisions a mitges, intencions antigues que ja no valen i codi que després es va canviar. Al final, la senyal —què s’ha de construir i per què— queda ofegada pel soroll de com hi heu arribat. En anglès en diuen context rot.

El desenvolupament dirigit per especificació —spec-driven development, SDD— és la resposta a això, i es resumeix en una frase: l’artefacte que sobreviu no és la conversa, és l’especificació.

Què és realment SDD

Durant dècades, l’especificació ha estat un document que es redactava, s’aprovava i s’oblidava en una carpeta mentre el codi seguia el seu camí. SDD inverteix la relació: l’especificació és el que genera la implementació, i el codi és una sortida seva.

Això funciona ara i no abans per una raó concreta: fins fa poc no hi havia res que sabés llegir una especificació en llenguatge natural i convertir-la en codi. Ara sí, i això canvia què val la pena escriure. Una especificació prou precisa perquè un agent la implementi sense haver d’endevinar la intenció ha deixat de ser burocràcia i ha passat a ser el que executa.

Els principis són tres:

1. L’especificació és la font de veritat. Si el codi i l’especificació no diuen el mateix, el que està malament és el codi.
2. Ha de ser prou concreta per ser executable. Si l’agent ha de prendre decisions sobre la intenció, l’especificació no està acabada.
3. Cada fase deixa un document, no un historial de xat. El document sobreviu al reinici del context; la conversa no.

La forma canònica del cicle

L’eina que va popularitzar el patró és Spec Kit, de GitHub, i val la pena conèixer-ne el vocabulari perquè s’ha convertit en l’estàndard de fet:

La separació entre spec i plan és el punt fi de tot plegat, i el que més costa a la pràctica: l’especificació descriu el problema, el pla descriu la solució. Barrejar-los és el que fa que acabis amb un document que ningú pot revisar perquè no se sap quina part és el requisit i quina l’opinió tècnica.

La constitution és la part més infravalorada. És on escrius coses com «tot el que toqui diners ha de tenir proves», «no s’afegeixen dependències sense justificar-ho» o «res es desplega sense una manera de revertir-ho». L’agent les té presents a cada fase, i deixes de repetir-les a cada conversa.

GSD: SDD amb la memòria resolta

GSD —Git. Ship. Done, hereu del projecte que es deia Get Shit Done— agafa aquest cicle i hi afegeix la part que Spec Kit deixa oberta: què passa quan el projecte és més llarg que una finestra de context.

La seva aposta té dues peces.

La primera: els executors comencen nets. Cada pla s’executa en un subagent amb el context buit —uns 200.000 tokens disponibles— que llegeix només els documents d’aquella fase. La sessió principal no acumula res. Això vol dir que la fase 12 s’executa amb la mateixa qualitat que la fase 1, cosa que no passa en una conversa llarga.

La segona: l’estat viu en fitxers, no a la memòria. Un directori .planning/ amb documents llegibles per una persona, versionats amb git com qualsevol altra cosa del repositori.

.planning/
├── PROJECT.md
├── REQUIREMENTS.md
├── ROADMAP.md
├── STATE.md
├── research/
└── phases/
    └── 01-fonaments/
        ├── 01-CONTEXT.md
        ├── 01-PLAN.md
        ├── 01-SUMMARY.md
        ├── 01-UAT.md
        └── 01-VERIFICATION.md

A l’arrel: PROJECT.md diu de què va això, REQUIREMENTS.md porta els requisits i el seu seguiment, ROADMAP.md les fases i les fites, i research/ la recerca prèvia. Dins de cada fase: CONTEXT.md són les decisions preses abans de planificar, PLAN.md el pla executable, SUMMARY.md què s’ha fet realment, UAT.md què ha de comprovar una persona i VERIFICATION.md el resultat d’haver-ho comprovat.

STATE.md és la peça central. Quan tanques el portàtil dimarts i el tornes a obrir dijous, no has de recordar res ni rellegir cap conversa: el document diu en quina fase ets, què està fet i què ve després.

La guia: com es treballa amb això

0. Instal·lar-ho

npx @opengsd/gsd-core@latest

L’instal·lador pregunta quin entorn fas servir —Claude Code, Codex, Cursor, OpenCode, Gemini CLI i uns quants més— i on l’instal·les. Són fitxers de configuració i ordres; no hi ha cap servei ni cap compte.

Després, segons on siguis:

/gsd-new-project     # projecte nou
/gsd-onboard         # projecte que ja existeix

El segon recorre el codi que ja tens i genera el PROJECT.md i el ROADMAP.md a partir d’ell, en comptes de fer-te’ls escriure.

1. Partir la feina en fases

Aquesta és la decisió que determina si tot plegat funciona, i la fas tu, no l’eina.

Una fase ha de complir tres condicions:

• Cap dins d’un context net. Si per planificar-la cal llegir mig repositori, és massa gran.
• Té un final comprovable. «Millorar el rendiment» no és una fase. «La pàgina de llistat carrega en menys d’un segon amb 10.000 registres» sí.
• Es pot enviar sola. Si tres fases han d’arribar juntes per no trencar res, en realitat n’hi ha una.

La temptació és fer fases grans perquè sembla que van més ràpid. Passa el contrari: una fase gran es planifica malament, s’executa amb el context ja mig ple i es verifica pitjor.

2. El cicle, fase a fase

Per a cada fase es repeteixen cinc passos:

/gsd-discuss-phase    # preguntes fins que no queda ambigüitat
/gsd-plan-phase       # recerca, descomposició i comprovació que el pla hi cap
/gsd-execute-phase    # execució en onades paral·leles, cada executor net
/gsd-verify-work      # es recorre el que s'ha construït i es diagnostica
/gsd-ship             # PR, arxivat de la fase, següent

Discuss és el pas que la gent es vol saltar i el que més estalvia. L’agent pregunta —adaptativament, no amb un formulari— fins que les decisions estan preses: què passa amb els casos límit, quin comportament s’espera quan falla, què queda explícitament fora. Tot això acaba a 01-CONTEXT.md. Cada pregunta que respons aquí és una decisió que l’agent no haurà d’inventar-se després.

Plan investiga el codi existent, descompon la feina i —això és el detall que importa— comprova que el pla càpiga en una finestra neta. Si no hi cap, et diu que partexis la fase. És el mecanisme que impedeix que et facis trampes.

Execute llança els plans en paral·lel. Cada executor arrenca sense saber res de la conversa que hi ha hagut: només llegeix els documents de la seva fase.

Verify no és passar les proves. És recórrer el que s’ha construït, contrastar-ho amb el que deia l’especificació i generar plans de correcció per al que no hi encaixa, abans de donar la fase per bona. Hi ha un 01-UAT.md amb el que ha de comprovar una persona, perquè hi ha coses que no les valida cap prova automàtica.

Ship genera el PR amb el cos escrit a partir del que realment s’ha fet, arxiva la fase i deixa el terreny net per a la següent.

Si et perds, hi ha dues ordres que fan de brúixola: /gsd-next, que mira l’estat i et diu quin és el pas següent, i /gsd-progress, que t’ensenya on ets i avança. I per a les interrupcions de la vida real, /gsd-pause-work desa el traspàs de context i /gsd-resume-work el recupera.

Per a la feina petita que no mereix una fase sencera hi ha /gsd-quick, i per a diagnosticar un error amb estat persistent, /gsd-debug.

3. Escriure una especificació que serveixi

Aquesta part no la fa l’eina i és on es guanya o es perd. Una especificació executable ha de contenir:

• El contracte de dades. Noms exactes, tipus, valors possibles, què és obligatori. Sense això, l’agent s’inventa noms de camps que després no casen amb res.
• El comportament als extrems. Què passa amb zero elements, amb 100.000, amb un valor nul, amb dos usuaris fent el mateix alhora.
• Què passa quan falla. No «gestiona els errors», sinó quin error, quin missatge, què es reintenta i què no.
• El criteri d’acabat. Una frase comprovable. Si no es pot comprovar, no és un criteri.
• Què queda fora. Sovint el més valuós. Sense això, l’agent afegeix coses «útils» que ningú ha demanat i que després s’han de mantenir.

La prova és sempre la mateixa, i és la que ja fem servir per demanar codi a un model: si el que has escrit no permetria a una persona nova fer la feina sense preguntar-te res, tampoc en té prou un agent.

Què costa això

Per honestedat, perquè el mètode no és gratis:

Escriure especificacions és feina. Una fase ben especificada pot ser una hora abans de tocar codi. Es recupera de sobres en projectes de setmanes; en una tarda de feina, no.

Genera molts documents. El .planning/ d’un projecte mitjà són desenes de fitxers. Van al repositori i s’han de mantenir amb la mateixa disciplina que el codi, o al cap d’un mes menteixen — i una especificació que menteix és pitjor que no tenir-ne.

L’eina evoluciona ràpid. GSD ha canviat de nom i de casa aquest mateix any: el repositori original es va arxivar el juny i el projecte continua com a GSD Core. Les ordres concretes d’aquest article poden haver canviat quan el llegeixis; el que no canviarà és el patró de sota.

No és per a tot. Per a un script de 200 línies, per a un arreglo puntual o per a explorar una idea que encara no saps si vols, tot això és sobrecàrrega. El senyal per començar a fer-ho servir és molt concret: quan la feina no cap en una sola sessió.

El que t’has d’endur

Encara que no facis servir cap eina de les que surten aquí, el patró es pot aplicar demà:

1. Escriu què s’ha de fer abans de demanar-ho, amb noms, tipus i casos límit.
2. Separa el problema de la solució en dos documents diferents.
3. Parteix la feina en trossos que càpiguen en una sessió, amb un final comprovable cadascun.
4. Deixa l’estat en un fitxer, no a la conversa.
5. Verifica contra l’especificació, no contra el record del que volies.

Els cinc punts són el mateix que fa que un procés automatitzat aguanti quan la persona que el va muntar ja no hi és. No és casualitat: el problema és idèntic. El que sobreviu és el que està escrit en algun lloc que no depèn de la memòria de ningú.