Spec-driven development

Spec-driven development (SDD) es escribir qué tiene que hacer el software, y en qué consiste estar hecho, antes de que se escriba el código, y dejarlo escrito en un documento que vive en el repositorio y del que se deriva todo lo demás.

El cambio respecto a lo de siempre no está en que haya un documento: está en quién lo usa. Una especificación clásica se escribía, se aprobaba y se olvidaba, y la verdad acababa estando en el código. En SDD la especificación es la entrada de trabajo del agente: si no está escrita, no se implementa; y cuando el código y la especificación no concuerdan, se corrige la especificación primero.

Con agentes de código, escribir código ha dejado de ser lo caro. Lo caro es decir bien qué hay que hacer. El cuello de botella se ha movido, y las prácticas de trabajo todavía no.

Los síntomas son siempre los mismos:

• Compila, pasa los tests y no es lo que pedías. El malentendido estaba en la primera frase del encargo, pero se descubre cuatrocientas líneas después.
• No hay dónde discutir el enfoque. Un diff de cuarenta ficheros es el peor sitio y el peor momento para enterarse de que la arquitectura elegida no era la que querías. A esas alturas, corregir significa tirar.
• La intención no queda en ninguna parte. El porqué de cada decisión se quedó en una conversación que se cerró. La siguiente sesión no lo tiene, la siguiente persona tampoco, y el código solo cuenta el qué.
• El agente deriva. En una sesión larga reinterpreta el objetivo por el camino, y cada reinterpretación parece razonable vista de una en una.
• No hay criterio de terminado. Sin una definición comprobable de hecho, el agente para cuando le parece que ya está, que rara vez es cuando lo está.
• El mismo encargo da resultados distintos según quién lo escriba, porque el encargo iba en un prompt improvisado y no en un documento compartido.

Todo eso es la misma causa: la ambigüedad sobrevive hasta el código, y en el código cuesta mil veces más quitarla.

SDD no inventa nada de esto: es la misma vieja lección de que el error es más barato cuanto antes se pilla. Lo que cambia es que antes no compensaba escribirlo todo —escribir la especificación costaba una parte importante de lo que costaba programarlo— y ahora sí, porque implementar se ha vuelto barato y especificar es lo único que sigue costando lo mismo.

El trabajo se parte en fases, cada una produce un documento, y entre fase y fase hay una persona que aprueba.

A esos tres se añade la memoria del proyecto —lo que vale para todas las funcionalidades y no para una: convenciones, arquitectura, reglas del negocio—, que es lo que evita repetir el mismo contexto en cada especificación.

La separación entre el QUÉ y el CÓMO es la que más se incumple y la que más rinde: mezclar la solución en los requisitos cierra el abanico antes de haber mirado, y es lo que convierte una revisión de requisitos en una discusión de implementación.

• Es ingeniería de contexto escrita y versionada. La especificación es exactamente el contexto que quieres que el agente tenga, en un fichero que se revisa en el pull request en vez de en un prompt que se pierde (tema 4).
• Da un criterio de terminado comprobable, que es el requisito sin el cual un bucle no puede funcionar: un objetivo demostrable y un verificador (tema 4).
• Es el pipeline con human-in-the-loop del tema 5, aplicado al desarrollo: pasos fijos, puerta entre paso y paso, y la persona en la puerta y no en cada línea.
• Cambia lo que revisas. Una página de requisitos, en vez de dos mil líneas de diff a las que todo el mundo acaba dando al botón verde.
• Las tareas trocean el trabajo en piezas que caben. Cada tarea es un encargo pequeño y acotado, que es justamente donde un agente acierta; el encargo grande y vago es donde se pierde.

• No es cascada. El ciclo es por funcionalidad pequeña, no por proyecto: se especifica lo que se va a hacer esta semana, no el sistema entero. Y se vuelve atrás: cuando la implementación demuestra que el diseño estaba mal, se corrige el diseño y se sigue, que es justo lo que la cascada no permitía.
• No es documentación. Un documento que nadie lee ni ejecuta es papel. La especificación se mantiene viva porque es la entrada del agente: si miente, lo que sale está mal, y eso se nota el mismo día.
• No es escribir más, es escribir antes. El volumen total baja, porque lo que se ahorra es el trabajo que había que rehacer.
• No sustituye al criterio. Las puertas de aprobación valen lo que valga la lectura: aprobar los requisitos sin leerlos es peor que no tener puerta, porque da sensación de control sin el control.

La regla corta: si el encargo cabe en una frase sin ambigüedad, escribirlo dos veces es ceremonia. Y si no sabes lo que quieres, primero se explora —a mano, con prototipos que se tiran— y se especifica después, con lo aprendido; especificar no es un método para averiguar qué quieres.

La petición, tal y como llega:

hay que poder exportar los pedidos

Ahí hay cinco decisiones escondidas, y el agente va a tomar las cinco por su cuenta sin avisar:

• ¿En qué formato?
• ¿Qué pedidos: todos, los del usuario, los que su rol puede ver?
• ¿Cuántos? Diez y diez millones no se resuelven igual.
• ¿En el momento, o se genera y se avisa al terminar?
• ¿Qué pasa si no hay ninguno?

Contestarlas cuesta cinco minutos por delante. Descubrirlas por detrás cuesta rehacer la funcionalidad, y encima con la sensación de que el agente «ha hecho algo raro» cuando lo que hizo fue rellenar los huecos que le dejamos.

Escrito como requisito queda comprobable, que es lo único que le pedimos:

Cuando un usuario solicita la exportación de pedidos, el sistema DEBERÁ
generar un fichero CSV con los pedidos visibles para su rol.
Si la consulta supera los 10.000 pedidos, el sistema DEBERÁ generarlo
en segundo plano y avisar por correo al terminar.
Si no hay ningún pedido, el sistema DEBERÁ informar de ello y no
generar ningún fichero.

Esa forma de escribir —cuando pasa esto, el sistema deberá hacer esto otro— es el formato EARS, y no es un capricho de estilo: obliga a nombrar la condición que dispara cada comportamiento, que es exactamente donde se esconden los casos que nadie había pensado. Se ve en detalle en el tema 11.

• El cuello de botella ya no es escribir código: es decir bien qué hay que hacer.
• SDD saca la ambigüedad del código y la pone en un documento, donde corregirla cuesta una frase.
• Fases: requisitos (el QUÉ) → diseño (el CÓMO) → tareas → implementación, con una persona aprobando en cada salto.
• La especificación es la fuente de verdad: si no concuerda con el código, se arregla primero el documento.
• Por funcionalidad pequeña y con vuelta atrás. No es cascada, y para lo trivial no se usa.

Cómo se hace esto con herramientas concretas —OpenSpec, GitHub Spec Kit, BMAD y Kiro— es el tema 11.