Spec-Driven Development: qué es y por qué lo cambia todo cuando programas con IA

Spec-Driven Development (SDD) es un enfoque de desarrollo de software en el que la especificación precede y guía al código. No es un framework, no es una metodología prescriptiva y no tiene nada que ver con volver al waterfall de los noventa. Es algo mucho más simple y más potente: escribir con precisión lo que quieres construir antes de que la IA escriba una sola línea. La especificación se convierte en la fuente de verdad del proyecto, tanto para las personas como para los agentes de IA que generan el código.

Si llevas tiempo programando con herramientas como Claude, ChatGPT, Copilot o Cursor, probablemente hayas experimentado las dos caras de la moneda. Cuando le das contexto claro a la IA, genera código que funciona. Cuando le pides algo ambiguo, genera código que parece funcionar pero que se desmorona en cuanto escalas o cambias un requisito. SDD es la diferencia entre esos dos escenarios.

El problema que intenta resolver: vibe coding y sus límites

En febrero de 2025, Andrej Karpathy acuñó el término "vibe coding" para describir un estilo de programación en el que te dejas llevar por la IA, aceptas todo lo que genera, no lees los diffs y cuando aparece un error simplemente lo copias y pegas para que la IA lo arregle. Para prototipos rápidos o proyectos personales, funciona. Para cualquier cosa que vaya a producción, es una receta para el desastre.

El problema del vibe coding no es la IA en sí, sino la ausencia de dirección. Sin una especificación clara, la IA toma decisiones por ti: elige la arquitectura que le parece, inventa nombres de campos, asume requisitos que nadie le ha dado, y genera código que técnicamente compila pero que no resuelve el problema real. Sin una especificación compartida, cada sesión con la IA es un universo paralelo que no sabe lo que pasó en el anterior.

Qué es Spec-Driven Development en la práctica

SDD propone algo directo: antes de escribir código (o de pedirle a la IA que lo escriba), defines con claridad qué vas a construir, cómo debe funcionar, qué restricciones tiene y qué estructura sigue. Esa definición es la especificación, y se convierte en el documento central del proyecto.

En la práctica, una buena especificación para desarrollo con IA incluye: el contexto de negocio (qué problema resuelve y para quién), la arquitectura técnica (stack, tablas, relaciones, endpoints), las reglas de negocio (qué puede y no puede hacer el sistema, qué validaciones aplica), las restricciones y convenciones (patrones de código, librerías permitidas, estilo de errores), y el orden de implementación (qué se construye primero y qué depende de qué). Todo esto cabe en un documento de texto o markdown que la IA puede leer al inicio de cada sesión. No hace falta un software especial. Hace falta pensar antes de generar.

Por qué SDD es especialmente importante con IA

Hay una diferencia fundamental entre trabajar con un equipo humano y trabajar con una IA: el equipo humano tiene contexto implícito. Un desarrollador que lleva tres meses en tu proyecto sabe cómo se llaman las cosas, qué patrón seguís para los controladores y por qué la autenticación funciona así. No necesitas explicárselo cada vez.

La IA no tiene nada de eso. Cada sesión nueva empieza desde cero. Si no le das una especificación, improvisará con solvencia, que es precisamente lo peligroso: generará código que parece correcto, que usa buenas prácticas genéricas, pero que no encaja con tu proyecto concreto. SDD resuelve esto convirtiendo el contexto implícito en contexto explícito. En proyectos donde la IA trabaja sin especificación, la tasa de retrabajo ronda el 40-60% según experiencias publicadas por equipos de Thoughtworks y GitHub. Con una especificación bien escrita, esa tasa baja al 10-15%.

Anatomía de una buena especificación para IA

Una especificación útil no es un documento de 50 páginas. Es un documento vivo, conciso y estructurado que contiene exactamente lo que la IA necesita para generar código de calidad. Las secciones que funcionan en el día a día trabajando con Claude y otros modelos son:

Visión general: qué se va a construir, para quién y qué problema resuelve. Dos o tres párrafos como máximo. Esto le da a la IA el "por qué" detrás de cada decisión técnica.

