Spec-Driven Development (SDD) amb IA: guia pràctica per al 2026

Aquesta no és una definició acadèmica més sobre el SDD. Pretén ser la guia que m’hauria agradat tenir quan vaig començar a treballar amb la IA en desenvolupament de producte i em vaig adonar d’una cosa força incòmoda: el prompting sense specs no escala. Aquí explico com aplicar Spec-Driven Development amb IA de manera pràctica, sense burocràcia i amb criteris clars que després sí que es poden portar al codi

Què és el Spec-Driven Development (SDD) i per què torna ara amb la IA

Spec-Driven Development (SDD) és una idea senzilla que durant anys va ser poc pràctica: definir amb precisió què vols construir abans de posar-te a construir-ho. L’especificació (la spec) no és un tràmit, és el centre de tot.

Durant molt de temps això sonava bé en teoria, però a la pràctica fallava gairebé sempre. Els canvis d’abast d’última hora, el cost de mantenir les specs actualitzades i les presses del dia a dia feien que el codi acabés sent l’única veritat. Amb la IA, per primera vegada, això pot canviar de manera realista.

Quan treballes amb models de llenguatge, la qualitat del resultat depèn directament de la claredat del context que els dones. No del model, ni del prompt màgic, sinó del context previ que defineix què és correcte i què no. I una bona spec és, bàsicament, el millor context possible. En el meu cas, el moment “clic” va ser adonar-me que una spec clara reduïa més errors que qualsevol prompt enginyós.

Qui no ha provat alguna vegada, encara que sigui per jugar, de llançar prompts a un agent del tipus: “Actualitza aquest projecte a DDD” o “Migra a la versió X”? El resultat sol ser el mateix: consum absurd de tokens i sortides més que qüestionables, perquè l’agent no té un marc clar contra el qual decidir.

SDD no torna per nostàlgia ni per moda. Torna perquè la IA necessita instruccions estables, no converses improvisades.

Si ja tens clar què és SDD, pots anar directament a com escriure specs efectives, eines per a SDD amb IA o errors comuns en aplicar Spec-Driven Development. La resta de l’article construeix aquesta base.

El flux real de Spec-Driven Development amb IA (de la idea al codi)

A la pràctica, SDD no és un procés rígid ni burocràtic. Tampoc pretén substituir altres metodologies com DDD, TDD o BDD. Jo l’entenc més aviat com un flux mental que se superposa a la manera com ja treballem i que pren especial sentit quan entren agents d’IA a l’equació.

De la idea al problema ben formulat

Tot comença amb una idea vaga. Això és normal. L’error habitual és passar d’aquí directament al codi o al prompt.

Abans d’escriure una sola línia de spec, m’obligo a respondre una cosa molt simple: quin problema concret estem resolent i per a qui? Si no puc explicar-ho en poques frases, encara no ho entenc. I si no ho entenc jo, és impossible que un agent ho executi bé.

Aquest pas, tot i que sembla trivial, sol ser on es genera més valor. Forçar-te a formular el problema elimina ambigüitats abans que es converteixin en deute tècnic.

La spec com a contracte (no com a document bonic)

Aquí és on SDD se separa clarament d’“escriure documentació”. La spec no intenta impressionar ningú. El seu únic objectiu és evitar malentesos.

Una bona spec deixa clares tres coses fonamentals:

• Què fa el sistema
• Què no fa
• Com sabem si està ben fet

Quan vaig començar a treballar així, moltes discussions van desaparèixer. No perquè tothom estigués d’acord, sinó perquè la spec obligava a prendre decisions abans d’escriure codi.

De la spec a tasques accionables

Una spec ben escrita es pot fragmentar gairebé sola en tasques. En aquest punt la IA ajuda molt: treu a la llum casos límit, dependències i buits lògics que sovint passem per alt.

Aquí hi ha un advertiment important: si la spec és ambigua, la IA no ho arreglarà. Ho amplificarà.

Aquest procés tampoc ha de ser completament manual. En el meu cas, acostumo a treballar la spec dins d’una conversa amb ChatGPT en mode canvas, iterant secció per secció fins que el text és prou clar perquè un altre humà —o un agent— el pugui executar sense fer suposicions. Curiosament, per com funcionen els models, aquest procés sol revelar escenaris extrems o restriccions que no havíem considerat al principi.

Codi assistit per IA (amb límits clars)

Amb una spec sòlida, la IA deixa d’“inventar” i passa a executar. Genera codi, tests i estructures amb molta més coherència i menys soroll.

Una cosa que vaig aprendre ràpid és que, quan el resultat no m’agrada, gairebé mai el problema és el model. El problema sol estar en la spec. Revisar-la i ajustar-la gairebé sempre dona millors resultats que canviar d’eina o de prompt.

Validació contra la spec, no contra opinions

L’últim pas no és preguntar “funciona?”, sinó “compleix el que vam prometre?”. La spec es converteix en el criteri de veritat.

