¿Qué es Spec-Driven Development? Una guía práctica (y cuándo no usarlo)
Spec-Driven Development es el método con el que entregué una fintech cripto de 13 apps en 70 días, solo, con agentes de IA. Qué es una spec, los cuatro pilares, un ejemplo completo, el formato EARS y cuándo no usarlo.
La especificación no es documentación. Es la memoria que tu agente de IA no tiene. Escríbela, o el agente reinventa tus decisiones en cada ejecución.
Llevo 25 años poniendo código en producción. A finales de 2025 usé spec-driven development para construir una fintech cripto completa, 13 apps con 3 APIs, 3 bases de datos y Kubernetes en producción, en 70 días, solo, con agentes de IA. El caso de estudio tiene los números reales. Este texto es el método.
Hay algo que nadie que te venda una herramienta te va a decir sin rodeos: la empresa que hace el modelo que usas ya te dijo que hicieras esto. La guía de la propia Anthropic para Claude Code es planificar antes de programar. La mayoría de los devs se salta ese paso, ve al agente producir algo rápido y equivocado, y le echa la culpa al modelo. El modelo está bien. Lo que falta es proceso.
Spec-driven development, definido
Esa inversión es toda la idea. Parece burocracia hasta que recuerdas para quién escribes ahora. No es el próximo mantenedor humano. Es un colaborador que olvida todo en el momento en que termina la sesión.
Quien hace el modelo te dice que planifiques primero
Olvida los blogs de proveedores un segundo y lee el manual de quien hace el modelo. Las buenas prácticas de Claude Code, de Anthropic, describen un ciclo de cuatro pasos: explorar, planificar, implementar, hacer commit. El producto tiene un plan mode dedicado, cuyo único trabajo es impedir que el agente escriba código mientras piensa. El ingeniero que creó Claude Code dice que la mayoría de sus sesiones empiezan en plan mode.
Su razonamiento es directo. En palabras de Anthropic, “dejar que Claude salte directo al código puede producir código que resuelve el problema equivocado”. Y sobre lo que contiene una buena spec: “las specs más útiles son autocontenidas: nombran los archivos y las interfaces involucradas, dicen qué queda fuera del alcance y terminan con un paso de verificación de punta a punta que prueba que la feature funciona.”
Hasta publican el prompt. Esta es la plantilla de la propia Anthropic para convertir una idea en una spec antes de que exista una línea de código:
I want to build [brief description]. Interview me in detail using the
AskUserQuestion tool. Ask about technical implementation, UI/UX, edge
cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the
hard parts I might not have considered. Keep interviewing until we've
covered everything, then write a complete spec to SPEC.md.Después abres una sesión nueva y ejecutas la spec. Eso es spec-driven development en tres frases, dicho por quienes entrenaron el modelo. Todo lo que sigue es cómo hacerlo bien.
El problema es la memoria, no la inteligencia
Contrata al albañil más rápido del mundo. Muros en minutos, plomería en segundos, techo antes del almuerzo. Pero olvídate del plano. Te queda una casa que se sostiene, con el baño donde iba la cocina y una escalera que termina en la pared. Claude Code, Cursor, Copilot: ese es el albañil. La velocidad nunca fue el problema. La dirección sí.
La causa de fondo no es que el agente sea tonto. Es que el agente no tiene memoria entre sesiones. Cada conversación empieza de cero. No recuerda la decisión que tomaste ayer ni la restricción que acordaron la semana pasada.
Por eso la falla se esconde hasta que sale cara. El código compila. La sintaxis es perfecta. Solo que resuelve un problema que nunca describiste del todo, con supuestos que nunca hiciste. Código de pagos llega a producción sin clave de idempotencia. Un retry le cobra dos veces a un cliente. Parchas el código. La próxima vez que el agente regenera ese módulo, el mismo hueco vuelve, porque la restricción vivía en tu cabeza, no en la spec.
Hay un resultado aquí que debería frenar en seco a cualquier dev con experiencia. En un ensayo controlado aleatorizado de 2025, METR observó a 16 devs open source experimentados trabajando 246 issues reales en codebases grandes y maduras. Los devs esperaban que la IA los hiciera 24% más rápidos. En realidad fueron 19% más lentos con ella. Y después seguían creyendo que los había acelerado cerca de un 20%. Cuanto más capaz el modelo, más lejos lo lleva una instrucción vaga en la dirección equivocada. La capacidad amplifica la dirección. No la aporta.
Prompt primero, sin spec
- 01prompt, generar, notar que falta algo
- 02otro prompt, romper algo, arreglar, otro prompt
- 03repetir hasta que más o menos funcione
- 048 a 12 horas para una feature real
Spec primero
- 01una o dos horas definiendo la spec
- 02generar desde la spec
- 03ajustes pequeños
- 04correcto en la primera pasada real
Una spec no es un prompt, y la diferencia lo es todo
La palabra “spec” se estiró hasta no significar nada. Media industria la usa hoy para decir “un prompt detallado”. Aclara eso primero, porque un prompt y una spec fallan de maneras distintas, y solo uno de los dos vale la pena defender.
Un prompt es una instrucción para un turno. Una spec es un contrato para toda la feature. Un PRD te dice qué construir para el negocio. Una spec le dice al agente cómo debe comportarse el sistema, con la precisión suficiente para implementarlo sin adivinar. Un design doc explica una decisión a humanos. Una spec se escribe para ejecutarse.
Una spec frente a las cosas con las que se confunde
| Artefacto | Escrito para | Vida útil | ¿Fuente de verdad? |
|---|---|---|---|
| Prompt | Un turno del agente | Segundos | No, caduca al instante |
| PRD | Stakeholders | Un release | Parcial: el qué, no el cómo |
| Design doc | Revisores humanos | Hasta que se construye | No, explica, no gobierna |
| Spec (SDD) | El agente de IA | Vive junto a la feature | Sí, el código se genera desde ella |
Los cuatro pilares, y qué va realmente en cada uno
SDD son cuatro fases con un gate de aprobación humana entre cada una. El agente no avanza a la siguiente fase sin tu visto bueno. Eso no es ceremonia. Es como atrapas un error mientras todavía es barato.
Los cuatro pilares
Entrada
Un comportamiento a construir. Empieza por lo que el sistema debe hacer, no por el código.
- 01Requisitos: qué
Lo que el sistema debe hacer, en lenguaje de negocio. Comportamientos observables, independientes de la tecnología. Gate antes del diseño.
- 02Diseño: cómo
Arquitectura, modelos de datos, contratos de API, decisiones de tecnología con su porqué. Cada requisito mapeado a una decisión. Gate antes de las tareas.
- 03Tareas: cuánto
Divídelo en unidades de 2 a 4 horas, cada una testeable por separado, con dependencias explícitas. Gate antes de la implementación.
- 04Implementación: ejecución
El código sigue a la spec. Cada tarea se verifica contra sus criterios de aceptación. Lo que aprendes vuelve a la spec.
Salida
Un rastro del porqué al cómo, y código que coincide con lo que realmente pediste.
Requisitos es donde decides qué significa “terminado”, en frases simples que alguien ajeno a ingeniería podría verificar. Sin stack, sin librerías, sin schema. Si dice “React” o “Postgres”, va en la siguiente fase. La salida es una lista de comportamientos y los criterios de aceptación que prueban cada uno.
Diseño es donde vive la ingeniería. Modelos de datos, el contrato de la API, las integraciones con terceros, los edge cases y las decisiones de tecnología con su porqué. No “usa Postgres”, sino “usa Postgres porque los registros de pagos necesitan garantías ACID”. El porqué es lo que impide que el agente lo cambie por otra cosa tres sesiones después. Cada requisito de la fase uno se mapea aquí a una decisión de diseño, para que nada se caiga sin que nadie lo note.
Tareas es donde cortas el trabajo en piezas lo bastante pequeñas para verificarlas. De dos a cuatro horas cada una. Si una tarea no se puede probar por sí sola, es demasiado grande o demasiado vaga. Cada tarea nombra los archivos que toca, sus dependencias y cómo sabrás que pasó.
Implementación es la única fase en la que se escribe código, y solo empieza después de que se aprueban las tareas. El gate es el punto. En mi kit el gate es literalmente un archivo de una línea, un .status por feature que dice requirements:approved, luego design:approved, luego tasks:approved. El agente lo lee antes de hacer cualquier cosa. La regla es tajante: un design.md en el disco no es aprobación. Solo el token de estado lo es. Esa única restricción evita que un agente impaciente salga corriendo a programar sobre un borrador que nadie firmó.
La cuenta es la razón para tomarse la molestia. Un error detectado en requisitos cuesta minutos. El mismo error detectado en implementación cuesta días. Detectado en producción, con dinero real en movimiento, cuesta semanas y una disculpa. Los gates existen para empujar cada error lo más a la izquierda posible.
Una spec real, de principio a fin
La mayoría de las guías describen una spec y nunca te muestran una. Aquí va una completa para un caso difícil: crear un cobro, donde un retry nunca debe cobrarle dos veces al cliente. Es muy parecida a la que realmente escribí para la fintech.
# Spec: Create a payment charge (POST /v1/charges)
# Status: requirements:approved
## Overview
A merchant creates a charge against a customer. This moves money, so it
must be safe to retry and impossible to double-bill.
## In scope
- Create a charge from an authenticated merchant request.
- Return the charge id and status.
- Guarantee exactly-once billing under client retries.
## Out of scope (v1)
- Refunds (separate spec: 005-refunds).
- Partial captures.
- Multi-currency. All amounts are BRL, stored as integer cents. Never float.
## Functional requirements (EARS)
- FR-1 WHEN a merchant POSTs a charge with a valid Idempotency-Key,
THE SYSTEM SHALL create at most one charge for that key.
- FR-2 WHEN the same Idempotency-Key is replayed within 24h,
THE SYSTEM SHALL return the original charge and create no new one.
- FR-3 IF the amount is <= 0,
THE SYSTEM SHALL reject with 422 "amount must be positive".
- FR-4 IF the merchant is over its rate limit,
THE SYSTEM SHALL reject with 429 and a Retry-After header.
- FR-5 WHILE a charge is pending,
THE SYSTEM SHALL NOT allow a second capture.
## Acceptance criteria (examples the agent must satisfy)
- amount=1000, key=abc -> 201, status=pending
- same key=abc, replayed -> 200, same charge id, no new row
- amount=0 -> 422 "amount must be positive"
- amount=-50 -> 422 "amount must be positive"
- 6th request in 1s, one merchant -> 429, Retry-After: 1
## Non-functional
- p95 latency under 300ms at 200 requests/sec per merchant.
- Every money value is an integer. No floating point anywhere in the path.
## Data
- charges(id, merchant_id, amount_cents, currency, status,
idempotency_key, created_at)
- UNIQUE(merchant_id, idempotency_key) # this is what enforces FR-1
## Verification
- Integration test replays one key 50x concurrently; assert exactly one
row and one ledger entry.
- Load test holds p95 < 300ms at 200 rps.
## Confirm before building
Do not write code until you restate FR-1 through FR-5 and the uniqueness
constraint in your own words. If any acceptance criterion is ambiguous,
ask before implementing.Fíjate en lo que hace esa spec. Nombra los comportamientos exactos, dice lo que no va a hacer, fija el tipo del dinero en enteros para que el agente no pueda echar mano de un float, pone la defensa contra el cobro doble en la base de datos como una unique constraint en lugar de esperar que el código se acuerde, y termina pidiéndole al agente que demuestre que entendió antes de teclear. Esa última línea no es decoración. Es la prevención de bugs más barata que vas a escribir en tu vida.
Qué hizo que esa spec funcionara
Una buena spec tiene una propiedad testeable: dásela a alguien sin nada de tu contexto, y aun así construye lo correcto. Cuatro movimientos te llevan ahí.
Escríbela para un niño listo
Explícale el sistema a un niño brillante de 12 años que hace preguntas agudas y no conoce nada de tu contexto. No le dirías “haz eso con las tareas”. Le dirías “cuando alguien crea una tarea, guarda el título, revisa que tenga permiso en ese workspace y avisa a todos los que están viendo la lista”. El agente necesita exactamente ese nivel. No porque sea lento, sino porque, como el niño, no tiene nada de tu conocimiento implícito. El objetivo del principio es sacar a la luz las reglas tácitas (“revisa el permiso”), donde dejan de ser algo que el agente tiene que adivinar.
Sé específico, o el agente adivina
Los adjetivos no son requisitos. “Rápido”, “limpio”, “seguro”, “robusto”: cada uno es una invitación a que el agente invente su propia definición.
Vago frente a ejecutable
| Vago: el agente adivina | Ejecutable: el agente sabe |
|---|---|
| "El sistema debe ser rápido." | GET /api/v1/tasks responde en menos de 500ms en p95 para listas de hasta 1.000 tareas. |
| "Valida el título." | vacío -> "El título es obligatorio"; 1 carácter -> "Mínimo 2 caracteres"; 501 caracteres -> "Máximo 500". |
| "Maneja los errores con elegancia." | Ante un timeout del proveedor, reintenta 3x con backoff y luego manda a la cola de revisión manual. |
Escribe los requisitos en EARS
Esta es la técnica que casi ninguna guía enseña, y es la de mayor palanca. Escribe los requisitos funcionales en EARS, el Easy Approach to Requirements Syntax. Es un formato de hace 30 años, salido de la ingeniería de requisitos, y está hecho justo para el tipo de ambigüedad que SDD combate. Cinco formas de oración cubren casi todo, y ninguna le deja al agente espacio para interpretar.
Los patrones EARS, con ejemplos reales
| Patrón | Plantilla y ejemplo |
|---|---|
| Ubicuo | THE SYSTEM SHALL validate workspace permissions on every task operation. |
| Dirigido por eventos | WHEN a task is completed, THE SYSTEM SHALL record the timestamp and the user. |
| Dirigido por estado | WHILE a task is archived, THE SYSTEM SHALL NOT allow edits. |
| Comportamiento no deseado | IF more than 50 subtasks are created, THE SYSTEM SHALL show "Subtask limit reached". |
| Opcional | WHERE notifications are enabled, THE SYSTEM SHALL notify assignees on change. |
Di lo que no vas a construir
El alcance negativo es la mejor defensa contra un agente que, “para ayudar”, construye algo que nunca pediste. Escríbelo temprano, escríbelo seco: sin tareas recurrentes, sin integración con calendario hasta la v2, sin registro de horas, solo subtareas. Cada línea que excluyes es un desvío en el modelo de datos que el agente no toma. La mecánica completa, con una plantilla para copiar y pegar, está en el texto complementario: cómo escribir una spec con la que un agente de IA pueda construir.
Elige tu nivel de rigor
No tienes que ir con todo. SDD es un dial, y elegir la posición es lo que mata el argumento de que “las specs son exageradas” antes de que empiece. La pregunta nunca es si escribir una spec. Es cuánto merece este trabajo en particular. Esta taxonomía viene del trabajo de Birgitta Böckeler en Thoughtworks, y es la forma más limpia de pensarlo.
¿Cuánta autoridad tiene la spec sobre el código?
| Nivel | La spec es | Ideal para |
|---|---|---|
| Spec-first | Una plataforma de lanzamiento. Guía el primer build y después la sueltas. | MVPs, prototipos, features puntuales |
| Spec-anchored | Un documento vivo que se mantiene sincronizado con el código a medida que cambia. | Sistemas en producción (el punto ideal) |
| Spec-as-source | El único archivo que edita un humano. El código se regenera desde él. | Frontera, todavía experimental |
SDD no es TDD, BDD ni vibe coding
SDD no es nuevo. Es el punto más reciente de una línea de 30 años. El TDD de Kent Beck guiaba el código con tests. BDD lo guiaba con ejemplos de comportamiento. SDD lo guía con una especificación aprobada. Una forma útil de verlo: TDD es SDD a nivel de unidad. El planteamiento académico, en un paper de 2026 sobre el tema, es que la especificación se vuelve la fuente de verdad y el código se vuelve un artefacto generado o verificado. Así es dónde guarda su verdad cada método.
¿Dónde vive la verdad?
| Método | La verdad vive en | Modo de falla típico |
|---|---|---|
| Vibe coding | El último prompt | Rápido, seguro de sí, equivocado |
| TDD | Tests unitarios | Tests en verde, arquitectura equivocada |
| BDD | Ejemplos de comportamiento | Los escenarios se desalinean del código |
| SDD | La spec aprobada | La spec se desactualiza si no la mantienes viva |
Si vienes del lado del vibe coding, la comparación cronometrada, la misma tarea con y sin spec, es un artículo aparte.
Un millón de tokens de contexto no te va a salvar
Es la objeción más aguda de 2026, y casi nadie la responde. Si puedo meter toda mi codebase en la context window, ¿para qué escribir una spec?
Porque el tamaño del contexto y la precisión del contexto son problemas distintos. Un millón de tokens de código le dice al agente qué es el sistema hoy. No dice nada sobre en qué debe convertirse: tu intención, tus restricciones, los edge cases que te importan, lo que queda fuera a propósito. Una ventana más grande deja al agente mejor informado sobre el presente y nada más sabio sobre el destino. Peor: más contexto es más superficie para que el agente copie el precedente equivocado.
Una spec no es entrega de información. Es un conjunto de decisiones. La context window hace que el agente esté al tanto. La spec hace que esté alineado. Las ventanas más grandes aumentan el valor de una spec clara, porque ahora el límite de la calidad no es cuánto puede ver el agente. Es qué tan claro le dijiste lo que tiene que hacer.
Cuándo no escribir una spec
Un método honesto te dice dónde no aplica. SDD tiene un overhead real, y para mucho trabajo ese overhead es puro desperdicio. Anthropic traza la línea en una frase: “si puedes describir el diff en una frase, sáltate el plan.” Estoy de acuerdo. Sáltate la spec cuando no compensa.
¿Este trabajo merece una spec?
| Criterio (peso) | Script puntual | Spike exploratorio | Feature de producción |
|---|---|---|---|
| Vive más de unos días (3) | 1 | 2 | 5 |
| Abarca varias sesiones (3) | 1 | 1 | 5 |
| Varias features o servicios complejos (2) | 1 | 2 | 5 |
| La corrección o el compliance importan de verdad (3) | 1 | 1 | 5 |
| Puntuación ponderada | 11 | 16 | 55 |
Scale 1-5 (5 = best). Highlighted column: winner by weighted score.
¿Vas a construir una utilidad de una hora? Escribir una spec antes es la burocracia de la que advierten los escépticos. Usa SDD cuando el trabajo dura más de una sentada, involucra arquitectura de verdad o abarca varias sesiones, porque es justo ahí donde la falta de memoria del agente empieza a costarte dinero.
No, esto no es waterfall
La diferencia es lo bastante precisa como para decirla. El problema de waterfall nunca fue planificar de antemano. Fue la planificación congelada: un ciclo de feedback tan largo que una decisión de hace meses no podía responder a lo que aprendiste después. Las specs de SDD están vivas. Revisas un requisito y el cambio se propaga, a propósito, por el diseño y las tareas. El ciclo es por fase, no por proyecto.
Aun así hay una advertencia que vale la pena guardar, y viene otra vez de Böckeler. El model-driven development intentó esto en los 2000, generando código a partir de modelos formales, y en buena parte murió: DSLs rígidos, generadores gigantes, el nivel de abstracción equivocado. Los LLMs eliminan parte de ese overhead. Pero los modos de falla que mataron a MDD, la spec desactualizada, especificar demasiado y demasiado pronto, empeorar las cosas en nombre del rigor, son riesgos que SDD todavía puede repetir si te descuidas. Mantén la spec proporcional a la fase, y mantenla viva.
Cómo se ve a escala
Voy a ser breve, porque esto tiene su propio caso de estudio. Pero para aterrizar el método, esto es lo que produjo SDD en un proyecto real.
Una fintech cripto, un dev, guiada por spec
- 13
- apps en producciónmonorepo
- 3
- APIs, 3 bases de datosauth, pagos, exchange
- 70
- díasbuild en solitario
- 28
- archivos de specel contexto fijo del agente
Eso fue un solo desarrollador. Cuando toda una organización de ingeniería intenta trabajar así, con producto, diseño y muchos squads, el framework que aparece es AI-DLC, el ciclo que AWS construyó sobre la misma idea: la IA conduce, las personas deciden en los gates y cada decisión vive en archivos versionados. Asume que tu equipo ya especifica. Por eso veo SDD como el escalón previo, y lo argumenté en AI-DLC vs Spec-Driven Development.
Preguntas frecuentes
¿Qué es spec-driven development, en términos simples?
Es una forma de construir software con IA en la que escribes y apruebas una especificación detallada antes de generar cualquier código, y esa spec se vuelve la fuente de verdad desde la que construye el agente.
El cambio es que la spec es el artefacto principal y el código es la consecuencia, al revés de como suele funcionar la documentación.
¿Anthropic recomienda spec-driven development?
En la práctica, sí. Las buenas prácticas de Claude Code, de Anthropic, describen un ciclo de explorar, planificar, implementar y hacer commit, y un plan mode dedicado, y publican una plantilla de prompt para entrevistarte hasta llegar a una spec antes de escribir código.
Su razón declarada: dejar que el modelo salte directo al código puede producir código que resuelve el problema equivocado.
¿Spec-driven development es lo mismo que test-driven development?
Están emparentados, no son lo mismo. TDD guía el código con tests. SDD lo guía con una especificación aprobada. Un planteamiento útil es que TDD es SDD a nivel de unidad.
SDD trabaja a mayor altura, requisitos, diseño y tareas, y está pensado para guiar agentes que no tienen memoria entre sesiones.
¿SDD es solo waterfall con otro nombre?
No. El problema de waterfall era la planificación congelada, de ciclo largo. Las specs de SDD son documentos vivos: las revisas y el cambio se propaga por el diseño y las tareas de forma controlada.
El ciclo de feedback es por fase, no por proyecto.
¿Una context window grande hace innecesarias las specs?
No. Una context window grande le dice al agente qué es el código hoy. No le dice en qué debe convertirse, ni qué queda fuera del alcance a propósito.
El tamaño del contexto y la precisión del contexto son problemas distintos. Las ventanas más grandes aumentan el valor de una spec clara.
¿Cuándo no debería usar spec-driven development?
Para scripts puntuales, prototipos desechables, spikes exploratorios o cualquier cosa que termines en una sola sesión de prompts. La regla práctica de la propia Anthropic: si puedes describir el diff en una frase, sáltate el plan.
Usa SDD cuando el trabajo dura más de una sentada, abarca varias sesiones o involucra arquitectura y requisitos de corrección de verdad.
¿Qué herramientas necesito para SDD?
Ninguna en particular. SDD es un método, no un producto. Puedes aplicarlo con archivos markdown simples y cualquier agente de código competente.
Toolkits como GitHub Spec Kit, OpenSpec, AWS Kiro y mi propio pi-sdd-kit codifican el workflow, pero el método funciona con un editor de texto y disciplina.
A dónde ir ahora
SDD no se trata de escribir más. Se trata de dejar por escrito las cosas correctas, porque tu colaborador más rápido olvida todo en el segundo en que termina la sesión, y la spec es la única memoria que tiene.
Empieza en pequeño. Elige una feature. Escribe los tres documentos, requisitos, diseño y tareas, y dáselos a tu agente. La primera spec es lenta. La segunda te toma la mitad. Para la tercera ya te sale sola.
La newsletter
Don’t Code, Specify. Cada semana, agentes de IA en producción de verdad. Sin hype: lo que funcionó y lo que se rompió.
Suscríbete en Substack (se abre en una pestaña nueva)El código ahora se escribe solo. La spec no. Ese es todo el trabajo.