logongas

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.
====== 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.

----

===== 1. El problema que intenta resolver =====

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.

^ Dónde se descubre el error ^ Lo que cuesta corregirlo ^
| En los requisitos | Cambiar una frase |
| En el diseño | Cambiar un párrafo y un diagrama |
| En las tareas | Reordenar una lista |
| En el código | Rehacer el trabajo, y normalmente también los tests |
| En producción | Lo anterior, más el incidente |

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.

----

===== 2. En qué consiste =====

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

<uml>
start
:peticion, normalmente una frase;
repeat
  :requisitos: el QUE;
  :aprobacion humana;
  :diseno: el COMO;
  :aprobacion humana;
  :tareas: el plan de ejecucion;
  :implementacion;
  :verificacion;
backward:corregir la especificacion;
repeat while (la implementacion desmiente la spec) is (si) not (no)
:entregado;
stop
</uml>

^ Documento ^ Qué contesta ^ Lo que **no** lleva ^
| ''requirements.md'' | Qué tiene que pasar, para quién y cómo se comprueba | Soluciones técnicas. Aquí no se elige base de datos |
| ''design.md'' | Cómo se va a hacer: arquitectura, modelo de datos, contratos, decisiones y las alternativas descartadas | Requisitos nuevos colados por la puerta de atrás |
| ''tasks.md'' | El plan: pasos pequeños, ordenados y verificables uno a uno | Nada que no salga de los dos documentos anteriores |

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.

----

===== 3. Por qué encaja tan bien con los agentes =====

  * **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.

<note tip>Y una consecuencia que no es evidente: la especificación es **reutilizable**. El mismo documento sirve para volver a generar el código con otro modelo, para reconstruir una parte que salió mal o para retomar dentro de seis meses. Lo que se ha capturado es la intención, y la intención no caduca cuando cambias de herramienta.</note>

----

===== 4. Lo que SDD no es =====

  * **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.

----

===== 5. Cuándo compensa =====

^ Compensa ^ No compensa ^
| Funcionalidad que toca varios ficheros | Un arreglo de una línea |
| Trabajo que dura más de una sesión | Un script de usar y tirar |
| Más de una persona implicada | Un prototipo que se va a tirar |
| Dominio con reglas de negocio que no se deducen del código | Cambios mecánicos y evidentes |
| Código que va a vivir años | Explorar: cuando **todavía no sabes qué quieres** |

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.

----

===== 6. Un ejemplo de por qué hace falta =====

La petición, tal y como llega:

<code>
hay que poder exportar los pedidos
</code>

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:

<code>
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.
</code>

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.

----

===== 7. Resumen =====

  * 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 [[cursos:sdd:11-kiro|Kiro]]— es el tema 11.