Spec-driven development (SDD): qué es y cuándo usarlo
El spec-driven development (SDD), en español desarrollo guiado por especificaciones o basado en especificaciones, es escribir una especificación antes de pedirle código a un agente de IA y usarla como referencia durante todo el trabajo. En 2025 empezaron a aparecer herramientas que lo convierten en un flujo: primero la especificación, después el plan, después las tareas y, al final, el código. Aquí verás qué aporta frente a lo que ya se hacía, dónde falla y un test de pocas líneas que avisa si un criterio se queda sin probar. Es lo contrario del vibe coding, en el que se acepta el código del agente sin leerlo. Este artículo forma parte de la IA Limpia, el enfoque de esta web: IA que corre, código que dura.
La idea principal es esta: una especificación solo protege si se puede comprobar. Escribir lo que quieres antes de pedírselo a un agente es buena idea; dejarlo en un documento que nadie contrasta con el código es volver a los requisitos que se quedaban viejos en un cajón. Es el principio «Sin pruebas, no está terminado» del método IA Limpia, aplicado a la especificación.
Todo el código está en la carpeta especificacion/ del repositorio tests-que-detectan-fallos.
Los planos de la reforma
Antes de reformar una cocina, haces un plano: dónde va el fregadero, cuántos enchufes y a qué altura. El plano sirve para que el albañil y tú estéis de acuerdo antes de tirar un tabique.
Hay tres formas de usar ese plano:
- Se hace antes y se guarda en un cajón. Sirve para empezar bien, pero a los dos años nadie sabe si sigue coincidiendo con la cocina.
- Se actualiza con cada cambio. Si mueves un enchufe, cambias también el plano. Cuesta más, pero el plano sigue diciendo la verdad.
- Solo se toca el plano. Cualquier cambio en la cocina se hace en el plano, y la cocina se rehace a partir de él. Si alguien cambia algo a mano, la próxima vez desaparece.
Son, más o menos, los tres niveles del SDD. El símil se queda corto en una cosa: una cocina se ve; si el plano no coincide, lo notas al entrar. El código no se ve así: la especificación y el código pueden decir cosas distintas durante meses, y por eso hace falta algo que los compare.
Qué es el spec-driven development (SDD)
El spec-driven development es una forma de trabajar con agentes de IA en la que se escribe primero qué debe hacer el software y esa especificación guía el plan, las tareas y el código.
Birgitta Böckeler, en un artículo publicado en el sitio de Martin Fowler en octubre de 2025, lo define como escribir una especificación antes de escribir código con IA, una forma de «documentación primero». Esa especificación pasa a ser la fuente de verdad para la persona y para la IA. Y avisa de que el término todavía está cambiando y no está bien definido.
Distingue tres niveles:
| Nivel | Qué pasa con la especificación | En el símil |
|---|---|---|
| Spec-first | Se escribe primero y se usa para la tarea | El plano que se guarda en un cajón |
| Spec-anchored | Se mantiene después y guía los cambios siguientes | El plano que se actualiza con cada reforma |
| Spec-as-source | Es lo único que edita la persona; el código no se toca a mano | Solo se toca el plano |
Herramientas de SDD: Kiro, Spec Kit y Tessl
En ese artículo, Böckeler prueba tres herramientas, cada una con su flujo. Sirven como ejemplo de la idea, con fecha, no como recomendación:
- Kiro, de AWS: requisitos, diseño y tareas, con un documento Markdown por paso (
requirements.md,design.mdytasks.md). Böckeler lo sitúa sobre todo en spec-first. - Spec Kit, de GitHub: una «constitución» del proyecto y después especificar, planificar y dividir en tareas. Su repositorio, con licencia MIT, lo describe como un conjunto de herramientas que da a los agentes de código procesos estructurados y plantillas, y lo maneja con skills que se invocan en el chat del agente:
/speckit-constitution,/speckit-specify,/speckit-plan,/speckit-tasks,/speckit-implementy/speckit-converge(sintaxis por defecto de GitHub Copilot; cada agente tiene la suya). Böckeler probó una versión anterior; la consultada aquí es la 1.4.0, del 10 de noviembre de 2026. - Tessl: en beta privada cuando lo probó, apunta a los niveles más altos y marca el código generado como «no editar». Hoy su web se presenta como una plataforma de skills para agentes y ya no menciona el framework.
- OpenSpec: en noviembre de 2026, el Technology Radar de Thoughtworks lo subió a Trial porque se centra en el nivel spec-anchored: cada cambio es una diferencia sobre una especificación que se mantiene. Avisa de que mantenerla sigue exigiendo disciplina.
SDD frente a TDD, ATDD y BDD
Esta sección es interpretación nuestra, desde el enfoque IA Limpia.
La parte buena del SDD no es nueva. Acordar qué debe hacer el software antes de programarlo, con ejemplos concretos, es lo que proponen el desarrollo dirigido por tests de aceptación (ATDD) y BDD desde hace años. Y TDD añade el ciclo corto: de uno en uno, test en rojo, código para ponerlo en verde y refactor. En este blog, los artículos de ATDD y de TDD son de 2018, de antes de los agentes.
Lo que cambia es el lector. En ATDD y BDD, los criterios se convierten en tests de aceptación que se ejecutan. En SDD, la lee además un agente, que la usa para planificar y escribir el código. Eso tiene una ventaja: el agente tiene delante lo que hay que hacer en lugar de adivinarlo. Y un riesgo: si la especificación es solo texto, nada garantiza que el código la cumpla, ni que siga coincidiendo con ella después.
| ATDD y BDD | SDD | |
|---|---|---|
| Quién lee la especificación | El equipo y una herramienta que la ejecuta | El equipo y un agente que escribe el código |
| Formato | Ejemplos ejecutables (por ejemplo, Gherkin) | Normalmente Markdown: requisitos, diseño, tareas |
| Qué la mantiene al día | Que se ejecuta en cada cambio | Depende del nivel y de la disciplina del equipo |
Si los criterios se escriben como ejemplos ejecutables (Gherkin con Cucumber, por ejemplo), el criterio es el test y no hay correspondencia que vigilar. Lo que sigue hace falta cuando la especificación se queda en Markdown, que es lo habitual en SDD.
Lo que critica Böckeler
En el mismo artículo, Böckeler deja varias reservas que conviene conocer antes de adoptarlo:
- El flujo es grande para cambios pequeños. Para un fallo menor, uno de los flujos le pareció matar moscas a cañonazos.
- Hay mucho que revisar. Las herramientas generan muchos ficheros Markdown, repetitivos y largos, y escribe que prefiere revisar código antes que todos esos documentos.
- Puede dar una falsa sensación de control. Los agentes ignoraban a veces las instrucciones, o las aplicaban de más.
- Recuerda al desarrollo dirigido por modelos (MDD). Los dos niveles más altos, sobre todo el que solo edita la especificación, se parecen a aquella idea, y teme que hereden su rigidez sumada a la falta de determinismo de los modelos.
- «Especificación» se usa para casi todo. A veces no es más que un prompt detallado.
Las reservas son de octubre de 2025. Desde entonces, Spec Kit y Kiro han añadido flujos más cortos para corregir fallos, lo que responde en parte a la primera; el resto sigue en pie.
Y una más, que no es de Böckeler: todavía no hay pruebas de que reduzca defectos. El único estudio grande revisado por pares que hemos encontrado (Brenn Hill, ESEM 2026, con 88.052 pull requests de 119 proyectos de código abierto) no encuentra menos defectos cuando hay una especificación. Pero mide sobre todo referencias a issues y tickets, no el uso de herramientas de SDD, que sigue sin estudiarse. Es otra razón para que la especificación se compruebe con tests en lugar de darla por buena. En el vocabulario que Böckeler usa después para el harness engineering, la especificación es una guía y los tests son los sensores que comprueban si se ha cumplido.
Atar la especificación al código
Algunas herramientas ya lo intentan: Spec Kit pide a un agente que compare el código con la especificación (/speckit-converge), y Kiro puede generar tests basados en propiedades enlazados a cada requisito. Lo que sigue es la versión mínima, sin herramienta: una comprobación determinista que corre en la integración continua.
Si la especificación tiene que seguir diciendo la verdad (el nivel spec-anchored), hace falta algo que la compare con el código. La forma más directa, y criterio nuestro, es que cada criterio de aceptación tenga un identificador y al menos un test que lo compruebe, y que un test vigile esa correspondencia.
La especificación, en spec/descuento-socios.md:
# Descuento para socios
Los socios pagan menos en las compras grandes. Importes en céntimos.
## Criterios de aceptación
- [DS-1] Un socio con una compra de 100 € o más paga un 10 % menos.
- [DS-2] Por debajo de 100 €, el socio paga el precio completo.
- [DS-3] Quien no es socio paga siempre el precio completo.
Fíjate en lo que falta: con importes en céntimos, el 10 % de 100,01 € (10001 × 0,9) da 9000,9 céntimos, y la especificación no dice cómo se redondea. El código de abajo redondea con Math.round, pero es una decisión que nadie ha escrito. Escribir los criterios con ejemplos concretos saca a la luz estas decisiones antes de que el agente las tome por ti.
Qué debe tener una buena especificación
Es criterio nuestro, a partir del ejemplo:
- Un identificador por criterio, para poder atarlo a su test.
- Números y ejemplos, no adjetivos: «100 € o más», no «compras grandes».
- Las decisiones que no son obvias, como el redondeo.
- Lo que queda fuera, para que el agente no lo añada por su cuenta.
Los tests empiezan por el identificador del criterio que comprueban:
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { precioFinal } from '../src/descuento.js';
test('DS-1: un socio que compra 100 € paga 90 €', () => {
assert.equal(precioFinal(10000, true), 9000);
});
test('DS-2: un socio que compra 99,99 € paga el precio completo', () => {
assert.equal(precioFinal(9999, true), 9999);
});
test('DS-3: quien no es socio paga 200 € por una compra de 200 €', () => {
assert.equal(precioFinal(20000, false), 20000);
});
El código que los pone en verde, en src/descuento.js:
// Los socios pagan un 10 % menos en compras de 100 € o más (spec/descuento-socios.md).
export function precioFinal(totalEnCentimos, esSocio) {
if (esSocio && totalEnCentimos >= 10000) {
return Math.round(totalEnCentimos * 0.9);
}
return totalEnCentimos;
}
Y un test de trazabilidad comprueba la correspondencia en los dos sentidos:
// Cada criterio de la especificación tiene al menos un test que empieza por su identificador.
import { test } from 'node:test';
import assert from 'node:assert/strict';
import { readFileSync, readdirSync } from 'node:fs';
import { join } from 'node:path';
const raiz = join(import.meta.dirname, '..');
const leerTodo = (carpeta) =>
readdirSync(join(raiz, carpeta), { recursive: true, withFileTypes: true })
.filter((entrada) => entrada.isFile())
.map((entrada) => readFileSync(join(entrada.parentPath, entrada.name), 'utf8'))
.join('\n');
const criterios = [...leerTodo('spec').matchAll(/^- \[([A-Z]+-\d+)\]/gm)].map(([, id]) => id);
const testsConCriterio = [...leerTodo('test').matchAll(/test\('([A-Z]+-\d+):/g)].map(([, id]) => id);
test('la especificación tiene criterios de aceptación', () => {
assert.notEqual(criterios.length, 0, 'No se ha encontrado ningún «- [XX-n]» en spec/');
});
test('cada criterio de aceptación tiene su test', () => {
const sinTest = criterios.filter((id) => !testsConCriterio.includes(id));
assert.deepEqual(sinTest, [], `Criterios sin test: ${sinTest.join(', ')}`);
});
test('cada test con identificador corresponde a un criterio que existe', () => {
const huerfanos = testsConCriterio.filter((id) => !criterios.includes(id));
assert.deepEqual(huerfanos, [], `Tests de criterios que ya no están en la especificación: ${huerfanos.join(', ')}`);
});
node --test
✔ DS-1: un socio que compra 100 € paga 90 € (0.708478ms)
✔ DS-2: un socio que compra 99,99 € paga el precio completo (0.152698ms)
✔ DS-3: quien no es socio paga 200 € por una compra de 200 € (0.126569ms)
✔ la especificación tiene criterios de aceptación (0.711463ms)
✔ cada criterio de aceptación tiene su test (0.582429ms)
✔ cada test con identificador corresponde a un criterio que existe (4.112907ms)
ℹ tests 6
ℹ pass 6
ℹ fail 0
Si alguien, persona o agente, añade un criterio a la especificación sin su test, por ejemplo - [DS-4] El descuento no se acumula con otras promociones.:
✖ cada criterio de aceptación tiene su test (5.270683ms)
AssertionError [ERR_ASSERTION]: Criterios sin test: DS-4
Y si quita un criterio de la especificación pero deja su test, falla el otro: ✖ cada test con identificador corresponde a un criterio que existe. Y si alguien cambia el formato de la lista (por ejemplo, viñetas con *), el primero avisa de que no encuentra ningún criterio (y el de huérfanos marca todos sus tests), en lugar de dar por bueno que no hay nada que comprobar.
Con esta convención, no puede quedar un criterio sin test ni un test sin criterio. Lo que no detecta es que alguien cambie lo que dice un criterio y deje el test como estaba: con DS-1 reescrito como «50 € o más paga un 20 % menos», todo sigue en verde. Solo comprueba que el test existe, no que sea bueno: eso es trabajo de la revisión y de herramientas como las pruebas de mutación.
SDD paso a paso con un agente
Con esto, el reparto queda claro:
- La persona escribe o acepta los criterios. El agente puede proponer casos que se han escapado, pero quien decide qué debe hacer el software es el equipo. En Claude Code, eso se hace en el modo plan, como en Claude Code paso a paso.
- Un criterio cada vez: su test en rojo por la razón esperada (que falle la comprobación, no la importación), el agente lo pone en verde y se pasa al siguiente. Un test que pasa sin haber escrito código no guía nada. El ciclo completo con un agente está en TDD con IA: la kata Mars Rover.
- El agente escribe el código y sus propios tests unitarios, sin tocar la especificación, los tests de aceptación ni el test de trazabilidad: cambiar su expresión regular también lo deja en verde. Eso se vigila con un permiso o un hook y en la revisión del cambio, porque un permiso no cubre todas las formas de editar un fichero, como se explica en AGENTS.md y CLAUDE.md.
- El test de trazabilidad queda en la integración continua y avisa si la especificación y los tests se separan.
Es lo mismo que proponía el artículo de ATDD, con un paso más: la especificación en Markdown, que es lo que leen los agentes, queda atada a los tests.
Cuándo usar el spec-driven development y cuándo no
Sí: funcionalidades nuevas con reglas de negocio que se pueden escribir como criterios, y encargos largos a un agente en los que adivinar sale caro.
¿Es volver a la cascada? Kent Beck lo critica justo por ahí, según recoge Martin Fowler: las descripciones de SDD que ha visto piden la especificación completa antes de programar, como si no se fuera a aprender nada al implementar. Fowler añade que la clave para usar bien la IA es acelerar los ciclos de feedback. Desde aquí, y es interpretación nuestra, la diferencia está en el tamaño. Una especificación por cambio, atada a sus tests, no es un documento de requisitos de todo el proyecto. Si crece hasta serlo, hereda sus problemas.
¿Y en un proyecto que ya existe? No hace falta especificar todo lo que ya hay: basta con empezar por el siguiente cambio, con sus criterios, sus tests y el test de trazabilidad. Si el código que vas a tocar no tiene tests, antes conviene fijar lo que hace hoy con tests de caracterización.
Los límites:
- El término no está asentado. Lo dice la propia Böckeler, y cada herramienta lo entiende a su manera. Este artículo usa su definición y sus tres niveles.
- Las herramientas cambian deprisa. Lo que cuenta Böckeler es de octubre de 2025. Lo actual, consultado el 15 de noviembre de 2026, es de Spec Kit 1.4.0, Kiro (IDE 1.4.178) y OpenSpec 2.0.0; puede haber cambiado cuando lo leas.
- Un identificador no garantiza un buen test. El test de trazabilidad comprueba que existe una correspondencia, no que el test pruebe bien el criterio.
- La convención tiene que ser estricta. El test reconoce
- [DS-1]en la especificación ytest('DS-1: …'con comillas simples. Conit(, comillas dobles o plantillas, hay que ampliar la expresión regular. Y un test desactivado con{ skip: true }cuenta como cubierto. - No todo cabe en un criterio. Rendimiento, seguridad o accesibilidad necesitan otro tipo de comprobaciones.
- Para cambios pequeños, sobra. Un fallo de una línea no necesita una especificación; necesita un test que lo reproduzca. Es el principio «Lo más sencillo que funcione»: una especificación también es algo que mantener.
Tu siguiente paso
- Antes del próximo encargo a un agente, escribe tres o cuatro criterios de aceptación con un identificador cada uno.
- Escribe el test del primer criterio, que empiece por su identificador, y comprueba que falla por la razón esperada antes de pedir el código. Después, el siguiente.
- Añade el test de trazabilidad a tu proyecto y deja que el agente trabaje sin tocar ni la especificación ni los tests.
El contenido sobre IA envejece rápido. Última revisión: 13 de noviembre de 2026.
Ejecutado el 15 de noviembre de 2026 con Node 24.22.3 y 26.13.1 (imágenes de Docker node:24.22.3 y node:26.13.1).
Fuentes
Consultadas el 15 de noviembre de 2026.
- Birgitta Böckeler: Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl (martinfowler.com, 15 de octubre de 2025).
- GitHub: Spec Kit (repositorio, licencia MIT; versión 1.4.0, 10 de noviembre de 2026).
- Kiro: Specs (página actualizada el 12 de noviembre de 2026).
- Thoughtworks Technology Radar, vol. 35: OpenSpec (noviembre de 2026).
- Martin Fowler: Fragments: January 8 (8 de enero de 2026), con la cita de Kent Beck.
- Brenn Hill: Specification Artifacts in Open-Source Pull Request Workflows Do Not Reduce Defects, ESEM 2026, LIPIcs vol. 394.
- Tessl (web consultada el 15 de noviembre de 2026).