Stack tecnológico: lenguaje, framework, base de datos, librerías externas. Si tu proyecto es .NET Core + PostgreSQL, la IA debe saberlo antes de escribir la primera línea.

Modelo de datos: tablas, campos, tipos, relaciones, restricciones. Posiblemente la sección más importante. Una base de datos bien definida es el esqueleto del proyecto.

Reglas de negocio y flujos: qué hace el sistema paso a paso, qué estados tiene cada entidad, qué pasa cuando se cumple o no una condición. Cuanto más explícito seas aquí, menos inventará la IA.

Convenciones y restricciones: cómo se nombran las variables, qué patrón de error usas, qué librerías están prohibidas. Estas son las reglas que un desarrollador humano absorbería por ósmosis y que la IA necesita por escrito.

Orden de implementación: qué se construye primero y qué depende de qué. Crucial para proyectos grandes donde la IA trabaja en fases.

SDD no es waterfall: especificaciones vivas

La objeción más frecuente es que SDD suena a waterfall. Es una objeción legítima, pero SDD no funciona así. La diferencia clave es que la especificación evoluciona con el proyecto: se versiona, se revisa, se actualiza. Cuando necesitas añadir una nueva funcionalidad, primero actualizas la spec y después generas el código. La spec siempre refleja el estado real del proyecto, no el estado imaginado hace tres meses.

Birgitta Böckeler de Thoughtworks propone una taxonomía útil: en el nivel básico ("spec-first") escribes la spec antes de codificar y la descartas. En el intermedio ("spec-persistent") la spec se mantiene y evoluciona como parte del proyecto. En el avanzado ("spec-living") la spec se valida automáticamente contra el código. La mayoría de equipos que trabajan con IA de forma productiva operan entre el nivel básico y el intermedio, y eso ya marca una diferencia enorme frente al vibe coding.

Herramientas del ecosistema SDD

GitHub Spec Kit es un toolkit open source con CLI, plantillas y formatos estándar para escribir especificaciones y planes técnicos. Incluye un archivo "constitution.md" donde el equipo define los principios innegociables del proyecto.

Kiro, el IDE inteligente de Amazon, está construido alrededor de SDD. Permite generar especificaciones estructuradas (spec → plan → tasks) y luego implementarlas con IA de forma guiada.

Claude Projects es la opción más accesible si ya trabajas con Claude. Creas un proyecto, subes la especificación como knowledge, defines las instrucciones del proyecto con las convenciones y restricciones, y cada conversación dentro de ese proyecto hereda todo el contexto. Es SDD aplicado al flujo de trabajo con un modelo de lenguaje, sin CLI ni plugins. En nacaIA Academy enseñamos exactamente este tipo de flujos.

La realidad es que la herramienta importa menos que el hábito. Si escribes buenas specs, funcionarán con cualquier IA.

Errores comunes al adoptar SDD

Sobrespecificar: un documento de 30 páginas para 200 líneas de código es contraproducente. La spec debe tener el nivel de detalle proporcional a la complejidad del problema.

Escribir la spec y olvidarla: si la spec no evoluciona con el proyecto, se convierte en documentación muerta. Peor que no tener spec es tener una spec desactualizada.

Confundir spec con prompt: un prompt es una instrucción puntual. Una spec es el contexto permanente del proyecto. El prompt cambia en cada mensaje. La spec permanece.

No incluir lo que la IA NO debe hacer: las restricciones negativas son tan importantes como los requisitos positivos. Si tu proyecto no debe usar cierta librería o no debe crear tablas fuera del schema definido, la spec debe decirlo explícitamente.

SDD en el flujo de trabajo real: cómo se aplica

El flujo SDD con IA se reduce a un ciclo de tres pasos que se repite para cada funcionalidad.

Especificar: antes de abrir la herramienta de IA, defines qué vas a construir. Este paso puede llevar 15 minutos o 2 horas según la complejidad, pero es una inversión que se recupera multiplicada en tiempo de implementación.

