~/codigoagente
Agentes de IA

Qué es Spec-Driven Development (SDD): desarrollo guiado por especificaciones con agentes de IA, con ejemplo

Spec-Driven Development (SDD), o desarrollo guiado por especificaciones, es una forma de trabajar con agentes de IA en la que, antes de pedir código, se escribe una especificación: qué se construye, para quién, por qué y cómo se sabrá que funciona. De esa especificación el agente deriva un plan técnico, una lista de tareas y, al final, la implementación. El código deja de salir de una conversación improvisada y pasa a salir de un documento que tú has revisado.

En este artículo explicamos qué es SDD, de dónde sale, sus fases, qué debe llevar una buena especificación (con un spec.md de ejemplo), qué herramientas existen y cómo aplicarlo en Claude Code con o sin instalar nada. Si ya conoces SDD y te interesa la alternativa más ligera, lee ODD vs SDD.

Qué es SDD en una frase

SDD es escribir el qué antes del cómo, y el cómo antes del código, dejando cada paso en un archivo que el agente vuelve a leer en lugar de depender del historial del chat.

El problema que resuelve tiene nombre: *vibe coding*. Cuando los requisitos solo viven en los mensajes, el agente decide por ti cada detalle que no dijiste, olvida lo que dijiste hace veinte mensajes cuando el contexto se compacta y, al terminar, no hay forma de comprobar si hizo lo que pedías. OpenSpec lo resume en su README: los asistentes de IA son potentes pero impredecibles cuando los requisitos solo existen en el historial del chat.

De dónde sale

