El desarrollo guiado por especificaciones (spec-driven development) es una forma de construir software en la que escribes los criterios de aceptación antes del código, y decides si una tarea está hecha 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 escribieron.
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 pediste. Medido en 120 ejecuciones y cuatro modelos, una petición en crudo de una línea coló 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 bajó 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.
Spec-driven vs. TDD
TDD también escribe los tests primero, y son primos hermanos. La diferencia es el énfasis: TDD es un ritmo de desarrollo (rojo, verde, refactor) centrado en el diseño a nivel de unidad. El desarrollo guiado por especificaciones trata los criterios de aceptación como el contrato de “hecho” a nivel de feature, y hace de la ejecución contra ese contrato el gate para mergear, sobre todo cuando el código lo escribió un agente y no miraste cada línea.
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 tocó sin ejecutarla. El desarrollo guiado por especificaciones cambia el “parece bien” por “se ejecutó y pasó”.
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.
Preguntas frecuentes
¿Es lo mismo que TDD? No, pero se solapan. TDD es un ritmo de código a nivel de unidad; el desarrollo guiado por especificaciones va de criterios de aceptación a nivel de feature y de poner el gate de “hecho” sobre la ejecución contra ellos.
¿Te ralentiza? Escribir criterios cuesta minutos. Mergear una feature verde-pero-rota cuesta horas o días después. En las tareas medidas eliminó 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.