Si alguna cosa falla, no es parcheja directament el codi. Es revisa primer la spec. En més ocasions de les que sembla, l’error era allà.

Què fa que una spec sigui realment bona (criteris pràctics)

No totes les specs serveixen per treballar bé amb IA. Algunes semblen completes, ben estructurades i fins i tot “professionals”, però quan intentes utilitzar-les amb un agent comencen a fer aigües.

Amb el temps he arribat a una conclusió bastant clara: una bona spec no és la que explica més coses, sinó la que redueix al mínim el que cal interpretar.

Context que realment acota, evita floritures

El context no està per explicar la història del projecte, sinó per acotar decisions. Qui farà servir això, en quina situació i amb quines limitacions reals.

Quan una spec diu “usuari final” o “ús general”, en realitat no està dient res. En canvi, quan defineixes un context concret, la IA —i qualsevol persona de l’equip— deixa d’imaginar escenaris que no existeixen.

Una spec ha de poder fallar

Si alguna cosa que estàs definint no es pot falsar, no ho has pensat prou.

Si en acabar el desenvolupament no pots definir amb claredat si s’ha complert o no l’objectiu, aleshores no era un bon objectiu. Aquest punt, que sembla filosòfic, és especialment important quan treballem amb agents d’IA: tendeixen a completar allò que no està clarament definit i, amb això, a “al·lucinar” afegint fluxos o comportaments no previstos.

El valor real de les exclusions

Aquí és on moltes specs fallen. Dir el que no entra en abast sol semblar innecessari… fins que no es fa.

En la meva experiència, definir exclusions redueix més errors que afegir funcionalitats. Redueix el context, evita sorpreses amb canvis en el projecte i assegura que una spec poc clara no modifiqui normes de negoci que no s’haurien de tocar. Recorda que el Domini no s’adapta (i quan algú intenta que ho faci, solen passar coses interessants…).

Evita redundàncies

Per sort, els estàndards estan arribant al nostre dia a dia a l’hora de treballar amb agents. Si veus que has d’incloure a totes les specs coses com “genera tests unitaris d’aquesta o aquella manera”, el més sensat és optimitzar el treball i desplaçar aquest tipus d’instruccions a fitxers com Agents.md o guidelines.md.

D’aquesta manera, l’agent sap com ha de comportar-se des del principi, però tu no has de repetir sempre els mateixos blocs de text. La spec es manté centrada en el problema i el comportament, que és on realment aporta valor.

Com encaixen els rols en un equip que treballa amb Spec-Driven Development

Una de les trampes més habituals en parlar de SDD és descriure’l com “més documentació”. En un equip real, el canvi no està en escriure més, sinó en moure el punt on es prenen les decisions importants.

Quan la spec és el centre, moltes friccions clàssiques desapareixen o, com a mínim, apareixen abans, quan encara són barates de resoldre.

PM / Producte: la spec com a eina d’alineació (no com a entregable)

Producte no escriu una spec per “passar la pilota” a desenvolupament. La spec és la seva eina principal per alinear tot l’equip al voltant de tres coses molt concretes:

• quin problema s’està resolent,
• què entra i què queda explícitament fora,
• i què significa exactament que alguna cosa estigui ben feta.

En equips que treballen amb IA això es nota moltíssim. Una spec poc acotada es converteix ràpidament en prompts interminables, decisions implícites i canvis de direcció a mig camí. Una spec clara, en canvi, redueix soroll i fa visibles les decisions des del principi.

Dev: menys interpretació, més disseny conscient

La feina del developer deixa de ser “endevinar què volia dir producte”. El seu rol passa a tensionar la spec amb preguntes incòmodes però necessàries:

• quin cas límit estàs assumint sense dir-ho?
• quina dependència implícita hi ha aquí?
• quina restricció tècnica fa que això sigui inviable, fràgil o car?

La clau és que aquestes converses passen abans que existeixi codi. Amb IA, aquest punt és crític: com més tard apareix una ambigüitat, més car és corregir-la.

QA: convertir ambigüitat en verificacions

QA deixa d’arribar al final per “trencar coses”. En SDD entra abans per transformar llenguatge imprecís en criteris comprovables:

• escenaris crítics,
• casos negatius (el que NO ha de passar),
• i proves que validen comportament, no implementació.

Una regla pràctica que faig servir és aquesta: si una spec no es pot testejar, probablement no està llesta per implementar-se.

La IA: executa ràpid, interpreta malament

Jo tracto la IA com un membre de l’equip amb dues característiques molt clares:

• és extremadament ràpida executant, i
• és perillosament bona omplint buits.

La spec existeix precisament per reduir aquest espai d’interpretació. No per limitar la IA, sinó per evitar que prengui decisions que mai haurien d’haver estat seves.

Checklist pràctic abans de donar una spec per “llesta”

