El mantra de les startups és conegut: "ship fast, learn fast". Construeix un MVP en setmanes, posa'l davant d'usuaris, itera. El problema no és la velocitat. El problema és el que passa quan aquest MVP, construït sobre suposicions no documentades, ha d'escalar, integrar-se amb agents d'IA o sobreviure al primer pivot. El 80% del rework en programari s'origina en defectes de requisits. I un MVP sense especificació és, per definició, un producte construït sobre requisits implícits.
Spec-Driven Development (SDD), també conegut com a desenvolupament guiat per especificacions, no proposa tornar al waterfall ni escriure documents de 100 pàgines abans de programar. Proposa una cosa més precisa: documentar les decisions que ja estàs prenent, en un format que tant humans com agents d'IA puguin consumir. La diferència entre un MVP que valida i un que genera mesos de rework és, gairebé sempre, en aquestes decisions no escrites.
El cost ocult dels MVPs sense especificació
Quan un equip construeix un MVP sota pressió de temps, es produeix un patró predictible: els requisits s'assumeixen en lloc de documentar-se. El frontend assumeix una estructura de dades. El backend assumeix un flux d'usuari. QA assumeix criteris d'acceptació. I ningú descobreix les inconsistències fins a 3-5 setmanes després, quan les peces no encaixen.
Les dades són contundents:
- El 30-50% de l'esforç total en projectes de programari es destina a rework (Boehm & Papaccio)
- El 80% d'aquest rework és atribuïble a defectes en requisits (Info-Tech Research Group)
- Un error de requisits costa 8x més corregir en disseny, 16x en codi i 29x en producció (NASA)
- Cada euro invertit a millorar processos de requisits retorna entre 3x i 7,5x (Carnegie Mellon SEI)
En un MVP típic de 8-12 setmanes, això es tradueix en 3-5 setmanes addicionals de redisseny no planificat. No perquè l'equip sigui dolent, sinó perquè les suposicions no documentades divergeixen entre persones. I quan introdueixes agents d'IA en aquest procés, el problema es multiplica.
Per què la IA amplifica el problema
Un agent d'IA com Claude Code o GitHub Copilot no té intuïció. No "sap" que el CTO volia un flux de pagament en dos passos, no en tres. No dedueix que l'API ha de ser RESTful perquè l'equip de mobile ho necessita. Sense especificació, l'agent genera codi basat en patrons estadístics, no en decisions de producte.
Quan equips amb processos de requisits immadurs integren IA, no redueixen el rework: l'acceleren. Com assenyala Thoughtworks en la seva anàlisi de SDD per al Technology Radar, la IA produeix solucions errònies més ràpid quan no té especificacions que la guiïn. El resultat és més codi per refactoritzar, no menys.
Quan una especificació és "prou formal" per a la IA
El biaix del "Quick Ship" assumeix que especificar és el contrari de ser àgil. Que escriure una spec abans de programar és perdre temps. Però una especificació útil per a SDD no s'assembla a un document de requisits de 100 pàgines. S'assembla a això:
## Feature: Checkout simplificat ### Problema El 34% d'usuaris abandona al pas de pagament. Necessitem reduir fricció sense comprometre seguretat. ### Restriccions - Màxim 2 passos (dades + confirmació) - Passarel·la: Stripe (ja integrada) - No emmagatzemar dades de targeta (PCI compliance) - API REST, endpoint POST /api/checkout ### Criteris d'acceptació - [ ] L'usuari completa la compra en menys de 60 segons - [ ] L'error de pagament mostra un missatge clar, no un codi HTTP - [ ] Funciona en mobile (viewport 375px+) ### Integració - Fa servir el component Button existent de /ui/Button - Segueix el patró d'estat de /hooks/useAsync - Tests amb Vitest, mínim 80% cobertura
Això és una especificació suficient per a SDD. No 100 pàgines. Són 20 línies que expliciten les decisions que l'equip ja havia pres mentalment però no havia escrit. La diferència és que ara un agent d'IA pot llegir-les i generar codi que respecti aquestes restriccions.
Els tres nivells de formalitat
- Nivell 1 - Prosa estructurada: Markdown amb seccions clares (problema, restriccions, criteris). Suficient per al 80% de features d'un MVP. 10-15 minuts d'escriptura.
- Nivell 2 - Contractes d'API: OpenAPI per a endpoints, schemas JSON per a models de dades. Necessari quan hi ha múltiples consumidors (mobile, web, agents). 30-60 minuts.
- Nivell 3 - Comportament formal: Gherkin per a fluxos crítics, state machines per a workflows complexos. Reservat per a lògica de negoci on un error té impacte financer o regulatori. 1-2 hores.
Cas: de 7 sprints a 3 sprints amb SDD + Claude Code
Context: SaaS B2B, equip de 6 developers, producte en fase de creixement post-MVP. Estaven reconstruint el mòdul de facturació per suportar múltiples divises i compliment fiscal europeu.
Sense SDD (estimació original): 7 sprints
- Sprint 1-2: Desenvolupament del core de facturació amb Copilot (prompts ad hoc)
- Sprint 3: Descobreixen que el model de dades no suporta divises múltiples correctament
- Sprint 4: Redisseny del schema + migració de dades
- Sprint 5-6: Reimplementació parcial + tests
- Sprint 7: Integració, QA, hotfixes
Patró clàssic: Els sprints 3-4 són pur rework. L'equip no va definir formalment les restriccions de multidivisa abans de començar. Copilot va generar codi que assumia una sola divisa perquè cap prompt ho va especificar.
Amb SDD: 3 sprints
- Setmana prèvia: 3 dies escrivint especificacions (model de dades multidivisa, regles fiscals per país, contractes d'API amb OpenAPI, criteris d'acceptació en Gherkin per a fluxos crítics)
- Sprint 1: Claude Code genera el schema, els endpoints i els tests base a partir de les specs. Revisió humana: 70% del codi acceptat sense canvis
- Sprint 2: Lògica de negoci i regles fiscals. La "constitució" del projecte (regles immutables) evita que la IA generi dreceres que violin compliance
- Sprint 3: Integració, QA, deploy. Sense redissenys perquè les decisions crítiques estaven documentades des del dia 1
Comparativa: sense SDD vs amb SDD
Els 3 dies d'especificació van estalviar 4 sprints de rework. ROI: 15x sobre el temps invertit en specs.
Matriu: quan SDD és ROI positiu vs overhead
SDD no sempre és la resposta correcta. Hi ha contextos on l'overhead d'escriure especificacions no compensa. Aquesta matriu t'ajuda a decidir:
| Escenari | SDD recomanat | Per què |
|---|---|---|
| MVP amb integració d'IA agèntica | Sí | Els agents necessiten context explícit. Sense spec, generen codi que no encaixa amb les decisions de producte. |
| Feature complexa (múltiples integracions, compliance) | Sí | Cost d'error alt. Una spec d'1-2 hores estalvia setmanes de redisseny. |
| Equip de 4+ developers en la mateixa feature | Sí | La spec és la font de veritat compartida. Redueix malentesos entre membres. |
| Landing page o canvi de copy | No | Baix risc, baix cost d'error. Un prompt directe és suficient. |
| Prototip llençable per validar una hipòtesi | No | Si saps que el llençaràs, no inverteixis a formalitzar-lo. Un prompt ad hoc és correcte. |
| Bugfix aïllat en codi existent | No | El context és al codi. La IA pot entendre'l directament. |
| MVP que escalarà post-validació | Sí | El cost de no especificar es paga amb interessos quan cal escalar el MVP validat. |
| Refactoring de codi legacy amb IA | Sí | La IA necessita saber què mantenir i què canviar. Sense spec, toca el que no ha de tocar. |
Regla general: Si el cost d'un error supera les 4 hores de rework, o si més de 2 persones (humanes o agents) treballaran en la mateixa feature, SDD és ROI positiu. Per sota d'aquest llindar, un prompt ben escrit és suficient.
Eines lleugeres per escriure specs
No necessites programari especialitzat per practicar SDD. Les millors especificacions per a MVPs s'escriuen amb eines que ja tens:
1. Prosa estructurada en Markdown
El format més accessible. Un fitxer .md amb seccions clares: problema, restriccions, criteris d'acceptació, integració. Funciona amb qualsevol agent d'IA (Claude Code, Copilot, Cursor) perquè és text pla que s'inclou com a context.
Quan fer-lo servir: Per al 80% de les features d'un MVP. És ràpid d'escriure (10-15 minuts) i prou formal perquè un agent generi codi consistent.
2. OpenAPI per a contractes d'API
Si el teu MVP té una API (i gairebé tots en tenen), una especificació OpenAPI és el contracte que connecta frontend, backend i qualsevol agent d'IA que consumeixi o generi endpoints. Els agents moderns interpreten OpenAPI directament i generen codi que respecta el schema.
Quan fer-lo servir: Quan hi ha múltiples consumidors de la teva API (app mobile, web, integracions de tercers) o quan un agent d'IA generarà tant el backend com el frontend.
3. Gherkin per a fluxos crítics
Gherkin (Given-When-Then) no és només per a testing. És un format que descriu el comportament esperat de manera que tant humans com IA l'entenen sense ambigüitat. Ideal per a fluxos on un error té impacte real: pagaments, registre, permisos.
Feature: Checkout amb múltiples divises
Scenario: L'usuari completa la compra en EUR
Given un usuari amb carret de 3 productes
And la divisa seleccionada és EUR
When confirma el pagament amb Stripe
Then el càrrec es processa en EUR
And rep confirmació per email en menys de 30 segons
Scenario: El fallo de pagament mostra un error comprensible
Given un usuari al pas de confirmació
When el pagament falla per fons insuficients
Then veu el missatge "El teu banc ha rebutjat el pagament"
And no veu codis d'error tècnics 4. "Constitució" del projecte
Un document breu (20-40 línies) que defineix les regles immutables del projecte: patrons d'arquitectura, convencions de naming, dependències permeses, estructura de carpetes. Aquest document es carrega com a context permanent a l'agent d'IA (el que en la disciplina de context engineering s'anomena "context curat"), assegurant que tot el codi generat respecti els estàndards de l'equip.
Exemple d'eines: CLAUDE.md per a Claude Code, .github/copilot-instructions.md per a Copilot, .cursorrules per a Cursor. El format varia, la funció és la mateixa.
5. onext SDD Accelerator
Accelerador desenvolupat per onext (sobre estàndards oberts, sense lock-in) que integra SDD directament en el flux de treball de l'equip. Genera templates d'especificació adaptats a l'stack del projecte, valida que el codi generat per IA compleixi les restriccions definides a la spec, i manté la "constitució" del projecte sincronitzada amb l'agent. Dissenyat per a equips que fan servir Claude Code, Copilot o Cursor com a agents principals.
El biaix del "Quick Ship" i com neutralitzar-lo
El biaix del Quick Ship és una trampa cognitiva: els equips prioritzen la velocitat percebuda (línies de codi escrites, features "acabades") sobre la velocitat real (features que funcionen correctament en producció sense rework posterior).
Amb l'arribada de la IA agèntica, aquest biaix s'intensifica. Un agent pot generar milers de línies de codi en minuts. La temptació de "ja ho arreglarem després" és més gran que mai. Però el cost d'arreglar-ho després també és més gran, perquè l'agent ha construït capes sobre capes de suposicions incorrectes.
Tres senyals que el teu MVP pateix el biaix del Quick Ship
- Els pull requests generats per IA requereixen més de 2 rondes de revisió. Si l'agent no entén el context, genera codi que necessita correcció constant. Això no és velocitat, és rework disfressat.
- Diferents developers implementen la mateixa lògica de formes diferents. Sense especificació compartida, cada persona (i cada agent) pren decisions de disseny diferents. El resultat és un codebase inconsistent que es torna exponencialment més difícil de mantenir.
- L'equip descobreix "sorpreses" en integració. El frontend esperava un format de dades. El backend en retorna un altre. L'API assumia autenticació per token, el mobile l'esperava per cookie. Cada sorpresa és una decisió no documentada.
SDD no és waterfall. És disciplina mínima.
Thoughtworks, en la seva anàlisi de SDD per al Technology Radar, adverteix d'un risc real: que els equips confonguin SDD amb un retorn al big design up front. És una preocupació vàlida.
"Dins de pràctiques emergents com l'spec-driven development, hem notat el risc de revertir a antipatrons clàssics d'enginyeria de programari, especialment el biaix cap a especificació pesada up-front i releases big-bang."
— Thoughtworks, Technology Radar Vol. 33
La resposta és en la proporcionalitat. Una spec de 20 línies per a una feature d'un MVP no és waterfall. És la mateixa disciplina que apliquem quan escrivim un test abans de programar (TDD). Ningú argumenta que escriure tests és "overhead" incompatible amb l'agilitat. Les especificacions per a IA en són l'equivalent: documentar la intenció abans d'executar.
L'objectiu no és documentar-ho tot. És documentar prou perquè les decisions crítiques no quedin al cap d'una persona (o pitjor, a la inferència estadística d'un LLM).
Com començar amb SDD al teu pròxim MVP
No necessites adoptar SDD de manera completa per veure resultats. Aquests són els passos per començar:
Pas 1: Identifica les 3-5 decisions crítiques del MVP
Abans d'escriure codi, llista les decisions que, si es prenen malament, generaran més rework. Normalment són: model de dades, contractes d'API, fluxos d'usuari crítics, i restriccions tècniques (compliance, performance, integracions).
Pas 2: Escriu una spec lleugera per a cadascuna
Fes servir prosa estructurada en Markdown. 15-20 línies per spec. Inclou: problema, restriccions, criteris d'acceptació, integració amb codi existent. Temps total: 2-4 hores per a un MVP típic.
Pas 3: Crea la "constitució" del projecte
Un fitxer amb les regles immutables: patrons d'arquitectura, convencions de naming, dependències permeses. Aquest fitxer es carrega com a context al teu agent d'IA. Temps: 1-2 hores, una sola vegada.
Pas 4: Fes servir les specs com a input per a l'agent
En lloc d'escriure prompts ad hoc, referencia la spec en demanar a Claude Code o Copilot que generi codi. L'agent produeix codi que respecta les restriccions documentades.
Pas 5: Revisa contra la spec, no només contra el codi
En code review, la primera pregunta no és "el codi està ben escrit". És "el codi compleix l'especificació". Si no hi ha spec, aquest és el primer problema a resoldre.
Inversió total: 1-2 dies d'especificació abans de començar a programar. Retorn típic: 3-5 setmanes de rework evitat. ROI conservador: 10-15x sobre el temps invertit.
Conclusió: la velocitat real no es mesura en línies de codi
El biaix del Quick Ship ens ha ensenyat a mesurar la velocitat en features shipped, línies escrites, sprints completats. Però la velocitat que importa és una altra: quant triga una feature a funcionar correctament en producció, sense rework posterior, i a mantenir-se estable al llarg del temps.
SDD no alenteix l'entrega. Elimina les iteracions destructives que l'alenteixen. Els equips que l'adopten no escriuen menys codi. Escriuen el codi correcte abans, i eviten escriure el mateix codi tres vegades.
En un món on els agents d'IA poden generar milers de línies en minuts, l'habilitat més valuosa ja no és programar ràpid. És especificar amb precisió què cal construir. Això és Spec-Driven Development. I això és el que separa els equips que entreguen dels que refan feina.
2 dies d'especificacions eviten 5 setmanes de rework. Els números parlen sols.
Jordi García és Tech Lead a onext. Treballa a portar la IA a producció governada en equips de desenvolupament i de producte —amb Spec-Driven Development, enginyeria de context i verificació humana a cada pas— i signa els insights tècnics d'onext sobre mètode, qualitat i cost de la IA aplicada.
LinkedIn →