Guía Completa. Spec-Driven Development: qué es y cómo aplicarlo con IA
Tabla de contenidos
Llevas seis meses con Copilot abierto. Has prompteado tantas veces que ya sabes qué frase funciona y cuál no. Pero cada vez que el PR llega a code review pasa lo mismo:
«Esto está bien, pero no es exactamente lo que pedíamos».
El problema no es la IA. Es que no le has dado una spec.
Y Spec-Driven Development es el método de trabajo que lo soluciona.
¿Qué es Spec-Driven Development?
Spec-Driven Development (SDD) es una metodología de desarrollo de software guiado por especificaciones claras y formales que actúan como fuente de verdad para diseñar, implementar y validar el sistema.
Es decir, la especificación precede y guía al código. En lugar de empezar a escribir —o a promptear— y ver qué sale, primero defines qué quieres construir, por qué, y bajo qué criterios. Esa especificación funciona como fuente de verdad: tanto para ti como para la IA que genera el código a partir de ella.
La idea no es nueva. Lo que cambia es el contexto. Hasta hace poco, una spec era un documento que alguien leía una vez y archivaba. Hoy, con agentes de IA capaces de escribir features enteras, la spec se convierte en el artefacto que el agente ejecuta. Si la spec está clara, el agente ejecuta. Si no, improvisa. Y cuando un agente improvisa sobre un sistema en producción, lo descubres tarde y mal.
Conviene quitar un malentendido de encima cuanto antes: SDD no es waterfall. No es escribir un documento de 40 páginas, congelarlo y no tocarlo nunca más. La spec evoluciona, se versiona y se actualiza igual que el código. Mantener software, en este paradigma, significa mantener especificaciones. El código pasa a ser la última milla.
Por qué sin spec tu agente improvisa (y tú lo pagas en code review)
Hagamos memoria. En 2023 todos aprendimos a promptear. En 2024 usábamos la IA como un autocompletado con esteroides: sugería, nosotros revisábamos línea a línea. El control seguía siendo nuestro.
En 2026 el modelo operativo es otro. Los agentes —Claude Code, Codex, Cursor en modo agente— no sugieren: ejecutan. Generan PRs enteros, escriben sus propios tests, abren ramas. La capacidad de revisar cada línea a mano, sencillamente, desaparece. Y cuando no hay spec compartida, cada agente toma decisiones de arquitectura por su cuenta.
Aquí es donde mucha gente asume que la IA, por sí sola, te hace más rápido.
Los datos dicen otra cosa.
En julio de 2025, el laboratorio independiente METR publicó un ensayo controlado aleatorizado con developers open source experimentados resolviendo tareas sobre sus propios repos. Antes de empezar, los participantes predijeron que la IA les aceleraría un 24%. El resultado medido fue el contrario: tardaron un 19% más con IA que sin ella. Y lo más revelador: al terminar, seguían convencidos de haber ido más rápido.
Y es que sin método, la IA añade fricción invisible: prompts ambiguos, validación constante de outputs, cambios de contexto. La spec es lo que convierte esa fricción en estructura. No te hace más rápido por arte de magia. Te hace predecible. Y en sistemas reales, predecibilidad gana a velocidad.
Qué incluye una buena spec (y qué hace que el agente se pierda)
El malentendido más frecuente al acercarse a SDD es confundirlo con escribir más documentación. No es eso. Documentar el código que ya existe es arqueología. Especificar antes de implementar es ingeniería.
La diferencia importa: cuando especificas primero, el proceso de escritura es en sí una herramienta de pensamiento. Te obliga a descubrir los edge cases antes de que lleguen a producción y a tomar decisiones de diseño antes de que sean caras de cambiar.
Antes de ver el ciclo completo, conviene entender que no hay una spec: hay dos niveles que deben convivir.
| Tipo | Qué define | Cuándo se escribe | Quién la mantiene |
|---|---|---|---|
| Spec de sistema | Arquitectura, convenciones globales, modelo de datos, patrones y decisiones técnicas permanentes del proyecto | Al inicio del proyecto; se actualiza con cada decisión de arquitectura significativa | Tech Lead / CTO |
| Spec de feature | Un cambio concreto dentro del sistema: qué se construye, sus criterios de aceptación, sus restricciones y sus tareas | Antes de cada ciclo de desarrollo, por cada feature o historia de usuario | Developer responsable |
La spec de sistema le dice a la IA cómo es el mundo donde vive el proyecto. La spec de feature le dice qué tiene que hacer hoy. Cuando solo existe la de feature, el agente genera código que funciona pero rompe los patrones del equipo. Cuando solo existe la de sistema, el agente no sabe qué construir ahora. Las dos se necesitan.
Si quieres ver cómo es una spec de sistema real antes de escribir la tuya, el equipo de LIDR mantiene lidr-specboot en GitHub: un conjunto de reglas de desarrollo, estándares y configuraciones de agentes IA listo para importar en cualquier proyecto. Es exactamente el tipo de artefacto que actúa como spec de sistema — portable, versionado y compartido por todo el equipo.
Qué incluye una spec de feature
Una spec no es un documento de 50 páginas. Es un Markdown estructurado con los elementos mínimos para que tanto el developer que revisa como el agente que ejecuta entiendan exactamente qué se quiere y por qué.
| Elemento | Qué responde | Ejemplo concreto |
|---|---|---|
| Objetivo | ¿Por qué lo hacemos? | Reducir el tiempo de revisión de candidatos eliminando la navegación manual entre perfiles |
| Capacidades | ¿Qué debe hacer el sistema? | Permitir filtrar por estado (activo / descartado / en proceso) y ordenar por score |
| Criterios de aceptación | ¿Cómo sabemos que está bien? | Dado un recruiter con 50 candidatos, cuando filtra por «en proceso», solo ve esos candidatos y el contador se actualiza |
| Restricciones | ¿Qué no puede hacer? | Sin modificar el modelo de datos existente. Sin afectar el rendimiento en listas de más de 1.000 candidatos |
| Decisiones técnicas | ¿Cómo lo hacemos? | Filtrado en cliente para listas < 500 registros; server-side para listas mayores |
| Casos de error | ¿Qué pasa cuando falla? | Si el API devuelve 500, mostrar banner no bloqueante. Si la lista queda vacía, mostrar CTA para limpiar filtros |
| Tareas | ¿Qué pasos de implementación? | 1. Componente FilterBar con tests. 2. Integrar en CandidateList. 3. Test E2E del flujo completo. |
El mismo agente. El mismo modelo. La única variable es el input.
| ❌ Spec incompleta | ✅ Spec bien escrita |
|---|---|
| «Añadir filtros a la lista de candidatos» | «Añadir filtro de estado a CandidateList con comportamiento server-side para listas > 500 registros, sin modificar CandidateService» |
| El agente genera filtros en cliente para todos los casos, sin tests de edge case, con estructura propia que no encaja con el componente existente | El agente genera lógica condicional cliente/servidor, tests para ambas ramas y código que extiende el componente existente respetando sus patrones |
| Explota en code review («esto no era lo que pedí»), en QA (falla con 600 candidatos) y en producción | PR aprobado en primera revisión. Criterios de aceptación validados antes de que llegue al revisor humano |
Un dato que lo contextualiza: el 65% de developers reporta que la IA pierde el contexto relevante en tareas críticas —refactoring, tests, code review— según el Qodo State of AI Code Quality 2025. Y esto es un fallo del input. La spec es lo que convierte ese input en algo con el que un agente puede trabajar.
Mejores prácticas flujo SDD. El ciclo OpenSpec: de la User Story al código validado en 6 pasos
El ciclo que usamos en LIDR se implementa con OpenSpec.
Tiene seis fases:
- User Story — el requisito de partida en lenguaje de negocio. Qué se quiere construir y por qué, sin entrar todavía en el cómo.
- Refined User Story — el agente enriquece y clarifica la historia, añade contexto técnico y detecta ambigüedades antes de que se conviertan en bugs.
- Proposal Artifacts (la spec) — el agente genera la propuesta técnica: criterios de aceptación, arquitectura, plan de tareas. Aquí está la fuente de verdad.
- Apply — con la spec aprobada, el agente genera los artefactos de implementación: rama, tests, documentación, código y testing report.
- Revisión humana + PR — el developer revisa que el output cumple la spec (no cada línea: los criterios). Code review y commit.
- Verify + Archive — verificación final y cierre. La spec queda archivada como registro del ciclo.
Un ejemplo concreto. Imagina que quieres añadir login con magic link. En el flujo improvisado, abres el chat y escribes «añade login con magic link» y rezas. En el flujo OpenSpec, la Proposal ya dice: qué endpoints, qué pasa si el enlace caduca, cómo se gestiona el rate limiting, qué eventos se loguean, qué tests deben pasar. El agente no decide esas cosas por ti. Las ejecuta contra la spec.
La diferencia no es cuánto tardas en escribir la primera versión. Es cuántas veces vuelves atrás.
Herramientas y frameworks para empezar con SDD
No hay una herramienta «correcta». Hay la que tu equipo va a usar sin fricción. Una comparativa rápida para situarte:
| Herramienta | Para qué brilla | Cuándo elegirla |
|---|---|---|
| OpenSpec (LIDR) | Framework CLI con ciclo completo integrado: User Story → Refined → Proposal → Apply → PR → Archive. Es el que usamos en AI4Devs. | Si quieres el flujo completo con el método que enseñamos en LIDR |
| BMAD-Method | Framework alternativo con roles de agente definidos (PM, Architect, Developer). Más estructurado para equipos grandes. | Si tu equipo necesita roles diferenciados en el flujo |
| GitHub Spec Kit | Toolkit open source, agnóstico de IDE. Funciona con Copilot, Claude Code y Cursor | Si quieres el flujo canónico y empezar por lo más estándar |
| Kiro (AWS) | IDE basado en VS Code con flujo Requirements → Design → Tasks integrado | Si tu equipo quiere todo en un mismo entorno |
| Claude Code + CLAUDE.md | La spec vive en el repo como archivo versionado | Si ya trabajáis en terminal y queréis spec viva |
| Cursor + .cursorrules | Mini-spec embebida en el IDE que ya usas | Si la adopción rápida pesa más que el rigor |
Mi recomendación práctica: no montes infraestructura nueva el primer día. Si ya tienes Claude Code o Cursor, empieza por ahí con una spec mínima. Si quieres el ciclo completo desde el principio, OpenSpec.
SDD en equipo: de la variabilidad individual al estándar compartido
Aquí está el ROI. Un developer solo puede apañárselas con su propio estilo. Un equipo, no.
El patrón se repite en organizaciones de todos los tamaños: cada persona usa la IA a su manera. Los juniors la usan más, los seniors desconfían, y nadie comparte criterios. Eso no es adopción. Es variabilidad. Y la variabilidad se paga en PRs impredecibles, code reviews más lentas y una sensación de «caja negra» que erosiona la confianza del equipo.
La spec compartida es lo que rompe ese patrón. Cuando todos los developers trabajan contra la misma fuente de verdad, los resultados dejan de depender de quién prompteó.
El caso de InfoJobs (Adevinta) lo ilustra bien. Su equipo —90 ingenieros, una plataforma con millones de usuarios— tenía exactamente este problema: adopción desigual, miedo a romper sistemas críticos, criterios inexistentes.
Al estandarizar el uso de IA dentro del ciclo completo (no solo la generación de código), documentar un microservicio pasó de aproximadamente una semana a un día. Los tests salían más limpios. Y la adopción se volvió transversal entre perfiles. El equipo llegó a crear MCPs conectados a Jira y GitHub para hacer cumplir estándares —cobertura de tests, formato de PRs— de forma automática.
Como lo resume Tomás Casquero, su Engineering Manager:
Errores comunes al empezar con SDD
Para que no tropieces donde tropieza todo el mundo:
- Spec ambigua. Si la spec deja una decisión abierta, la IA la cierra por ti. Y rara vez como tú querías. La ambigüedad no desaparece: se delega.
- Sobre-especificar. El extremo contrario. Si detallas la implementación línea a línea, le quitas al agente el margen para optimizar y vuelves al trabajo manual con pasos extra.
- Confundir SDD con waterfall. La spec no se congela. Evoluciona con el proyecto. Si la tratas como un documento muerto, lo será.
- No versionar las specs. Si la spec no está en git, no es fuente de verdad. Es una nota. Versiona la spec como versionas el código.
- Escribirla en solitario. Una spec que define una sola persona no es un estándar de equipo. Es una opinión con formato. El valor aparece cuando el equipo la comparte.
Hay un riesgo más, de fondo, que conviene nombrar: la sobredependencia. Si el equipo confía demasiado en la IA, puede perder capacidad de revisión crítica. La respuesta no es volver atrás. Es diseñar el proceso para que la IA ejecute y el equipo siga definiendo y validando.
Primeros pasos para empezar con Spec-Driven Development
Nada de esto sirve si se queda en lectura. Tres acciones para esta semana:
- Crea una spec mínima. Instala OpenSpec o crea un CLAUDE.md en tu repo actual. Que recoja al menos: stack, convenciones y qué está prohibido.
- Elige una feature pequeña. Escribe la spec antes del prompt. Define qué, por qué y criterios de aceptación.
- Compara. Ejecuta esa feature con spec y mídelo contra tu flujo habitual. No la velocidad de la primera versión: las veces que vuelves atrás.
Spec-Driven Development no convierte la IA en mágica. Hace lo contrario: la convierte en predecible. Donde antes había variabilidad —entre developers, entre features, entre días— ahora hay un mismo método anclando todo. No es una metodología nueva que tengas que aprender desde cero. Es lo mínimo que la IA necesita para dejar de improvisar y empezar a ejecutar.
[Contenido relacionado: Los 3 pilares del uso efectivo de la IA en desarrollo de software].
De Developer a Agentic Engineer. Máster de IA para desarrolladores de software
