Spec-driven development: qué resuelve, qué cuesta y cuándo usarlo

Faltaba un requisito de base de datos en el pedido. El agente no preguntó: asumió un valor por defecto razonable y siguió adelante. Cuando alguien lo notó, esa suposición ya estaba replicada en decenas de archivos y sacarla costó más que la feature entera. El caso lo documentó el equipo de Nearform, y es el que mejor explica por qué existe spec-driven development.

La idea, en una línea: escribir una especificación antes de generar código, y tratarla a ella como la fuente de verdad del proyecto. Abajo está qué problema resuelve de verdad, qué cuesta —que no es poco— y cómo decidir si para tu cambio conviene o es ceremonia. Spoiler de la última parte: no es una metodología que se adopta o no, es una perilla que se sube o se baja según el tamaño del cambio.

Qué es, en concreto

Lo que invierte SDD es cuál de los dos manda: la especificación o el código. En el desarrollo de siempre el código es la verdad, y el documento que lo describe es un reflejo que envejece apenas alguien toca algo. Acá es al revés: la especificación vive versionada en el repositorio junto al código, y cuando cambia un requisito se edita ese documento y se regenera lo que corresponda — nunca al revés.

La implementación de referencia es Spec Kit, de GitHub, y conviene mirarla porque vuelve concreto algo que suele explicarse en abstracto. Son cinco etapas, y cada una produce un archivo de texto que lee la siguiente:

constitution — las reglas del proyecto que no se vuelven a discutir en cada tarea: qué base de datos se usa, que toda API nueva va versionada, que nada se mergea sin test. Se escribe una vez.
specify — convierte el pedido en prosa en una especificación estructurada. Define qué tiene que hacer el sistema, sin entrar en cómo.
plan — recién acá aparecen las decisiones técnicas: el cómo.
tasks — parte ese plan en tareas chicas que se puedan hacer y verificar de a una.
implement — el único paso donde se escribe código.

Entre medio hay compuertas de revisión. Las dos que más se usan son clarify, que va después de specify y sirve para que el agente pregunte lo que falta en vez de asumirlo, y validate al final, que comprueba que lo implementado se corresponde con lo que decía la especificación.

Y aunque se dibuje como una lista, no se recorre una sola vez: cada compuerta puede mandarte para atrás, y el ciclo se repite hasta que una vuelta entera no produce cambios. Ahí recién está terminado.

Otras herramientas tienen su versión del mismo esquema: Kiro de AWS, OpenSpec, BMAD, Tessl, y lo que traen Claude Code, Cursor y Antigravity. Los nombres cambian; la forma es la misma.

Lo importante de ver el flujo desplegado es notar que el código aparece en el último paso de cinco. Todo lo anterior es ponerse de acuerdo.

No todos dicen lo mismo con “SDD”

Acá hay una confusión que conviene sacarse de encima temprano, porque explica por qué dos personas discuten sobre SDD sin estar hablando de lo mismo. Birgitta Böckeler, de Thoughtworks (abre en una pestaña nueva), comparó tres herramientas que se presentan como spec-driven —Kiro, spec-kit y Tessl— y encontró que no son una sola práctica sino una escalera de ambición, con tres escalones. Los nombres que les puso son los que se usan hoy:

Spec-first. La especificación guía la generación inicial y después lo que se mantiene es el código. La spec fue el combustible de arranque, no una estructura permanente: cumplida su función, se deja morir. Es el escalón más barato y el que ya captura la mayor parte del beneficio.
Spec-anchored. La especificación queda viva. Los cambios entran primero por ella y de ahí bajan al código, regenerando o editando con guía. Pasa a ser una capa de gobierno permanente, con el costo de mantenimiento que eso implica.
Spec-as-source. La especificación es lo único que mantenés y el código es su salida compilada, como el binario de un compilador. Es el escalón más alto y hoy está reservado a entornos con generación determinista.

Vale la pena notar dónde pega cada crítica. La acusación de “esto es waterfall” apunta sobre todo a los dos escalones de arriba. Y casi todo el mundo que dice hacer SDD, en los hechos, está en el primero.

Qué resuelve

El argumento a favor es uno solo, pero es bueno: un agente no deja huecos.

Cuando a una persona le falta un dato, pregunta, o al menos deja un TODO y se nota. Un agente no hace ninguna de las dos cosas: donde falta una definición, pone la suposición más plausible y sigue como si nada. No es un error del modelo de IA — es lo que hace bien. El problema es que esa suposición después se propaga por cada archivo que toca, y para cuando aparece el síntoma ya no hay un lugar donde arreglarla, hay veinte.

Ahí está el valor real de la spec, y conviene decirlo con precisión: no sirve para documentar, sirve para eliminar la ambigüedad antes de generar. Es la diferencia entre descubrir que te faltó definir algo cuando lo estás escribiendo —gratis— y descubrirlo cuando ya está implementado en decenas de archivos.

En la práctica la diferencia se ve así. El pedido de siempre:

Agregá exportación de pedidos a CSV.

Lo mismo, sin huecos:

Exportación de pedidos a CSV

Columnas: id, fecha (formato ISO 8601), cliente, total, moneda.

Filtra por rango de fechas. Sin rango, exporta los últimos 30 días.

Arriba de 10.000 filas se genera en segundo plano y se avisa por mail.

Los montos van con punto decimal y dos decimales, sin separador de miles.

