¿Qué es el Spec-Driven Development? La metodología que termina con el código basura generado por IA

¿Cuántas veces has abierto Claude Code o Copilot, escrito un prompt vago y terminado con 500 líneas de código que no hacen lo que necesitas? No eres el único. El 62% de desarrolladores ya usa herramientas de IA en su flujo, pero la mayoría trabaja sin método: escribes, pruebas, corriges, repites. El resultado es código que funciona hoy y se rompe mañana.

El Spec-Driven Development (SDD) es una metodología que pone las especificaciones formales como contrato obligatorio antes de que la IA toque una sola línea de código. No es un framework más. Es la diferencia entre pedirle a un arquitecto que construya sin planos y entregarle un proyecto detallado con medidas, materiales y criterios de calidad.

En esta guía vas a entender qué es el SDD, cómo funciona su flujo de trabajo paso a paso, las 6 modalidades que existen hoy (OpenSpec, Spec Kit, BMAD, Kiro, Agent OS y flujos personalizados) y cuándo conviene cada una. Todo basado en el análisis de las fuentes originales de cada framework.

¿Qué es exactamente el Spec-Driven Development?

El Spec-Driven Development (SDD) es un framework donde las especificaciones formales actúan como la fuente de verdad para diseñar, implementar y validar un sistema. Funciona como una capa de planificación obligatoria antes de que la IA escriba código, estableciendo un contrato exhaustivo entre el desarrollador, los stakeholders y el agente de IA (OpenSpec Documentation, 2026).

El SDD surge por una razón concreta: cuando la barrera para escribir código baja, el volumen de líneas generadas sube exponencialmente. Sin un sistema de validación, ese volumen se convierte en una caja negra de código incoherente. El precursor de esta filosofía fue Kiro, que sentó las bases de la planificación exhaustiva antes de implementar, y de ahí evolucionaron herramientas como Spec Kit de GitHub y OpenSpec.

Los principios del SDD son cuatro. Primero, diseño exhaustivo previo: antes de programar se documenta el qué, el por qué y el plan técnico en archivos Markdown legibles por máquinas. Segundo, contrato validable: la especificación incluye criterios de aceptación detallados, happy paths y manejo de errores. Tercero, gestión del contexto de la IA: cuando el uso de la ventana de contexto supera el 40%, el rendimiento cae y la IA olvida requerimientos iniciales. Cuarto, documentación viva: las especificaciones se actualizan como deltas y se convierten en la documentación permanente del proyecto.

¿Por qué el "vibe coding" está matando tus proyectos?

El vibe coding consiste en lanzarse a generar código iterando a base de ensayo y error mediante chat. ¿Suena familiar? Escribes un prompt, la IA genera algo, no funciona, corriges el prompt, repites. Para un arreglo rápido de dos líneas puede servir. Para un proyecto real es una bomba de relojería.

El problema no es la IA. Es la falta de contrato. Cuando iteras sin especificaciones, pierdes la intención original, desperdicias tokens masivos en correcciones y alimentas las alucinaciones del modelo. Un equipo que antes lograba completar 3-5 tickets en una sesión de planificación de 3 horas ahora puede generar 10 tickets con especificaciones de 50 páginas cada uno usando SDD (FusionAI OpenSpec, 2026).

¿Y la diferencia real? Arreglar un error en la etapa de planificación cuesta minutos. Arreglarlo en código ya implementado cuesta horas. El SDD fuerza a corregir los enfoques donde es barato: en los documentos.

¿Cómo funciona el Spec-Driven Development en la práctica?

El flujo de trabajo del SDD sigue un ciclo de cuatro fases. Vamos a verlo con OpenSpec como ejemplo, el framework más adoptado y compatible con más de 20 herramientas de IA, incluyendo GitHub Copilot, Cursor y Claude Code.

Fase 1: Exploración y clarificación

El comando explore abre una sesión de pensamiento libre. La IA lee tu código actual, identifica opciones y te ayuda a clarificar el alcance. Es conversacional: debatir enfoques técnicos antes de comprometerse con nada. Si el cambio es parche de dos líneas, este paso es suficiente y te ahorras el resto.

Fase 2: Propuesta y generación del plan

Ejecutas propose <nombre-funcionalidad>. OpenSpec crea una carpeta dedicada (por ejemplo, changes/admin-dashboard). Luego ejecutas ff (fast-forward) y la IA genera el paquete completo sin tocar tu código:

• proposal.md: qué se construye y por qué

• specs/: requerimientos con formato given/when/then, criterios de aceptación, flujos de usuario

• design.md: decisiones de arquitectura y enfoque técnico

