El desarrollo guiado por especificaciones (spec-driven development) es una forma de construir software en la que los criterios de aceptación, la definición de “hecho” del producto, se escriben antes del código, y si una tarea está hecha se decide ejecutando el código contra esos criterios, no con un build en verde.
El nombre apunta al orden: primero la spec, luego el código, y por último la verificación por ejecución. Que el build pase no es la meta. La meta es que los criterios se ejecuten como se han escrito.
Por qué existe
Que el build esté en verde te dice que el código está de acuerdo consigo mismo. No dice nada de si hace lo que has pedido. Medido en 120 ejecuciones y cuatro modelos, una petición en crudo de una línea ha colado un fallo de corrección real en el 40% de los casos con el build en verde. Darle al agente los criterios por delante lo ha bajado a 0%.
El modelo no era la variable. La spec sí.
Cómo funciona
- Escribe los criterios de aceptación de la tarea, en lenguaje claro, antes de una línea de código. Cada criterio es una afirmación comprobable sobre el comportamiento: qué debe hacer el código, con qué entrada, con qué resultado.
- Implementa el cambio (tú, o un agente).
- Pon un gate de ejecución. Reaplica el cambio sobre una copia limpia, ejecuta el código y comprueba cada criterio. Si uno falla, la tarea no está hecha, por muy verde que esté el build.
Los criterios viajan con el cambio y sobreviven a la sesión, que es lo que mantiene un sistema coherente en vez de localmente correcto pero globalmente incoherente.
De dónde viene (y por qué no es TDD)
El desarrollo guiado por especificaciones no es TDD, y confundirlos es la forma más rápida de no entenderlo. TDD es un ritmo del desarrollador, rojo, verde, refactor, a nivel de unidad: el dev escribe un test unitario que falla para guiar el diseño de una función. El autor es el desarrollador, el artefacto es un test unitario, el propósito es el diseño.
El desarrollo guiado por especificaciones está un nivel por encima, y viene de otro linaje: BDD (behavior-driven development), acceptance-test-driven development y el Specification by Example de Gojko Adzic. El artefacto son los criterios de aceptación de una user story, la definición de “hecho” del producto, idealmente escritos en forma ejecutable como el Given/When/Then de Gherkin. Fusiona producto y código: los criterios que define el producto se convierten en el gate que el código tiene que pasar. La user story lleva la intención, los criterios de aceptación la hacen comprobable, y el gate los ejecuta.
Lo nuevo en la era de la IA es quién escribe qué. Cuando el código lo escribe un agente, el trabajo del humano sube a la especificación, y el gate tiene que imponerla sobre el diff real, en cada run, porque el agente no es determinista y no has mirado cada línea. No es un dev probando su propio diseño. Es la intención del producto, hecha ejecutable, decidiendo si lo que ha sacado el agente cuenta como hecho.
Spec-driven vs. spec-gated
Hay una distinción que merece nombre, porque es donde fallan casi todos los equipos. Spec-driven habla del orden: escribes los criterios antes que el código. Spec-gated habla del poder: nada está hecho hasta que pasa los criterios, ejecutados, en cada run.
Un repo lleno de PRDs y criterios de aceptación en Markdown que nadie ejecuta es spec-driven solo de nombre. Los documentos existen. No deciden nada. Lo que ha movido los números en el benchmark no ha sido escribir los criterios, ha sido ponerles un gate: re-ejecutar el código contra ellos en cada cambio, sobre un agente no-determinista que no has mirado.
Así que el nombre más afilado para lo que de verdad funciona en la era de la IA es spec-gated development: un cambio no está hecho hasta que pasa la spec, ejecutada, en cada run. Los criterios de aceptación no son documentación. Son el gate.
Spec-driven vs. vibe coding
El vibe coding es lo contrario: prompt, miras el resultado, mergeas si parece bien. Funciona hasta que no, y en un sistema no-determinista no puedes saber qué tirada te ha tocado sin ejecutarla. El desarrollo guiado por especificaciones cambia el “parece bien” por “se ha ejecutado y ha pasado”.
Dónde compensa
Cuanto más dura y menos trivial es la tarea, más importa: hasta el mejor modelo frontier, en crudo, cuela un fallo real en una feature compleja una de cada tres veces, de forma no-determinista. Escribir los criterios una vez y poner el gate de ejecución es lo que hace el resultado fiable, y permite que un modelo barato iguale a uno caro.
Hacerlo a mano en cada tarea es la parte tediosa, y es lo que PaellaDoc automatiza.
Para profundizar
El desarrollo guiado por especificaciones es una práctica dentro de un cambio más amplio en cómo se construye software con agentes de IA. Las piezas de abajo bajan un nivel desde esta definición.
Empieza por el artefacto en sí: por qué la spec es el contrato entre intención e implementación, y por qué ese contrato debería ser portable entre agentes y editores en vez de quedar atrapado en una sola herramienta. Si la ceremonia se te hace pesada, hay una versión ligera que conserva el contrato y recorta el proceso, y una forma de añadir specs a un repo que ya existe sin parar el mundo.
Una spec solo sirve mientras sigue siendo cierta. Ese es el problema del spec drift, la divergencia lenta entre el contrato y el código, y el motivo de las especificaciones vivas que se actualizan a la vez que el sistema. Antes de que el agente construya, el gate más barato es revisar la spec en vez del diff; y una vez que una herramienta como Spec Kit ha escrito una, la pregunta difícil es qué necesita el spec-driven a continuación.
Preguntas frecuentes
¿Es lo mismo que TDD? No. TDD es un ritmo a nivel de unidad para que un dev diseñe código. El desarrollo guiado por especificaciones es el linaje de BDD / acceptance-test-driven: los criterios de aceptación del producto, expresados de forma ejecutable (el Given/When/Then de Gherkin), deciden si el trabajo está hecho. Otro nivel, otro autor, otro propósito.
¿Te ralentiza? Escribir criterios cuesta minutos. Mergear una feature verde-pero-rota cuesta horas o días después. En las tareas medidas ha eliminado por completo la tasa de bugs genuinos.
¿Necesito una herramienta? No. Puedes hacerlo a mano. Una herramienta ayuda cuando quieres los criterios y el gate de ejecución en cada tarea sin tener que acordarte.