Spec-driven development: qué es, cómo funciona y por qué importa
Durante el último año el desarrollo de software con IA se ha dividido en dos campos. Por un lado, el vibe coding: pedirle a un modelo «hazme una app que…» y aceptar lo que devuelve. Por el otro, el spec-driven development: especificar primero, generar después, validar siempre. El primero domina los titulares. El segundo, los productos que llegan a producción.
Este artículo explica qué es spec-driven development, por qué funciona, cómo se aplica con Claude Code y otros agentes, y en qué tipo de proyectos compensa el esfuerzo extra inicial.
Qué es spec-driven development
Spec-driven development (SDD) es una metodología de construcción de software en la que la especificación detallada del producto se escribe primero, y el código se genera a partir de ella, validándose contra ella en cada iteración. No es una idea nueva: la programación por contrato (Eiffel, 1988) y la formal specification (Z notation, B-method) ya planteaban algo similar hace décadas.
Lo que es nuevo en 2026 es el contexto: con modelos como Claude, GPT o Gemini capaces de generar código complejo y consistente a partir de una especificación bien construida, la spec deja de ser solo documentación. Se convierte en el contexto principal de la IA, lo que ésta consulta para escribir, modificar y mantener cada pieza del código.
La spec como single source of truth
En spec-driven development la especificación es el único documento autoritativo sobre lo que el producto debe hacer. Incluye:
- Modelos de datos (entidades, relaciones, restricciones)
- Contratos de API (endpoints, métodos, parámetros, respuestas, errores)
- Reglas de negocio (qué se puede y qué no, en qué condiciones)
- Casos de uso prioritarios y de borde
- Criterios de aceptación medibles
- No-objetivos: lo que el sistema NO va a hacer
Si una funcionalidad no está en la spec, no se construye. Si el código contradice la spec, hay que actualizar uno de los dos. Esa disciplina es lo que hace que el sistema se mantenga consistente cuando crece.
En qué se diferencia del desarrollo tradicional
En el desarrollo tradicional, la especificación suele ser un PRD genérico que el product manager escribe al inicio y que rápidamente se queda obsoleto. Las decisiones reales sobre el comportamiento del sistema acaban viviendo en el código, en los comentarios de Slack y en la cabeza de los developers senior. Cuando alguien se va, parte del conocimiento se va con él.
En spec-driven development la especificación es viva. Se mantiene actualizada con cada cambio significativo. El código y los tests se generan a partir de ella, no al revés. Y porque la mantenemos al día, sirve como documentación real, como contexto para la IA y como contrato entre el equipo de producto y el de ingeniería.
Tabla comparativa
| Aspecto | Desarrollo tradicional | Spec-driven development |
|---|---|---|
| Documento autoritativo | Código | Especificación |
| Cuándo se escribe la spec | Al inicio, luego se ignora | Continuamente, antes que el código |
| Cómo se valida | Tests escritos a mano | Tests derivados de la spec |
| Mantenimiento | Depende de quién conozca el código | Depende de la spec, transferible |
| Uso de IA | Como autocompletado | Como ejecutor con contexto completo |
| Riesgo al cambiar de equipo | Alto | Bajo |
En qué se diferencia del vibe coding
Vibe coding es la antítesis de SDD. La intención se queda vaga («una app para hacer X»), el modelo decide los detalles, el resultado puede funcionar a primera vista pero arrastra decisiones implícitas que nadie ha tomado conscientemente.
Los problemas del vibe coding se manifiestan a partir del segundo sprint:
- El modelo, sin spec, no sabe qué cambiar para implementar la siguiente funcionalidad sin romper la anterior.
- El código tiene patrones inconsistentes (a veces async, a veces sync, a veces typescript, a veces no).
- Los tests, si existen, prueban lo que se construyó, no lo que se quería.
- Cuando hay un bug, nadie sabe si el comportamiento «correcto» es el que la app hace o el que esperabas.
SDD elimina esos problemas. La spec dice qué es correcto. El modelo genera código que la cumple. Los tests validan que se cumple. Cualquier discrepancia se resuelve actualizando la spec o el código de forma explícita.
Cómo se aplica con Claude Code
Claude Code es la herramienta más adecuada para SDD a día de hoy porque permite trabajar con contexto extenso, ejecutar comandos, leer y escribir archivos directamente. El flujo típico de un sprint:
1. La spec vive en el repo
El documento de especificación se versiona junto al código. Puede ser un único SPEC.md o un conjunto de archivos por dominio (spec/domain.md, spec/api.md, spec/rules.md). Claude Code lo lee como contexto al inicio de cada sesión.
2. Cada cambio empieza por la spec
Antes de pedir código nuevo, se actualiza la spec con lo que se quiere conseguir. Esto fuerza una decisión consciente: ¿cómo debería comportarse el sistema cuando pase X?
3. Generación con criterios explícitos
El prompt al modelo no es «añade una funcionalidad de exportar a CSV». Es: «según la sección 4.2 de spec.md, implementa el endpoint de exportación. Debe cumplir los criterios de aceptación de la sección 4.2.3 y respetar el modelo de datos definido en spec/domain.md».
4. Tests derivados de la spec
Los tests se escriben (o se generan) a partir de los criterios de aceptación. Cada criterio = al menos un test. Si se cumplen los tests, la implementación se considera correcta respecto a la spec.
5. Revisión humana del código
Aunque el modelo lo genere, el código pasa por revisión humana. Lo importante: la revisión es contra la spec, no contra «¿está bonito?». Eso hace que sea más rápida y más objetiva.
Herramientas que complementan SDD
SDD funciona mejor con un stack que apoye el flujo:
- Claude Code o Cursor como entorno principal de generación e iteración.
- MCP (Model Context Protocol) para que el modelo acceda a fuentes de datos reales (Shopify, bases de datos, APIs internas) y trabaje con información en lugar de inventarla.
- Git con commits estructurados que enlacen cada cambio de código con el cambio de spec correspondiente.
- Tests automáticos derivados de los criterios de aceptación.
- Schemas estrictos (JSON Schema, Zod, Pydantic) que codifiquen las restricciones de la spec.
Cuándo conviene SDD
Cuándo SÍ tiene sentido el esfuerzo extra
- Productos que van a producción. Si el código va a ejecutarse con usuarios reales, SDD reduce errores y simplifica el mantenimiento.
- Proyectos de varios meses. El coste de la spec se amortiza cuando el segundo y el tercer sprint son más rápidos que el primero.
- Equipos que rotan. Si la gente entra y sale, la spec hace que el conocimiento no se vaya.
- Integraciones empresariales. Cuando los contratos con sistemas externos importan, la spec es el único modo de mantenerlos coherentes.
- Productos con lógica de negocio compleja. Pricing dinámico, reglas de descuento, workflows con muchos estados.
- Cuando el cliente va a auditar. Una spec clara y un código que la cumple son auditables. Vibe coding no.
Cuándo NO compensa
- Prototipos de un día para validar una idea. Aquí el coste de la spec es más alto que el beneficio.
- Scripts internos de un solo uso. Si nadie va a mantenerlo, ningún metodología importa.
- Cuando el alcance está en flux constante. Si todavía no sabes qué quieres construir, escribir spec antes es prematuro. Mejor explorar y consolidar después.
El cambio cultural: del «hazme algo» al «especifica»
El paso de vibe coding a SDD no es técnico. Es cultural. Requiere que el founder o el product owner se siente a pensar lo que quiere antes de pedirlo. Que el developer no aceptes código que «funciona» sin saber si cumple lo que se quería. Que el equipo entienda que un buen sistema con IA empieza por una buena conversación con humanos.
La buena noticia: las herramientas que necesitas para hacer SDD ya existen. Claude Code, MCP, Git, tests, schemas. Lo que faltaba era la disciplina. Y eso se aprende en dos o tres proyectos.
Cómo lo hacemos en Pango Studio
En Pango aplicamos spec-driven development en todos los proyectos serios de desarrollo a medida. Empezamos por una sesión inicial donde definimos la spec, seguimos con sprints de implementación validados contra ella y entregamos un repositorio donde código, tests y spec viven juntos.
Detalle del enfoque: desarrollo de software a medida con IA y spec-driven development. Comparativa directa: vibe coding vs spec-driven development.
Si quieres hablar de un proyecto concreto, contacta con nosotros.