Conceptos · SDD

Spec Driven Development

Qué es Spec Driven Development, por qué la especificación precede al código y qué artefactos produce el arnés.

Especificación primero · planificación revisable

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.

TipoPlanificaciónQué resuelve
Featurerequirements.md, design.md y tasks.mdTrabajo que necesita especificarse, varias decisiones de diseño, cambio de comportamiento o de arquitectura.
Taskplan.mdDocumentación, contratos o un cambio pequeño y localizado, sin cambio de comportamiento ni de arquitectura.
  • meta.json guarda el tipo, el estado y los commits de referencia del Work Item.
  • current.md refleja la sesión viva para poder retomarla si se interrumpe.
  • impl.md y review.md dejan la evidencia de la implementación y del veredicto.
  • history.md archiva 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.

Aprobación de la planificación

Pendiente

La firma humana libera la hoja. El silencio no aprueba.

La aprobación se registra desde el CLI; el visor no la sustituye.