Spec-driven development: qué es y nuestro contrato de issue

Spec-driven development (SDD) significa que deja por escrito qué construir y cómo sabrá que está terminado antes de que un agente de IA escriba una sola línea de código. Spec Kit de GitHub lo resume así: "Define what to build and why, then turn the specification into a plan, tasks, and working code." Es decir: defina qué construir y por qué, y convierta la especificación en un plan, tareas y código que funciona. Nosotros usamos una versión más ligera: la especificación es un issue de GitHub con tipo de tarea y criterios de aceptación, y un control automático comprueba que existe el resultado prometido.

Trabajamos como una fábrica de software: los agentes de IA hacen el trabajo rutinario, los seniors deciden qué se construye y revisan cada cambio. Así que nuestro trabajo se trasladó a la especificación y a las comprobaciones a su alrededor. A continuación, nuestro contrato de issue, el código que lo lee y lo que aprendimos cuando la especificación estaba mal.

¿Qué es el spec-driven development con agentes de IA?

La definición breve está en nuestro glosario. La idea es antigua: acordar qué significa terminado antes de construir. Con agentes de IA importa más, porque un agente construye algo de todos modos. Sin especificación rellena los huecos con suposiciones, y las suposiciones parecen terminadas.

Spec Kit lo ejecuta como comandos en el chat del agente: principios del proyecto, especificar, planificar, tareas, implementar. Otras herramientas tienen su propia variante. Todas comparten una cosa. La especificación va antes que el código y sigue siendo la referencia en la revisión.

Dónde encaja el context engineering: todo lo que ve el agente es contexto, desde los archivos de reglas hasta la salida de las herramientas. La especificación es la parte de ese contexto que dice qué significa terminado. Más contexto sin ella solo produce un resultado equivocado con más seguridad.

¿Por qué un issue de GitHub en lugar de un documento de especificación largo?

Nuestros issues son una cola que la gente lee cada mañana. Nuestra regla para ellos empieza con tres palabras: "Queue items, not specs." Elementos de una cola, no especificaciones. Una especificación larga va a un documento enlazado. El issue es lo que una persona o un agente recoge y termina.

Menos issues y más grandes funcionan mejor también para los agentes. Nuestra regla es un resultado terminado por issue y por pull request. Uno grande sigue siendo un solo PR, con un commit por capa, para que una persona pueda leerlo en el orden en que se construyó.

¿Qué incluye nuestro contrato de issue?

Tres cosas son obligatorias: un título con un verbo de acción y un objeto concreto, una etiqueta de prioridad y qué hay que hacer. Para un trabajo sencillo basta con el título. Secciones como ## What, ## Acceptance y ## Output aparecen solo cuando tienen contenido. Un ## Acceptance: TBD vacío está prohibido.

El tipo de tarea decide qué debe existir al final:

Nadie añade una etiqueta para el tipo. Quien recoge el issue lo deduce. Si falta ## Output o ## Acceptance, se completa como suposición explícita, nunca en silencio.

¿Cómo comprueba una máquina la especificación?

Dos veces: antes del trabajo y después.

Antes del trabajo: READY. Una llamada de solo lectura a un modelo lee el issue y el código y devuelve una respuesta tipada. Recortado de nuestro esquema:

{
  "ready": true,
  "type": "code",
  "done_when": ["criteria a reviewer can answer yes or no"],
  "verifiable": "test",
  "confirmation": ["the test that carries the proof"],
  "premise": "verified against <file:line>",
  "question": ""
}

premise es lo que más tiempo nos ahorra. La comprobación compara cada afirmación que hace el issue sobre el comportamiento actual con el código, con archivo y línea. Si nada del issue sigue siendo cierto, propone cerrarlo. verifiable dice si un test puede demostrar el criterio más arriesgado, o solo una persona mirándolo. Si falta una decisión de producto, question hace una pregunta con dos opciones y una recomendación, y el trabajo no empieza.

Después del trabajo: el control. Bash sin más, con códigos de salida, una rama por tipo de tarea. Para el código ejecuta el typecheck, el lint, los tests y el build del propio repositorio, más un red-proof: el código fuente cambiado necesita un test cambiado, y ese test debe fallar en la rama base. Para la investigación abre cada URL de fuente y busca la cita en la página. Una paráfrasis no pasa. Esta parte nunca la califica un modelo.