Generar: le das a la IA la spec y le pides que implemente la funcionalidad. La IA genera código coherente con la arquitectura, el modelo de datos y las convenciones definidas. No improvisa porque no necesita hacerlo.

Validar: revisas lo que la IA ha generado contrastándolo con la spec. ¿Usa las tablas correctas? ¿Sigue las convenciones? ¿Implementa las validaciones definidas? Si algo se desvía, lo corriges y actualizas la spec si descubres un caso no contemplado.

Este ciclo es rápido, iterativo y produce código de calidad desde la primera pasada. En nacaIA, este es el flujo que seguimos en los proyectos de desarrollo a medida y el que enseñamos en nuestra formación.

Cuándo tiene sentido SDD y cuándo no

SDD no es para todo. Para prototipos rápidos, scripts de una sola ejecución o pruebas de concepto, basta con un prompt claro. Donde marca la diferencia es en proyectos que van a crecer, que tienen múltiples componentes interconectados o que van a ser mantenidos a lo largo del tiempo: sistemas de gestión, aplicaciones SaaS, plataformas con panel de administración, APIs con varias entidades relacionadas.

Una regla práctica: si vas a necesitar más de 3 sesiones con la IA para completar el proyecto, escribe una spec. Si vas a resolverlo en una sola conversación, probablemente no la necesites.

El futuro de SDD: especificaciones como producto

En 2026 se consolida una tendencia interesante: las especificaciones están dejando de ser un documento interno para convertirse en un entregable en sí mismo. Empresas que desarrollan software a medida están empezando a entregar no solo el código, sino la spec que lo generó, porque esa spec permite que cualquier equipo pueda mantener, extender o reconstruir el sistema sin depender del desarrollador original. Si la spec es buena, el código se puede regenerar. La spec se convierte en el activo más valioso del proyecto.

Preguntas frecuentes

¿Spec-Driven Development es lo mismo que waterfall?
No. Waterfall documenta todo el proyecto completo antes de codificar, con fases rígidas. SDD trabaja a nivel de funcionalidad: especificas lo siguiente que vas a construir, lo implementas, validas y avanzas. Es iterativo, no secuencial.

¿Necesito herramientas especiales para aplicar SDD?
No. Un archivo markdown con la especificación es suficiente. Herramientas como GitHub Spec Kit o Kiro formalizan el proceso, pero no son imprescindibles. Si trabajas con Claude, un proyecto con la spec como knowledge ya es SDD funcional.

¿Cuánto tiempo lleva escribir una buena especificación?
Para una funcionalidad sencilla, entre 15 y 30 minutos. Para un sistema completo con múltiples entidades y flujos de negocio, unas pocas horas. El tiempo se recupera con creces porque la IA produce código correcto desde la primera pasada.

¿SDD funciona con cualquier IA o solo con modelos específicos?
Funciona con cualquier modelo de lenguaje actual: Claude, ChatGPT, Copilot, Gemini o Cursor. Modelos con ventanas de contexto amplias como Claude aprovechan mejor las specs largas y detalladas.

¿Merece la pena aprender SDD si no soy programador profesional?
Sí, y de hecho es donde más impacto tiene. Sin spec, la IA genera código difícil de evaluar para alguien no técnico. Con una buena spec, puedes validar que el resultado cumple lo especificado aunque no entiendas cada línea. SDD convierte a la persona no técnica en un director de proyecto efectivo para agentes de IA.

Conclusión

Spec-Driven Development no es una moda ni una vuelta al pasado. Es la evolución natural de la forma de trabajar con IA en desarrollo de software. La IA es extraordinariamente capaz generando código, pero necesita dirección clara para generar código que sirva. El vibe coding funciona para prototipos, pero para proyectos reales que van a producción, a mantenimiento y a crecer, SDD es la diferencia entre un proyecto sólido y uno que se desmorona a las tres semanas.

Si quieres aprender a aplicar este enfoque, en nacaIA Academy trabajamos con esta metodología en todos nuestros cursos, desde automatizaciones con n8n hasta desarrollo web asistido por IA. Y si prefieres que lo implementemos nosotros, contacta con nosotros.