Especificar antes de programar es tan antiguo como la ingeniería de software (documentos de requisitos, casos de uso, historias de usuario). Lo nuevo es el lector: la especificación ya no la lee solo un equipo humano, sino un agente que la usa como instrucción. El término se popularizó en 2025 con tres herramientas:

  • Kiro (AWS), un IDE que genera requisitos, diseño y tareas antes de programar.
  • [GitHub Spec Kit](https://github.com/github/spec-kit) (MIT), anunciado el 2 de septiembre de 2025, que añade comandos de SDD a agentes como Claude Code, Copilot, Cursor o Gemini CLI.
  • [OpenSpec](https://github.com/Fission-AI/OpenSpec) (MIT), más ligero, organizado por cambios.

Birgitta Böckeler (Thoughtworks) distingue en martinfowler.com tres niveles: spec-first (la especificación guía una tarea), spec-anchored (se mantiene viva para evolucionar la feature) y spec-as-source (la especificación es lo único que editas y el código se regenera).

Las fases de SDD

Las siete fases de SDD con sus comandos en Spec Kit; aclarar es opcional · codigoagente

Cada herramienta les pone nombres distintos, pero el esquema es el mismo. Lo explicamos con los comandos de Spec Kit (rama principal, noviembre de 2026), que se escriben en el chat del agente, no en la terminal:

  1. Constitución (/speckit-constitution), una vez por proyecto: los principios que el agente no puede saltarse (calidad, tests, rendimiento, convenciones).
  2. Especificar (/speckit-specify <descripción>): genera spec.md con el qué y el porqué. Sin tecnología.
  3. Aclarar (/speckit-clarify, opcional): el agente busca huecos en la especificación y te hace hasta cinco preguntas concretas; tus respuestas se escriben en el propio spec.md.
  4. Planificar (/speckit-plan <stack>): genera plan.md con el cómo: stack, modelo de datos, estructura de carpetas y una comprobación contra la constitución.
  5. Tareas (/speckit-tasks): genera tasks.md, una lista ordenada por dependencias y agrupada por historia de usuario. Las tareas que se pueden hacer en paralelo llevan [P].
  6. Implementar (/speckit-implement): el agente ejecuta las tareas una a una.
  7. Converger (/speckit-converge): compara el código con la especificación, el plan y las tareas, y añade como tareas nuevas lo que falte. Se repiten implementar y converger hasta que el informe dice *Converged*.

Hay un paso más, /speckit-analyze, que revisa la coherencia entre spec.md, plan.md y tasks.md sin modificar nada. La regla de oro de todo el flujo: revisa cada archivo antes de pasar al siguiente. Si apruebas un spec.md sin leerlo, SDD no te protege de nada.

Qué lleva una buena especificación

La plantilla oficial de Spec Kit (templates/spec-template.md) es la mejor referencia que conocemos, porque obliga a separar cosas que en el chat se mezclan. Sus secciones:

SecciónQué contienePor qué importa con un agente
**Historias de usuario priorizadas**P1, P2, P3; cada una se puede probar y entregar solaLa P1 sola ya es un producto mínimo; el agente no intenta hacerlo todo a la vez
**Escenarios de aceptación***Dado / Cuando / Entonces* por historiaSe convierten directamente en tests
**Casos límite**Qué pasa en los bordes y ante erroresEs lo primero que el agente olvida si no está escrito
**Requisitos funcionales**`FR-001: El sistema DEBE...`Numerados, se pueden citar en tareas y revisiones
**Marcas de duda**`[NEEDS CLARIFICATION: ...]`El agente marca lo que no sabe en vez de inventarlo
**Entidades clave**Qué datos existen y cómo se relacionan, sin tecnologíaFija el vocabulario antes del modelo de base de datos
**Criterios de éxito**Medibles y sin tecnología: "en menos de 2 minutos"Permiten decir si la feature cumplió
**Supuestos**Lo que el agente dio por hechoLo revisas antes de que se convierta en código

La idea más útil de la plantilla es que la especificación no habla de tecnología. "El sistema DEBE impedir reservar una franja ocupada" es especificación; "añadir un índice único en la tabla bookings" es plan. Mezclarlos es el error más común.

Ejemplo: un spec.md real

Rellenamos la plantilla oficial para una feature pequeña de una app de turnos para una peluquería. Así se ve una especificación revisable en dos minutos:

specs/001-reservar-franja/spec.mdtext
# Especificación: reservar una franja

**Estado**: borrador · **Entrada**: "Los clientes reservan una franja libre de 30 minutos con un profesional."

## Escenarios de usuario

### Historia 1: reservar una franja libre (P1)
Un cliente elige profesional, día y hora libre, y confirma la reserva.
**Prueba independiente**: con un profesional y un día con franjas libres, se puede reservar y ver la reserva.

**Escenarios de aceptación**
1. **Dado** que la franja de las 10:00 del martes está libre, **cuando** el cliente la reserva, **entonces** queda reservada a su nombre.
2. **Dado** que la franja ya está reservada, **cuando** otro cliente intenta reservarla, **entonces** ve "Esa hora ya no está disponible" y no se crea la reserva.

### Historia 2: cancelar una reserva (P2)
...

### Casos límite
- Dos clientes confirman la misma franja a la vez: solo una reserva se crea.
- El cliente intenta reservar una franja pasada.

## Requisitos
- **FR-001**: El sistema DEBE mostrar solo franjas libres y futuras.
- **FR-002**: El sistema DEBE impedir dos reservas en la misma franja, también si llegan a la vez.
- **FR-003**: El sistema DEBE avisar al cliente por [NEEDS CLARIFICATION: ¿WhatsApp, correo o ninguno?].

### Entidades clave
- **Franja**: 30 minutos de un profesional en un día; libre o reservada.
- **Reserva**: una franja asignada a un cliente.

## Criterios de éxito
- **SC-001**: Un cliente completa una reserva en menos de 1 minuto desde el móvil.
- **SC-002**: Cero reservas duplicadas en la misma franja.

## Supuestos
- Las franjas duran siempre 30 minutos.
- El pago queda fuera de esta feature.

Fíjate en tres detalles: el escenario 2 trae el mensaje literal (se puede testear), FR-002 cubre el caso de concurrencia que un agente rara vez considera solo, y FR-003 está marcado como duda en lugar de inventado. Con /speckit-clarify el agente te preguntaría eso antes de planificar.

Herramientas de SDD

Spec KitOpenSpecKiro
QuiénGitHubFission AIAWS
LicenciaMITMITIDE comercial
Cómo se usaCLI `specify` (Python 3.11+ y uv) + comandos en tu agenteCLI `openspec` (Node 22.20+) + skills en tu agenteSu propio IDE
Unidad de trabajoUna feature (`specs/001-.../`)Un cambio (`openspec/changes/<cambio>/`), que se archiva al terminarUna spec por feature
Archivos`spec.md`, `plan.md`, `tasks.md` y más`proposal.md`, `specs/`, `design.md`, `tasks.md``requirements.md`, `design.md`, `tasks.md`
Formato de requisitosHistorias + *Given/When/Then* + `FR-###``SHALL` + escenarios `WHEN/THEN`Notación EARS (`WHEN ... THE SYSTEM SHALL ...`)
AgentesClaude Code, Copilot, Cursor, Gemini CLI y otrosMás de 30 asistentesEl suyo

OpenSpec (versión 2.1.0) se define frente a Spec Kit como más ligero: su flujo básico son /openspec-propose, /openspec-apply-change y /openspec-archive-change, y presume de no tener "puertas" rígidas entre fases. Spec Kit, por su parte, ya ofrece flujos aparte para bugs (specify extension add bug) y para evaluar ideas, sin pasar por el SDD completo.

Cómo aplicar SDD en Claude Code sin instalar nada

No necesitas una herramienta para hacer SDD; necesitas el orden. Este prompt reproduce el flujo con Claude Code a secas. Úsalo con el modo plan activado (Shift+Tab) para que no toque código mientras especifica:

prompttext
Vamos a hacer Spec-Driven Development para esta feature: [descripción].
1. Lee el código relacionado. No modifiques nada todavía.
2. Escribe docs/specs/[feature]/spec.md con: historias priorizadas (P1, P2...),
   escenarios Dado/Cuando/Entonces con los mensajes literales, casos límite,
   requisitos FR-001..., entidades, criterios de éxito medibles y supuestos.
   Sin tecnología. Marca lo que no sepas con [NEEDS CLARIFICATION] y pregúntamelo.
3. Para y espera a que lo apruebe.
Después: plan.md (stack, datos, archivos que cambian) y tasks.md (tareas pequeñas,
test primero, una por commit). Pide aprobación entre cada paso.

Si quieres que esto se repita en cada feature sin pegar el prompt, conviértelo en una skill: lo explicamos en qué son las skills de Claude Code. Y si prefieres que el agente te entreviste para sacar la especificación, las skills to-spec y to-tickets de Matt Pocock hacen justo eso.

Ventajas y límites de SDD

Ventajas

  • Menos sorpresas: decides el comportamiento antes de que exista código que defender.
  • Contexto que sobrevive: el agente relee el archivo, no un resumen de la conversación.
  • Revisión más barata: revisar una especificación de una página es más rápido que revisar 600 líneas de código equivocado.
  • Criterios de aceptación listos para tests: los escenarios *Dado / Cuando / Entonces* se convierten en tests casi literalmente (te lo explicamos en SDD vs TDD vs BDD vs DDD).

Límites

  • Desproporción: aplicado a todo, un bug de tres líneas genera varios Markdown. Böckeler vio a Kiro convertir una corrección pequeña en cuatro historias con 16 criterios de aceptación.
  • Mucho texto que revisar: si no lees los archivos, el coste está y el beneficio no.
  • El agente no siempre obedece: una especificación larga no garantiza que el agente la siga; por eso importan los tests y el paso de convergencia.

Por esos límites nació ODD (*Organic Driven Development*), que aplica la especificación solo cuando la tarea es grande. Lo comparamos con datos en ODD vs SDD.

Cuándo usar SDD

  • Sí: proyectos nuevos, features de varias sesiones, trabajo para un cliente que tiene que aprobar el alcance, equipos donde varias personas o agentes implementan contra el mismo contrato, sectores con trazabilidad de requisitos.
  • No hace falta: bugs que entiendes, ajustes de estilo, cambios que se pueden retomar mirando el git diff.
  • Término medio: SDD ligero al empezar (un PRD, la arquitectura y los tickets) y tareas directas con test primero después.

Errores frecuentes

  • Meter tecnología en la especificación. "Usar Postgres con un índice único" va en el plan. Si está en spec.md, no podrás cambiar de idea sin reescribir los requisitos.
  • Aprobar sin leer. El valor de SDD está en tu revisión entre fases. Sin ella, solo has añadido archivos.
  • Criterios sin mensajes ni números. "Debe ser rápido" no se puede comprobar; "en menos de 1 minuto" sí.
  • No marcar las dudas. Si el agente rellena huecos sin preguntar, la especificación parece completa pero contiene decisiones que nadie tomó.
  • Dejar morir la especificación. Si cambias el comportamiento en el código y no en spec.md, la próxima feature partirá de un documento falso.

Preguntas frecuentes

¿Qué significa SDD en programación?

*Spec-Driven Development*, desarrollo guiado por especificaciones: escribir una especificación revisable antes de que un agente de IA (o una persona) implemente. No confundir con SSD, que es un tipo de disco.

¿SDD es lo mismo que escribir un PRD?

Se parecen. Un PRD describe un producto entero para personas; la especificación de SDD describe una feature con un formato pensado para que un agente la ejecute y la compruebe: requisitos numerados, escenarios testeables y marcas de duda.

¿Necesito Spec Kit para hacer SDD?

No. Spec Kit, OpenSpec o Kiro automatizan el flujo y dan plantillas, pero con un prompt como el de este artículo y una carpeta docs/specs/ puedes hacer SDD en cualquier agente.

¿SDD funciona con Claude Code?

Sí. Spec Kit y OpenSpec tienen integración con Claude Code, y el flujo manual funciona con el modo plan.

¿SDD sustituye a los tests?

No. Los escenarios de la especificación dicen qué tests deben existir; los tests son los que comprueban que el código cumple. La plantilla de constitución de Spec Kit propone como ejemplo un principio de test primero.

Conclusión

SDD consiste en poner por escrito, antes del código, lo que quieres y cómo sabrás que está bien, y en que el agente trabaje desde ese documento. Su mayor valor está en la especificación (historias priorizadas, escenarios testeables, requisitos numerados y dudas marcadas), no en la herramienta. Empieza por el prompt de este artículo en tu próxima feature grande y reserva el flujo completo para cuando el alcance lo justifique.

Del spec al proyecto en producción

Escribir la especificación es el primer paso; después hay que convertirla en tickets, trabajar con memoria entre sesiones, revisar el código y desplegar. La guía Claude Code de cero a producción recorre ese camino completo con un proyecto real (precisamente una app de turnos para una peluquería): planificación con SDD ligero y ODD, plantillas de PRD, arquitectura y tickets, skills para planificar y revisar, y despliegue en Vercel o en tu VPS. Incluye 68 prompts listos para copiar. Cuesta 19,99 USD, pago único: consigue la guía aquí.

Fuentes: GitHub Spec Kit (README, templates/spec-template.md y templates/commands/) · OpenSpec (README, v2.1.0) · Kiro: conceptos de specs · Birgitta Böckeler, "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl".

// código fuente

Repositorios del artículo
El código del que habla este artículo es público: revísalo, dale una estrella o clónalo desde aquí.

Nos ayuda a crecer

codigoagente es gratis y sin muros de pago. Si este artículo te sirvió, cualquiera de estas cosas mantiene el blog en marcha.

// newsletter

Un correo a la semana con los repos que valen la pena

Los artículos nuevos de la semana, probados con código real. Sin spam; te das de baja con un clic.

Agentes de IA

guía · Guía completa de ECC para Claude Code · #8

AgentShield, el escáner de ECC, revisa CLAUDE.md, settings.json, MCP, hooks y agentes. Lo probamos con una configuración vulnerable y con el propio ECC.
  • Seguridad y revisión de código
  • Claude Code
leer artículo
Agentes de IA

guía · Guía completa de ECC para Claude Code · #7

Medimos cuánto contexto ocupa ECC con /ecc:context-budget --audit (unos 12.500 tokens en el perfil minimal) y cómo recortarlo: modelo, compactación y MCP.
  • Claude Code
  • Skills para tus agentes
leer artículo
Agentes de IA

guía · Guía completa de ECC para Claude Code · #6

Qué hacen los 28 hooks de ECC, cómo GateGuard frena la primera edición, cómo guardar y retomar sesiones y cómo funcionan los instincts del aprendizaje continuo.
  • Claude Code
  • Skills para tus agentes
leer artículo