Los pedidos cancelados no se exportan.

Cada una de esas líneas es una decisión que, si no está escrita, el agente va a tomar solo y sin avisarte. Y mirá la última: es la típica que nadie se acuerda de aclarar, que el agente resuelve de la forma más obvia —exportar todo— y que nadie detecta hasta que administración pregunta por qué los totales del informe no cierran con los del sistema.

Por eso la práctica nació en 2025 como reacción al vibe coding, que es pedirle cosas al agente a medida que se te ocurren y alinear después. Los agentes escriben código muy bien y adivinan la intención muy mal; SDD es el intento de sacar la adivinanza del medio.

Qué cuesta

Acá es donde la mayoría de lo publicado se pone entusiasta y conviene no serlo. Las críticas son concretas y vienen de gente que lo usó.

El proceso se come las tareas chicas. En un refactor menor o un ajuste de interfaz, se termina dedicando más tiempo a gestionar el flujo que a entregar. Hay un experimento publicado donde alguien comparó OpenSpec contra simplemente escribir un archivo Instructions.md con las indicaciones, y el archivo suelto resultó más rápido, más barato y más fácil de iterar.

La disciplina se evapora. Los relatos coinciden en que el método se sostiene hasta que el agente empieza a escribir código; a partir de ahí la spec se consulta cada vez menos y queda una sensación de control mayor a la real.

Especificar temprano falla cuando el requisito todavía no existe. El caso típico: un cliente que pide “insights con IA sobre estos datos” y que no puede decirte qué necesita hasta ver algo funcionando. Especificar ahí es inventar. Lo que recomiendan es al revés — prototipo descartable primero, spec después, cuando ya sabés qué estás construyendo.

Y la objeción más aguda, que es sistémica: acelerar la producción de código no acelera la entrega si la revisión, la verificación y la integración mantienen la capacidad que tenían. Producir el doble de código con la misma gente revisando no te da el doble de software entregado; te da una cola más larga antes del cuello de botella. Es la crítica que explica por qué en Hacker News el hilo más leído sobre el tema se titula “The Waterfall Strikes Back”: para muchos esto es diseño exhaustivo por adelantado con nombre nuevo.

Vale la pena registrar un detalle: hasta el paper académico que sistematiza la práctica cierra con un marco para decidir cuándo conviene y cuándo alcanza con algo más simple. Nadie serio la está vendiendo como universal.

Cuándo usarlo

La pregunta útil no es si adoptar SDD, sino cuánto de esas cinco etapas conviene correr para el cambio que tenés enfrente. Lo deciden dos cosas: cuántos archivos toca, y qué pasa si el agente asume mal.

Los tres primeros casos van por tamaño, de menor a mayor.

Toca uno o dos archivos y se deshace con un git revert. Pedilo directo, sin escribir nada antes: un bug que ya tiene un test que falla, un texto que cambia, un renombre. Acá redactar la especificación lleva más tiempo que hacer el cambio.
Toca varios archivos, en una parte del sistema que conocés. No hace falta el flujo entero: alcanzan dos de las cinco etapas, hechas a mano y en corto. Anotá en tres o cuatro líneas qué tiene que pasar y qué no, y antes de que escriba una línea de código, pedile que te cuente cómo piensa resolverlo. Es el punto del método donde menos esfuerzo compra más.
Toca muchos archivos, o equivocarse sale caro. Cambiar el modelo de datos, algo que cruza varios módulos, cualquier cosa que mueva plata o decida permisos. Acá sí el flujo completo, con las compuertas de revisión antes de generar: es exactamente el escenario para el que se inventó, donde un hueco no queda en un archivo sino que se replica en todos.

Y una regla que pisa a las tres anteriores, sin importar el tamaño:

Si todavía no sabés qué querés, no especifiques. Cuando el requisito no está claro —el tuyo o el del cliente— primero va un prototipo descartable, y la especificación recién cuando ya viste algo funcionando. Al revés, lo único que conseguís es redactar con mucha precisión algo que vas a tirar.

Dicho en los términos de la escalera de recién: para casi todo el mundo el lugar correcto es el primer escalón, spec-first. Subir a spec-anchored —mantener la especificación viva para siempre— recién se justifica cuando hay varias personas tocando lo mismo y el costo de que cada una entienda algo distinto supera al de mantener el documento.

Hay además una condición previa que no depende de la spec: si el proyecto no se puede verificar solo, ninguna especificación lo salva. El agente puede tener el documento más preciso del mundo y aun así no poder comprobar si lo que escribió cumple — de eso hablamos acá.

La spec es para antes, no para después

Si te quedás con una sola idea: la especificación paga cuando se escribe antes de generar y para cerrar ambigüedades, no cuando se escribe después para documentar. Una spec redactada una vez terminado el código es documentación, con el mismo destino de siempre: envejece y nadie la lee.

Y el corolario práctico, que es menos vistoso pero más útil: casi todo el beneficio está en el paso más barato de los cinco. Antes de que el agente escriba una línea, pedirle que te diga qué entendió y cómo lo va a hacer. Si eso no coincide con lo que tenías en la cabeza, acabás de ahorrarte las veinte correcciones que venían después.

Si llegaste hasta acá y querés la parte práctica —cómo se escribe una especificación sin huecos, con qué plantillas y por dónde empezar— la seguimos en el artículo siguiente.