DEV Community: Manuel

Spec-Driven Development (SDD): De la improvisación a la ingeniería con agentes de IA

Manuel — Sun, 13 Sep 2026 11:48:16 +0000

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.

Día 1: Spec-Driven Development (SDD): Construyendo un Comparador de Hipotecas

Manuel — Wed, 15 Jul 2026 20:16:34 +0000

¡Hola a todos! Bienvenidos al día 1 de este diario de desarrollo. Durante las próximas semanas voy a documentar el proceso paso a paso de cómo construyo una aplicación web real desde cero.

Pero no lo haré a ciegas. Para este proyecto no voy a programar de la forma tradicional, ni tampoco voy a improvisar. Voy a utilizar Spec-Driven Development (SDD) apoyándome en la herramienta de estándar abierto más potente del ecosistema: GitHub Spec Kit.

🎯 El Proyecto: El Comparador Inteligente de Hipotecas

La aplicación que vamos a construir tiene un propósito muy claro y una lógica de negocio que se presta perfectamente para el desarrollo guiado por especificaciones:

Comparador Multihipoteca: Permitirá introducir y comparar de forma simultánea hasta 3 hipotecas con sus respectivos tipos de interés (fijo, variable o mixto), plazos y comisiones de apertura.
Simulador de Vinculaciones (Complementos): Podremos añadir productos adicionales vinculados que habitualmente proponen los bancos para rebajar el diferencial de la hipoteca (seguro de vida, seguro de hogar, domiciliación de nómina, plan de pensiones, alarma, etc.).
Cálculo de Viabilidad Real (El "Árbitro Financiero"): Evaluaremos si un complemento del banco realmente merece la pena.
- Ejemplo: Si contratar el seguro de vida del banco te reduce la hipoteca un 0.1% (ahorrándote 15€ al mes en la cuota), pero ese seguro contratado con el banco cuesta 300€ anuales (25€/mes) y contratarlo por fuera de manera independiente te costaría 200€ anuales (16.6€/mes)... ¿Vale la pena la bonificación? El sistema calculará matemáticamente si estás perdiendo o ganando dinero con la vinculación.

🛠️ ¿Por qué elijo GitHub Spec Kit?

Para gestionar el ciclo de vida de este desarrollo, he elegido GitHub Spec Kit. Los motivos son muy sencillos:

Independencia de modelos (Model-Agnostic): Spec Kit no me ata a un solo proveedor de IA. Funciona mediante un CLI (specify) y plantillas estándar. Esto me permite orquestar mis especificaciones utilizando cualquier LLM tanto local (ej: qwen3.5:9b) como cloud (ej: modelos top tier de Claude, OpenAI, Gemini...)
Estructura y Comandos Estandarizados: Spec Kit nos dota de un flujo estructurado a través de comandos claros (/constitution, /specify, /plan, /tasks, /implement). No tengo que inventar la estructura de carpetas; el framework se encarga de que la especificación y el código vivan en armonía.
Sincronización nativa en Git: La especificación (en formato Markdown con metadatos YAML basados en OpenSpec) se guarda directamente en la carpeta .specify/ de nuestro repositorio. De este modo, si modificamos el comportamiento de nuestra calculadora de seguros de vida, editamos primero el archivo .md de especificación, y Spec Kit regenerará el código de forma controlada.

🥊 Tablas Comparativas: El Ecosistema de Desarrollo en 2026

Para entender el valor de lo que vamos a hacer, observemos cómo se compara SDD frente al resto de enfoques.

1. SDD vs. Metodologías de Diseño y Desarrollo (TDD y BDD)

Criterio	TDD (Test-Driven)	BDD (Behavior-Driven)	SDD (Spec-Driven / Spec Kit)
Artefacto Principal	Pruebas unitarias de código (e.g. Jest, PyTest).	Escenarios de usuario en lenguaje de negocio (Gherkin: Given/When/Then).	Especificación ejecutable estructurada (Arquitectura, reglas EARS, APIs, fórmulas matemáticas).
Foco del Proceso	Calidad del código y diseño técnico interno.	Colaboración estrecha entre desarrollo, producto y negocio.	Sincronizar el diseño humano con la ejecución ultra-precisa de agentes de IA y humanos.
Rol de la IA	Te asiste sugiriendo código para hacer pasar un test.	Puede generar tests a partir de historias de negocio escritas en lenguaje natural.	Lee la spec, genera un plan técnico estructurado, desglosa tareas y escribe el código funcional y los tests.

2. SDD vs. Vibe Coding (Improvisación con IA)

Aspecto	Vibe Coding (Improvisación)	SDD con Spec Kit (Guiado por Spec)
Aproximación	Prompts rápidos y ambiguos ("Créame un comparador de hipotecas con seguros").	Especificaciones acotadas basadas en reglas lógicas estandarizadas utilizando sintaxis EARS.
Escalabilidad	Muy baja. Al crecer la base de código, la IA sufre "degradación de contexto" y rompe funciones viejas al arreglar bugs.	Muy alta. La IA consulta la "Constitución" del proyecto y el archivo de especificación en el repo para no desviarse jamás.
Lógica Matemática	Frecuentemente errónea. Las IAs suelen fallar con fórmulas de amortización complejas si no se les guía de cerca.	Exacta. Las fórmulas financieras están explicitadas en la spec como requerimientos inflexibles que el código debe respetar.

⚙️ El Plan de Ataque: El Flujo en 4 Fases

A partir de mañana, para cada funcionalidad (como el módulo de carga de hipotecas, el simulador de seguros o la interfaz de comparación gráfica), repetiremos este ciclo soportado por Spec Kit:

Especificar (Specify): Redactaremos un archivo calculator.md bajo el estándar OpenSpec, detallando las fórmulas financieras con reglas exactas de tipo EARS ("CUANDO el usuario active el seguro de hogar, ENTONCES el sistema reducirá el diferencial en un 0.20% y sumará 250€ al gasto anual del perfil").
Planificar (Plan): El agente de IA traducirá la spec en un plan.md técnico (qué librerías usaremos para calcular las fechas, base de datos en local, etc.).
Crear Tareas (Tasks): Dividiremos el plan en tareas de programación atómicas para que puedan ser ejecutadas sin errores colaterales.
Implementar (Implement): El programador o la IA completarán cada tarea asegurándose de que los cálculos pasen la verificación frente a la spec inicial.

🚀 ¿Qué sigue?

Utilizar Spec Kit nos asegura que nuestro simulador financiero será matemáticamente preciso y perfectamente escalable a medida que añadamos más tipos de vinculaciones (como planes de pensiones o alarmas).

En el próximo post de este diario, definiremos la "Constitución" técnica de nuestra App y mucho más.

¡Nos vemos en el Día 2! ¡Déjame en los comentarios qué características te gustaría que incluyamos en el comparador!