Aquesta és, probablement, la part menys glamurosa del procés… i també una de les més útils. No és un checklist per complir per complir, sinó una última revisió ràpida per detectar ambigüitats abans que es converteixin en feina extra.

Aquest és el checklist que faig servir quan vull evitar sorpreses (humanes o d’IA):

• El problema s’entén sense context addicional?
  Si algú que no ha estat a la conversa original no ho entén, un agent tampoc.
• L’objectiu pot fallar?
  Podries dir amb claredat “això no compleix la spec”? Si no, hi ha ambigüitat.
• Està explícit què NO entra en abast?
  Si no hi ha exclusions clares, algú (humà o IA) les inventarà.
• Els criteris d’acceptació són verificables i binaris?
  Res de “hauria de”, “idealment” o “més o menys”. O passa, o no passa.
• Hi ha exemples suficients per als fluxos importants?
  Almenys un per flux crític. Els exemples redueixen interpretació més que qualsevol definició.
• La spec descriu comportament, no implementació?
  Si estàs decidint arquitectura aquí, probablement estàs barrejant nivells.
• Un agent podria executar aquesta spec sense fer-te preguntes?
  Aquesta és la prova final. Si la resposta és no, la spec encara no és madura.

Regla pràctica: si alguna casella queda en dubte, no passa res. Tornar a la spec ara és infinitament més barat que fer-ho quan ja hi ha codi, tests o prompts en producció.

Si alguna resposta és “no”, no passa res: tornes a la spec. És infinitament més barat ajustar aquí que fer-ho quan ja hi ha codi, tests o prompts muntats.

Plantilla simple de spec (la que faig servir de veritat)

La plantilla importa menys que la disciplina d’utilitzar-la sempre. Aquesta és la que acostumo a fer servir perquè m’obliga a pensar en exclusions i criteris d’acceptació des del principi:

Títol

Problema que es vol resoldre

Context d’ús

Objectiu

Abast
- Inclou
- No inclou

Comportament esperat
- Flux principal
- Fluxos alternatius / casos límit

Criteris d’acceptació
- Donat / Quan / Aleshores

Restriccions
- Tècniques / negoci / seguretat

Notes
- Decisions obertes / dubtes

Si t’obligues a omplir No inclou i almenys 2–3 criteris d’acceptació verificables, ja vas per davant del 90% de les specs que veig per aquí.

Exemple real: spec per al registre d’un usuari (backend)

Per evitar ambigüitats i centrar-nos en l’important, aquest exemple està deliberadament enfocat en el procés backend, no en la UI. La idea és mostrar com una spec clara permet implementar la lògica sense discutir detalls de frontend.

Títol
Registre d’usuari (backend)

Problema que es vol resoldre
Permetre que un sistema creï comptes d’usuari de manera segura i consistent, garantint la integritat de les dades i evitant registres duplicats.

Context d’ús
Servei backend que rep peticions de registre des de diferents clients (web, mòbil, API externa). El backend és l’única font de veritat per a la creació d’usuaris.

Objectiu
Donat un email i una contrasenya vàlids, el sistema crea un nou usuari persistent i deixa el compte en estat pendent de verificació.

Abast
- Inclou:
  - Endpoint de registre d’usuari
  - Validació d’email únic
  - Validació de contrasenya segons política definida
  - Persistència de l’usuari
  - Emissió d’esdeveniment de "usuari registrat"
- No inclou:
  - Renderització de formularis
  - Gestió de sessió o login
  - Enviament del correu de verificació
  - Recuperació o canvi de contrasenya

Comportament esperat
- El sistema rep una sol·licitud de registre amb email i contrasenya
- Verifica que l’email no existeixi prèviament
- Valida la contrasenya segons les regles establertes
- Emmagatzema la contrasenya de manera segura (hash)
- Crea l’usuari amb estat "pending_verification"
- Publica un esdeveniment de domini indicant que l’usuari ha estat registrat

Criteris d’acceptació
- Donat un email no registrat i una contrasenya vàlida, quan es processa la sol·licitud, aleshores es crea un nou usuari en estat "pending_verification"
- Donat un email ja existent, quan es processa la sol·licitud, aleshores no es crea cap usuari i es retorna un error de conflicte
- Donada una contrasenya que no compleix la política, quan es processa la sol·licitud, aleshores no es crea l’usuari i es retorna un error de validació

Restriccions
- El hash de la contrasenya ha de complir els estàndards de seguretat del sistema
- L’endpoint ha de ser idempotent davant de reintents
- El sistema ha de complir el RGPD en el tractament de l’email

Notes
- L’enviament del correu de verificació es gestiona en un altre servei
- El format exacte de l’esdeveniment es defineix en una spec separada

Aquest exemple mostra com una spec centrada en backend redueix discussions innecessàries i permet a humans i agents implementar la lògica sense haver d’inferir responsabilitats que no els corresponen.