Spec Driven Development
Qué es Spec Driven Development, por qué la especificación precede al código y qué artefactos produce el arnés.
La especificación antes que el código
Spec Driven Development invierte el orden habitual: primero se acuerda qué se va a construir y cómo, y solo después se escribe código. El objetivo no es acumular documentación, sino dar al Implementer el contexto necesario para hacer el cambio con las menores ambigüedades posibles.
El arnés separa tres cosas que en una conversación se mezclan: decidir qué se construye, planificar cómo y ejecutar el cambio. Cuando las tres viven en el mismo chat, nada queda registrado y la revisión depende de la memoria. Con SDD, la planificación existe antes de la primera línea de código y se puede revisar por separado.
Qué artefactos produce
El tipo de Work Item decide la planificación. Una Feature necesita requisitos, diseño y tareas; una Task se resuelve con un plan breve. En ambos casos la planificación vive en .rei/specs/<work-item-id>/ y se aprueba antes de implementarse.
| Tipo | Planificación | Qué resuelve |
|---|---|---|
| Feature | requirements.md, design.md y tasks.md | Trabajo que necesita especificarse, varias decisiones de diseño, cambio de comportamiento o de arquitectura. |
| Task | plan.md | Documentación, contratos o un cambio pequeño y localizado, sin cambio de comportamiento ni de arquitectura. |
meta.jsonguarda el tipo, el estado y los commits de referencia del Work Item.current.mdrefleja la sesión viva para poder retomarla si se interrumpe.impl.mdyreview.mddejan la evidencia de la implementación y del veredicto.history.mdarchiva el resumen de los Work Items cerrados y nunca se sobrescribe.
Cómo se relaciona con el arnés
REI Harness convierte SDD en un workflow con roles separados, estados y una puerta de aprobación humana. Cada rol tiene un contrato propio y un límite explícito: ninguno puede planificar, implementar y aprobar su propio trabajo al mismo tiempo.
La planificación queda en ready cuando el Spec Author termina. No se implementa automáticamente: la persona revisa las decisiones y, solo si está de acuerdo, el Work Item pasa a in_progress. El Implementer ejecuta exactamente lo aprobado y el Reviewer compara el resultado con esa planificación.
Lo que SDD no es
- No es escribir documentos por escribir: la planificación se mide por lo que permite decidir y verificar.
- No sustituye el criterio humano: la responsabilidad de qué se construye sigue siendo de la persona.
- No convierte al agente en autónomo: el agente propone y ejecuta dentro de un contrato, no decide el alcance solo.
- No garantiza que no haya errores: hace visibles las decisiones y deja evidencia para revisarlas.
- No elimina la revisión: la cambia de código improvisado a un diff comprobable contra un plan.
Siguiente paso
Para ver el proceso en marcha, recorre un Work Item completo. Para entender la puerta que lo hace distinto, sigue con la aprobación humana.
La firma humana libera la hoja. El silencio no aprueba.