¿Qué es Spec-Driven Development? Definición y ejemplo

Spec-driven development (SDD) es una forma de trabajar con agentes de código en la que primero escribes una especificación dentro del repositorio: un documento que dice qué tiene que hacer el software y cuándo se considera correcto. El agente lee ese documento y genera el código a partir de él. Un agente de código es un programa como Claude Code, Copilot, Cursor o Codex que puede leer tus archivos y escribir cambios por su cuenta.

Para seguir el resto solo necesitas saber qué es un repositorio de git y haber pedido alguna vez a un asistente de IA que te escriba una función.

La spec se guarda en git junto al código y se revisa en el mismo pull request que el cambio. Ahí está toda la diferencia con un prompt: el prompt se evapora cuando cierras el chat.

Qué hay dentro de una spec

Una spec dice qué entra, qué sale, qué no se puede romper y cómo comprobar que el resultado sirve. Suele ser un fichero markdown corto, del tamaño de un ticket bien escrito: igual que un ticket, dice qué se espera y cómo se comprueba, no cómo implementarlo línea a línea.

# Spec: exportar facturas a CSV

Entrada: un rango de fechas.
Salida: un CSV con una fila por factura emitida.

Reglas que no se negocian:
- Las facturas anuladas nunca aparecen en el export.
- Los importes van con dos decimales y punto como separador decimal.

Criterios de aceptación:
- [ ] Un rango sin facturas devuelve un CSV solo con la cabecera.
- [ ] Una factura anulada dentro del rango no sale en el fichero.

Fuera de alcance: exportar a Excel.

Fíjate en lo que no aparece: ningún nombre de función, ninguna librería, ninguna estructura de carpetas. Esas decisiones se las dejas al agente. Lo que tú fijas es el comportamiento y el criterio de aceptación, que es justo la parte que el agente no puede adivinar.

Y esos criterios hacen doble trabajo: son lo que revisas tú y son lo que el agente usa para saber cuándo ha terminado. Esto es solo el aspecto de una spec; qué la hace buena (y los errores típicos que la convierten en papeleo) lo tienes en la guía completa.

La diferencia con pedírselo por el chat

Puedes conseguir el mismo export de facturas escribiendo un párrafo en el chat, y funcionará. La diferencia aparece en la segunda semana.

	Prompt en el chat	Spec en el repositorio
Dónde vive	En la conversación, hasta que la cierras	En git, al lado del código
Quién lo revisa	Nadie	Tu equipo, en el pull request
Cuando el agente se equivoca	Se lo vuelves a explicar desde cero	Corriges la spec y la corrección queda aplicada para siempre
Seis meses después	El motivo de cada decisión no está en ninguna parte	Lees por qué se decidió así

El agente arranca cada sesión sin recordar nada de la anterior. La spec es el único sitio donde puedes dejarle por escrito lo que decidisteis, y también donde tú lo relees cuando ya no te acuerdas.

De dónde viene el término

El término se hizo popular durante 2025, empujado por dos cosas a la vez. Sean Grove, de OpenAI, dio una charla titulada The New Code en la AI Engineer World’s Fair de ese año defendiendo que el artefacto que de verdad hay que versionar es la especificación escrita, no el código generado. Su comparación: guardar solo el código que sale del modelo y tirar el prompt es como versionar el binario y triturar el código fuente.

En paralelo llegaron las herramientas. AWS lanzó Kiro en julio de 2025, un IDE que genera los ficheros requirements.md, design.md y tasks.md antes de tocar una línea de código^[1]. GitHub publicó Spec Kit como código abierto en septiembre de 2025^[2], con un flujo de comandos que cualquier agente puede seguir: /speckit.specify para describir el qué, /speckit.plan para el enfoque técnico, /speckit.tasks para trocearlo y /speckit.implement para ejecutarlo^[3].

Ninguna de las dos inventó la idea de escribir requisitos antes de programar. Lo nuevo es quién los lee: ahora el lector principal es un agente que va a generar el código, no un compañero que va a interpretarlos.

Cuándo escribir una spec y cuándo no

Escribe una spec cuando el cambio contiene decisiones que alguien tendrá que entender más adelante: reglas de negocio, contratos entre sistemas, casos límite que no son obvios mirando el código. Para renombrar una variable o corregir un mensaje de error, la spec cuesta más de lo que ahorra.

Si quieres el argumento completo de por qué esta práctica funciona, con los datos sobre velocidad percibida y calidad del código generado, lo tienes en la guía completa de spec-driven development. Y como SDD es una forma concreta de dirigir agentes, encaja dentro de los mismos patrones que trabajamos en el curso de patrones agénticos.

Fuentes

AWS Launches Kiro, A Specification-Driven Agentic IDE — Forbes — fecha de lanzamiento de Kiro y su flujo de requisitos, diseño y tareas.
GitHub Open Sources Kit for Spec-Driven AI Development — Visual Studio Magazine — anuncio público de Spec Kit en septiembre de 2025.
github/spec-kit, repositorio oficial — descripción del toolkit y comandos del flujo.

Preguntas Frecuentes

¿Qué significa SDD?

SDD son las siglas de spec-driven development, desarrollo dirigido por especificación. Verás las dos formas en documentación y herramientas, y significan lo mismo.

¿Es SSD o SDD? (la confusión habitual)

SDD. Al teclearlo mucha gente escribe “SSD” por error, que son los discos de estado sólido — nada que ver con especificaciones ni con agentes de código.

¿Qué es spec-driven development con IA?

Es el mismo concepto, con un matiz: la spec ya no se escribe para que la lea un compañero, sino para que la lea un agente de código de IA (Claude Code, Copilot, Cursor, Codex) y genere la implementación a partir de ella. Antes de los agentes, un documento de requisitos servía para alinear personas; ahora el lector principal es el modelo, y eso cambia lo que tiene sentido incluir: menos prosa para humanos, más criterios de aceptación verificables que el agente pueda comprobar por sí mismo.

¿Spec-driven development es lo mismo que escribir documentación?

Son cosas distintas. La documentación describe algo que ya existe y se escribe después. La spec describe algo que todavía no existe y se escribe antes, porque es la entrada que el agente lee para generar el código. Si la redactas cuando el pull request ya está mergeado, lo que has escrito es documentación.

¿Hace falta una spec para cualquier cambio?

No. Para cambios pequeños y evidentes — renombrar una variable, ajustar un mensaje de error — escribir la spec cuesta más tiempo que hacer el cambio, y acabas con un fichero que nadie va a leer. Para uno que sí lo merece —por ejemplo, cambiar cómo se calculan los reembolsos parciales— el criterio práctico es: si dentro de tres meses alguien va a preguntar “¿por qué se hizo así?”, merece una spec.

¿Cómo se relaciona spec-driven development con context engineering?

La spec es la parte estable del contexto que le das al agente: lo que merece vivir en el repositorio en lugar de reexplicarse en cada conversación. La relación completa la desarrolla la guía de spec-driven development.