Hacer desarrollo asistido por IA hoy en día suele caer en dos extremos: o bien el llamado vibe coding (abrir el chat, tirar un prompt ambiguo y rezar para que compile), o saltar directamente a herramientas y frameworks como spec-kit u open-spec sin entender los principios de base.
A partir del curso de MoureDev, este artículo desglosa los fundamentos de Spec-Driven Development (SDD): qué es, sus niveles de adopción, sus artefactos clave, la sintaxis EARS y una guía práctica paso
a paso.
1. ¿Qué es SDD y por qué surge?
El problema del Vibe Coding
El vibe coding es fantástico para prototipar en 15 minutos: le pides a un LLM que te monte una aplicación y lo hace. Sin embargo, a medida que el proyecto crece, el enfoque colapsa por cuatro razones:
- Pérdida y saturación de contexto: El modelo olvida decisiones previas.
- Alucinaciones arquitectónicas: Introduce librerías innecesarias o refactoriza código funcional sin avisar.
- Código espagueti: Parches sobre parches sin una visión global coherente.
- Falta de verificabilidad: No hay forma certera de comprobar si el modelo cumplió el 100% de lo que se le pidió.
La solución: SDD como puente con el SDLC clásico
Spec-Driven Development (SDD) traslada los principios del ciclo clásico de vida del software (SDLC) a la interacción con agentes de IA:
| Fase del SDLC | Equivalente en SDD | Rol de la IA y del desarrollador |
|---|---|---|
| Planificación y reglas | constitution.md |
Define los límites técnicos y las reglas innegociables del proyecto. |
| Análisis de requisitos | spec.md |
La IA entrevista al desarrollador para definir qué debe hacer el sistema y por qué. |
| Diseño arquitectónico | plan.md |
Se define cómo se implementará la solución: módulos, datos, contratos y decisiones técnicas. |
| Desglose del trabajo | tasks.md |
Se crean tareas pequeñas, preferiblemente de menos de 30 minutos, ordenadas por dependencias. |
| Implementación | Ejecución tarea a tarea | La IA escribe primero los tests, después el código, ejecuta las comprobaciones y se detiene al terminar la tarea asignada. |
| Testing y QA | Validación contra la especificación | Se audita cada requisito funcional y se comprueba qué test demuestra su cumplimiento. |
| Mantenimiento | Ciclo de cambio | Todo cambio comienza actualizando la especificación, no modificando directamente el código. |
Principio fundamental: la IA no debe decidir por sí sola el alcance ni improvisar la arquitectura. Primero se acuerda y aprueba la especificación; después, la IA implementa bajo supervisión.
2. Los 3 tipos de SDD: Grado de compromiso con la Spec
Se puede clasificar el SDD según el papel que desempeña la especificación frente al código:
| Nivel de compromiso | Enfoque | Fuente de verdad |
|---|---|---|
| Bajo | Spec-first | El código |
| Medio | Spec-anchored | El código y la especificación sincronizados |
| Alto | Spec-as-source | La especificación |
Cuanto mayor es el nivel de compromiso, más importante resulta mantener la especificación actualizada y utilizarla como referencia para diseñar, implementar y validar el sistema.
1. Spec-First (Nivel Bajo)
- Concepto: La especificación se redacta al inicio para alinear ideas y arrancar el desarrollo.
- Comportamiento: Una vez que el código empieza a evolucionar, la spec se abandona y suele quedar desactualizada.
- Fuente de verdad: El código.
- Cuando se usa: Prototipos rápidos donde se necesita claridad inicial, pero el ciclo de vida será corto.
2. Spec-Anchored (Nivel Medio — El estándar recomendado)
- Concepto: La especificación acompaña al código durante toda la vida del proyecto.
- Comportamiento: Si un requisito cambia o se añade una feature, está prohibido tocar el código directamente: primero se actualiza la spec, se aprueba el diff, se ajustan el plan y las tareas, y finalmente se implementa.
- Fuente de verdad: El tándem Código + Specs sincronizadas.
- Cuando se usa: Proyectos reales en producción y equipos profesionales. Es el enfoque enseñado en el curso.
3. Spec-as-Source (Nivel Alto / Radical)
- Concepto: La especificación es el programa.
- Comportamiento: El desarrollador no edita el código ejecutable; este se compila o regenera automáticamente por la IA a partir de la spec.
- Fuente de verdad: La Spec exclusivamente.
- Cuando se usa: Sistemas formales, DSLs (Domain Specific Languages) o flujos de generación determinista de pipelines. ────── ## 3. Las piezas y artefactos del ecosistema
Para trabajar con SDD sin herramientas complejas, solo necesitas una estructura ordenada de archivos Markdown:
mi-proyecto/
├── AGENTS.md # Contexto, herramientas y reglas operativas del agente
├── docs/
│ └── constitution.md # Principios innegociables del proyecto
└── specs/
└── 001-nombre-feature/
├── spec.md # Qué y Por qué (criterios en EARS)
├── plan.md # Cómo (arquitectura, datos, decisiones técnicas)
└── tasks.md # Desglose de tareas con checkboxes y criterios de fin
1. Constitución (constitution.md)
Se escribe una sola vez por proyecto. Son directrices cortas (máx. 15 líneas) e innegociables:
- Límites del stack (ej.: "Python 3.12+ y solo biblioteca estándar").
- Separación de responsabilidades (ej.: "Lógica separada de la CLI").
- Política de tests (ej.: "Ninguna tarea avanza con tests en rojo").
- Regla de oro: "La spec manda. Si algo no está especificado, no se programa".
2. Contexto del Agente (AGENTS.md)
El archivo donde el agente consulta los comandos de ejecución (pytest, linters), el estilo del código y la regla de parada obligatoria tras cada tarea.
3. La Especificación (spec.md)
Contiene únicamente el QUÉ y el POR QUÉ. Prohibido hablar de nombres de archivos, bases de datos o librerías aquí.
Incluye:
- Contexto y objetivo.
- Historias de usuario.
- Requisitos Funcionales (RF) numerados usando notación EARS.
- Casos límite (duplicados, cadenas vacías, archivos corruptos).
- Fuera de alcance (lo que explícitamente NO se construirá en esta iteración).
- Criterios de finalización y dudas abiertas ([NECESITA ACLARACIÓN]).
4. El Plan Técnico (plan.md)
Contiene el CÓMO. Traduce los RFs en ingeniería:
- Módulos y responsabilidades.
- Estructura y esquema del modelo de datos.
- Algoritmos clave en pseudocódigo.
- Decisiones técnicas justificadas y la alternativa que fue descartada.
- Estrategia de tests (qué y cómo se va a testear).
5. Lista de Tareas (tasks.md)
Desglose de tareas pequeñas (de 20 a 30 minutos como máximo), ordenadas por dependencias estrictas. Cada tarea
indica qué RFs cubre y contiene una cláusula explícita: "Hecho cuando: ".
4. El corazón de la Spec: Notación EARS
El lenguaje natural ordinario es impreciso. Para que un agente de IA no interprete libremente los requisitos, se
utiliza EARS (Easy Approach to Requirements Syntax).
EARS define cinco patrones universales para redactar requisitos funcionales de forma clara y verificable:
| Tipo de patrón | Plantilla sintáctica | Ejemplo |
|---|---|---|
|
Ubicuo Siempre activo |
EL SISTEMA [comportamiento] |
EL SISTEMA almacenará todos los datos en un único archivo JSON local y legible. |
| Dirigido por evento | CUANDO [evento], EL SISTEMA [respuesta] |
CUANDO el usuario ejecute habits done <nombre>, EL SISTEMA registrará la fecha actual como completada. |
| Dirigido por estado | MIENTRAS [estado], EL SISTEMA [respuesta] |
MIENTRAS no exista ningún hábito registrado, EL SISTEMA mostrará un mensaje invitando a crear el primero. |
|
Comportamiento no deseado Errores |
SI [condición], ENTONCES EL SISTEMA [respuesta] |
SI el hábito ya estaba marcado como hecho hoy, ENTONCES EL SISTEMA informará de que ya estaba registrado y no lo duplicará. |
| Funcionalidad opcional | DONDE [opción activa], EL SISTEMA [respuesta] |
DONDE se pase la opción --ayer, EL SISTEMA registrará la fecha del día anterior en lugar de la fecha actual. |
5. Mini-Guía: El Flujo SDD Paso a Paso
A continuación tienes el ciclo de trabajo completo con los prompts esenciales extraídos de prompts.md y aplicados en README.md.
flowchart TD
A["0. Constitución"] --> B["1. Especificación<br>(spec.md)"]
B --> C["2. Clarificación<br>(Auditoría QA)"]
C --> D["3. Plan técnico<br>(plan.md)"]
D --> E["4. Tareas<br>(tasks.md)"]
E --> F["5. Implementación TDD<br>(Tn a Tn)"]
F --> G["6. Validación<br>(RF frente a tests)"]
G --> H{"¿Nuevo requisito?"}
H -- "Sí" --> B
H -- "No" --> I["Fin: feature completada"]Paso 0: Constitución (Reglas del juego)
- Objetivo: Acotar el terreno antes de escribir nada.
- Prompt esencial: "Proponme la constitución de este proyecto: 6 principios cortos y verificables sobre stack, calidad, tests, persistencia e idioma. Máx. 15 líneas. Espera mi aprobación."
Paso 1: Especificación mediante entrevista dirigida
- Objetivo: Obligar a la IA a hacer preguntas clarificadoras en lugar de escribir código.
- Prompt esencial: "NO escribas código. Vamos a redactar la spec de la funcionalidad X. Hazme preguntas de UNA en UNA (máx. 6) sobre casos límite, errores y alcance. Con mis respuestas, genera spec.md con RF numerados en EARS, fuera de alcance y criterios de finalización. Solo el QUÉ y el POR QUÉ."
Paso 2: Clarificación (El rol de QA)
- Objetivo: Auditar la spec antes de diseñar la solución técnica.
- Prompt esencial: "Revisa spec.md como un QA profesional: busca ambigüedades, contradicciones entre requisitos, casos límite ausentes o conflictos con la constitución. Solo detecta, NO resuelvas todavía."
Paso 3: Planificación Técnica
- Objetivo: Cerrar las decisiones arquitectónicas y el modelo de datos.
- Prompt esencial: "Lee constitución y spec.md. NO escribas código: genera plan.md con módulos, modelo de datos, algoritmos en pseudocódigo, decisiones justificadas (incluyendo la alternativa descartada) y estrategia de tests. Indica qué RF cubre cada parte."
Paso 4: Desglose de Tareas
- Objetivo: Generar unidades de trabajo pequeñas y dependencias claras.
- Prompt esencial: "A partir de spec.md y plan.md, genera tasks.md con tareas pequeñas (< 30 min), ordenadas por dependencia, cada una con sus RF asociados y una línea 'Hecho cuando:' verificable. Con checkboxes."
Paso 5: Implementación TDD controlada (La regla de oro)
- Objetivo: Evitar que el agente se desboque o implemente de más.
- Prompt esencial: "Implementa SOLO la tarea T2 de tasks.md, siguiendo plan.md y la constitución. Escribe primero los tests, luego el código. Ejecuta la suite de tests y muéstrame el resultado. Al terminar: marca T2 en tasks.md, indica qué RF cubre y PÁRATE. No empieces T3."
Paso 6: Validación cruzada
- Objetivo: Asegurar cobertura total de requisitos antes de dar por cerrado el trabajo.
- Prompt esencial: "Recorre spec.md requisito por requisito (RF-1 a RF-n). Para cada uno indica: qué test lo cubre y el resultado de su ejecución. Comprueba los criterios de finalización y dame un veredicto: ¿spec cumplida?"
Paso 7: Gestión de Cambios
- Objetivo: Evitar que el código se desincronice de la documentación.
- Prompt esencial: "Nuevo requisito: . NO toques código todavía. Actualiza primero spec.md (nuevo RF en EARS y casos límite) y muéstrame el diff."
6. Conclusión para un desarrollador mid-level
Como desarrollador con experiencia, notarás que herramientas como spec-kit o open-spec no hacen magia: son simplemente automatizaciones de este mismo ciclo (scaffolding, comandos CLI y linters de markdown).
La verdadera fortaleza de Spec-Driven Development reside en:
- Reducir la ventana de contexto de la IA: Cada fase tiene un contexto delimitado (la fase de spec ignora la implementación; la fase de implementación solo mira la tarea actual y el plan).
- Determinismo y verificabilidad: Un test unitario asociado a un RF-x redactado en EARS es un contrato cerrado.
- El humano como arquitecto y árbitro: La IA asume la carga de escribir tests y código repetitivo, mientras tú tomas las decisiones críticas en la especificación y el diseño.
Top comments (0)