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
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:
- Constitución (
/speckit-constitution), una vez por proyecto: los principios que el agente no puede saltarse (calidad, tests, rendimiento, convenciones). - Especificar (
/speckit-specify <descripción>): generaspec.mdcon el qué y el porqué. Sin tecnología. - 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 propiospec.md. - Planificar (
/speckit-plan <stack>): generaplan.mdcon el cómo: stack, modelo de datos, estructura de carpetas y una comprobación contra la constitución. - Tareas (
/speckit-tasks): generatasks.md, una lista ordenada por dependencias y agrupada por historia de usuario. Las tareas que se pueden hacer en paralelo llevan[P]. - Implementar (
/speckit-implement): el agente ejecuta las tareas una a una. - 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ón | Qué contiene | Por qué importa con un agente |
|---|---|---|
| **Historias de usuario priorizadas** | P1, P2, P3; cada una se puede probar y entregar sola | La 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 historia | Se convierten directamente en tests |
| **Casos límite** | Qué pasa en los bordes y ante errores | Es 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ía | Fija 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 hecho | Lo 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:
# 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 Kit | OpenSpec | Kiro | |
|---|---|---|---|
| Quién | GitHub | Fission AI | AWS |
| Licencia | MIT | MIT | IDE comercial |
| Cómo se usa | CLI `specify` (Python 3.11+ y uv) + comandos en tu agente | CLI `openspec` (Node 22.20+) + skills en tu agente | Su propio IDE |
| Unidad de trabajo | Una feature (`specs/001-.../`) | Un cambio (`openspec/changes/<cambio>/`), que se archiva al terminar | Una 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 requisitos | Historias + *Given/When/Then* + `FR-###` | `SHALL` + escenarios `WHEN/THEN` | Notación EARS (`WHEN ... THE SYSTEM SHALL ...`) |
| Agentes | Claude Code, Copilot, Cursor, Gemini CLI y otros | Más de 30 asistentes | El 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:
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
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.
- Compártelo con alguien a quien le sirvaWhatsAppLinkedInXFacebook
- Llévate el kit para agenciasVer qué incluyeComprar
- Conoce a nuestro patrocinadorSafe Build Labs
Más sobre Agentes de IA

guía · Guía completa de ECC para Claude Code · #8
- Seguridad y revisión de código
- Claude Code

guía · Guía completa de ECC para Claude Code · #7
- Claude Code
- Skills para tus agentes

guía · Guía completa de ECC para Claude Code · #6
- Claude Code
- Skills para tus agentes