• tasks.md: lista exhaustiva de tareas atómicas en orden de implementación

¿El paso más crítico? La revisión humana. Lees los documentos y corriges errores de diseño. Arreglar un error aquí cuesta segundos; arreglarlo en código cuesta horas.

Fase 3: Ejecución del código

Apruebas los documentos, limpias la ventana de contexto y ejecutas apply. La IA lee los documentos como si fueran nuevos — rendimiento óptimo, sin degradación — y trabaja a través de tasks.md paso a paso. Si algo no cuadra, paras, actualizas la especificación y continúas.

Fase 4: Consolidación y trazabilidad

Al terminar, ejecutas archive. OpenSpec mueve la carpeta a changes/archive con timestamp y fusiona los deltas en el documento permanente del proyecto. Las especificaciones no desaparecen: se convierten en la documentación viva de lo construido y por qué.

Con este flujo, construir un dashboard de administración completo y funcional desde cero toma unos 10 minutos. Generar 39 historias de usuario detalladas a partir de una descripción vaga: 2 minutos. Un esquema completo de base de datos: 1 minuto. Y el código funciona en la primera ejecución, sin depuración ni retrabajos mayores.

¿Cuáles son las 6 modalidades del Spec-Driven Development?

Existen seis enfoques principales para implementar SDD. Cada uno tiene un punto dulce distinto según el tipo de proyecto y la madurez del equipo. OpenSpec lidera con 24.000+ estrellas en GitHub, pero no es la única opción (OpenSpec GitHub, 2026).

1. OpenSpec: el estándar

Framework open source de FusionAI. Instalación en 5 minutos, sin servicios externos ni API keys. Compatible con Copilot, Cursor y Claude Code.

Su fortaleza es la gestión de proyectos brownfield (código existente). El 99% de los desarrolladores trabaja el 99% del tiempo en repositorios que ya tienen miles de líneas. OpenSpec analiza el código actual y aplica deltas incrementales, actualizando la documentación permanente al finalizar con archive.

Cuándo usarlo: el 99% de los proyectos. Es el más equilibrado entre rigor y agilidad.

2. Spec Kit (GitHub)

Open source de GitHub. Genera especificaciones extremadamente detalladas con convenciones corporativas: numeración automática de funcionalidades, reglas constitucionales del proyecto, creación automática de ramas.

Cuándo usarlo: proyectos greenfield (de cero) en entornos corporativos donde se necesita rigor máximo desde el día 1. No está optimizado para brownfield — su estructura dificulta iterar sobre código existente.

3. BMAD: el simulador ágil completo

BMAD divide el desarrollo en 34 flujos de trabajo a lo largo de 4 fases, con 21 agentes especializados: arquitecto, analista, diseñador UX, escritor técnico... Es prácticamente un simulador de equipo de software completo.

¿El problema? Para la mayoría de proyectos es matar moscas a cañonazos. La curva de aprendizaje es pronunciada y la sobrecarga de archivos y complejidad que introduce es masiva. Funciona en compañías muy grandes con software de complejidad extrema. Para un equipo normal, es sobreingeniería pura.

Cuándo usarlo: corporaciones grandes con complejidad metodológica extrema y múltiples perfiles simulados.

4. Kiro: el pionero

Uno de los precursores del SDD. Se centró en diseños exhaustivos haciendo las preguntas correctas antes de programar, asegurando que las especificaciones fueran autocontenidas.

Cuándo usarlo: su valor es histórico. Sentó las bases, pero como Spec Kit, no preparó su flujo para proyectos brownfield.

5. Agent OS

Define un flujo que incluye planificación de producto, shape spec, redacción de especificación, creación de tareas e implementación. Su creador, Brian Castle, reconoce algo interesante: a medida que los modelos se vuelven más inteligentes, la necesidad de herramientas tan rígidas disminuye. El framework ahora prioriza la sustracción de características sobre la adición.

Cuándo usarlo: equipos que buscan un flujo intermedio y confían en el razonamiento nativo del modelo.

6. Flujos personalizados (OSDDT, AI Specs, prompting directo)

Muchos desarrolladores sénior construyen sus propios scripts. Herramientas CLI caseras como OSDDT usan comandos simples (start, spec, plan, implement) para generar salidas predecibles. Otros usan plantillas como AI Specs de LIDR configuradas con archivos MCP del IDE. Y algunos simplemente convierten requerimientos en historias de usuario, esquemas de bases de datos y listas de fases en Markdown, sin usar comandos de terminal.

Cuándo usarlo: equipos experimentados con entornos de código muy específicos (monorepos complejos, worktrees) que valoran la libertad absoluta.