¿Qué cambió cuando dejamos de dimensionar tareas?

Antes puntuábamos las tareas por tamaño y las repartíamos según eso. Lo sustituimos por la preparación: ¿está la premisa comprobada contra el código, está nombrada la prueba, queda algo por decidir?

Los controles son la otra mitad de la especificación. El issue dice qué significa terminado. Las comprobaciones se aseguran de que nadie, persona o agente, pueda darlo por terminado de otra forma.

¿Qué salió mal con nuestras especificaciones?

• La comprobación de preparación llegó tarde. Al principio el agente tomaba el issue tal como estaba escrito. La comprobación de la premisa contra el código la añadimos después. Hoy es la primera etapa, y es por donde empezaríamos.
• Un comentario equivocado no es un issue equivocado. Un plan antiguo en un comentario hacía que la comprobación refutara issues buenos. Ahora solo cuenta una afirmación en el cuerpo del issue. Un cuerpo refutado va a una persona, que responde OK antes de que empiece el trabajo.
• Un control en verde que no demostraba nada. En un monorepo, el red-proof ejecutaba los tests sin el entorno correcto. Cada "falla en la rama base" era un test que nunca llegó a arrancar, no un rojo de verdad. Durante unos días, todos los red-proof de ese repositorio pasaron en falso. Ahora los tests se ejecutan con el gestor de paquetes del repositorio, por paquete, con la versión de Node fijada.

El último es la lección que más repetimos: una comprobación que no puede fallar no es una comprobación. Más sobre esto en TDD red-green con agentes de IA.

¿Cómo se escribe un issue que un agente pueda terminar?

El último paso es el que los equipos se saltan. También es el más barato: una llamada de solo lectura a un modelo, antes de que exista una línea de código.

Cómo es el resto de la configuración del agente, de las reglas a los hooks, lo contamos en Harness engineering en la práctica: del issue al PR. Cuándo basta el modo de planificación integrado en lugar de una especificación lo explicamos en Claude Code plan mode.

¿Está su issue listo para un agente?

¿Quiere un ciclo de la especificación al PR en su equipo?

Construimos este contrato y las comprobaciones que lo respaldan directamente en el repositorio del equipo como parte de AI-native SDLC para equipos de desarrollo. ¿Le faltan manos más que proceso? Vea un desarrollador senior para su equipo. Desde 2023 hemos entregado más de 15 proyectos en producción.

Le respondemos en un plazo de dos días hábiles con algunas preguntas sobre su trabajo. Después acordamos qué hacemos primero.

Si prefiere hablar antes, reserve una llamada introductoria de 15 minutos.

¿Qué significaba "terminado" en el último issue de su equipo, y quién lo comprobó?

Preguntas frecuentes

¿Qué es el spec-driven development?

Dejar por escrito qué construir, por qué y cómo sabrá que está terminado antes de que nadie escriba código, y convertir eso después en un plan, tareas y código. Con agentes de IA, la especificación es además el contexto con el que trabaja el agente.

¿Necesito un documento de especificación largo?

No. Para la mayoría del trabajo usamos un issue de GitHub: un título, un tipo de tarea, criterios de aceptación y dónde va el resultado. Una especificación larga vive en un documento enlazado, no en el issue.

¿Qué diferencia hay entre spec-driven development y context engineering?

El context engineering es todo lo que ve el agente: reglas, archivos, herramientas, historial. La especificación es la parte que dice qué significa terminado. Sin especificación, más contexto solo produce un resultado equivocado con más seguridad.

¿Cómo comprueban que el agente cumplió la especificación?

Con código, no con opiniones. Antes del trabajo, una comprobación de solo lectura compara el issue con el código. Después del trabajo, un control comprueba que existe el resultado prometido: un PR con un test que falla antes y pasa después, fuentes con citas literales, un informe de QA.

¿Cuándo no compensa una especificación?

Para un arreglo de una línea, el título es la especificación. Donde solo una persona puede juzgar el resultado, como un texto o la sensación visual, la especificación lo dice y el trabajo va a esa persona.