¿Qué framework elegir según tu proyecto?

La elección depende de dos variables: si tu proyecto es greenfield o brownfield, y cuánta complejidad metodológica necesitas. Esta tabla resume la decisión:

¿La regla práctica? Empieza con OpenSpec. Si tu proyecto es de cero y necesitas rigor corporativo, mira Spec Kit. Si eres un equipo de uno o dos developers que quiere control total, construye tu propio flujo. Solo considera BMAD si gestionas un equipo de 20+ personas con procesos ágiles formales.

¿Cómo se compara el SDD con otras metodologías?

El Spec-Driven Development no existe en el vacío. Se relaciona con metodologías conocidas, pero las adapta a la era de la IA:

SDD vs. Vibe Coding: El vibe coding es saltar directo a generar código iterando por ensayo-error. Sirve para parches. Para proyectos reales, desperdicia tokens y genera código incoherente. El SDD fuerza a planificar donde es barato: en documentos, no en código.

SDD vs. TDD (Test-Driven Development): El TDD requiere pensar la funcionalidad basándose en tests técnicos. El SDD adapta esta filosofía expandiéndola hacia un PRD completo: escribir la idea, el plan, las tareas atómicas y luego delegar tanto la implementación como la generación de tests a la IA.

SDD vs. Copilotos sin estructura: Muchos desarrolladores usan asistentes dando una tarea y dejando que la IA genere pasos en el chat. En SDD, esa planificación no puede quedar en un chat efímero: debe plasmarse en archivos Markdown versionables para actualizarse y rastrearse.

SDD vs. Agile con IA (BMAD): El SDD estándar es directo y centrado en especificaciones granulares. BMAD simula un equipo ágil completo con 21 agentes. Para la mayoría de proyectos, BMAD es excesivo. El SDD estándar destaca por su agilidad.

Preguntas frecuentes

¿Necesito saber programar para usar Spec-Driven Development?

Sí. El SDD no reemplaza el conocimiento técnico — lo amplifica. Necesitas entender arquitectura de software para escribir buenas especificaciones y validar lo que la IA genera. Las especificaciones son el contrato, pero el desarrollador sigue siendo el responsable del sistema (OpenSpec Documentation, 2026).

¿Spec-Driven Development funciona para proyectos pequeños?

Sí, con matices. OpenSpec incluye un comando explore para cambios ligeros que no requieren todo el flujo. Para un arreglo de dos líneas, el SDD completo es excesivo. Para una funcionalidad nueva que toca 5+ archivos, los beneficios compensan desde el minuto uno. La clave es ajustar la profundidad de las especificaciones al alcance del cambio.

¿Qué herramientas de IA son compatibles con SDD?

OpenSpec es compatible con más de 20 herramientas incluyendo GitHub Copilot, Cursor, Claude Code, Windsurf y otros asistentes basados en LLM. La especificación vive en archivos Markdown que cualquier herramienta puede leer (OpenSpec GitHub, 2026).

¿Cuánto tiempo se ahorra realmente con SDD?

Generar 39 historias de usuario detalladas toma 2 minutos. Un esquema de base de datos completo: 1 minuto. Un dashboard funcional desde cero: 10 minutos. Y el código funciona en la primera ejecución sin depuración mayor. El ahorro no está en la velocidad de generación sino en la eliminación del ciclo de corrección que consume el 80% del tiempo en vibe coding.

¿El SDD reemplaza la documentación tradicional?

Sí y no. Las especificaciones SDD se convierten en documentación viva del proyecto mediante el comando archive. A medida que el proyecto avanza, los cambios se documentan como deltas sobre los archivos originales. Al finalizar una tarea, las especificaciones son la documentación permanente y actualizada de lo que existe y por qué existe (OpenSpec Documentation, 2026).

El Spec-Driven Development responde a un problema real: cuando la IA puede generar código en segundos, la especificación se convierte en el cuello de botella — y en la mayor ventaja competitiva. Los puntos clave:

• Planifica antes de codificar: arreglar errores en documentos cuesta minutos; en código, horas

• Gestiona el contexto de la IA: más del 40% de uso de la ventana de contexto degrada el rendimiento

• Elige el framework correcto: OpenSpec para el 99% de los proyectos, Spec Kit para greenfield corporativo, custom para equipos sénior

• Las especificaciones son documentación viva: no se tiran, se archivan y se actualizan con cada cambio

El SDD no es moda. Es la adaptación natural de las buenas prácticas de ingeniería de software a la era donde el código lo escribe una máquina pero la responsabilidad sigue siendo tuya.