Spec-Driven Development (SDD) con IA: guía práctica en 2026

Esta no es otra definición académica de SDD. Es la guía que me habría gustado tener cuando empecé a trabajar con IA en desarrollo de producto y me di cuenta de algo bastante incómodo: prompting sin specs no escala. Aquí explico cómo aplicar Spec-Driven Development con IA de forma práctica, sin burocracia y con criterios claros que luego sí se pueden llevar a código.

Qué es Spec-Driven Development (SDD) y por qué vuelve ahora con la IA

Spec-Driven Development (SDD) es una idea sencilla que durante años fue poco práctica: definir con precisión qué quieres construir antes de ponerte a construirlo. La especificación (la spec) no es un trámite, es el centro de todo.

Durante mucho tiempo esto sonaba bien en la teoría, pero en la práctica fallaba casi siempre. Los cambios de alcance de última hora, el coste de mantener las specs actualizadas y las prisas del día a día hacían que el código terminara siendo la única verdad. Con la IA, por primera vez, esto puede cambiar de forma realista.

Cuando trabajas con modelos de lenguaje, la calidad del resultado depende directamente de la claridad del contexto que les das. No del modelo, ni del prompt mágico, sino del contexto previo que define qué es correcto y qué no. Y una buena spec es, básicamente, el mejor contexto posible. En mi caso, el momento “clic” fue darme cuenta de que una spec clara reducía más errores que cualquier prompt ingenioso.

¿Quién no ha probado alguna vez, aunque sea por jugar, a lanzar prompts a un agente del estilo: “Actualiza este proyecto a DDD” o “Migra a la versión X”? El resultado suele ser el mismo: consumo absurdo de tokens y salidas más que cuestionables, porque el agente no tiene un marco claro contra el que decidir.

SDD no vuelve por nostalgia ni por moda. Vuelve porque la IA necesita instrucciones estables, no conversaciones improvisadas.

Si ya tienes claro qué es SDD, puedes ir directo a cómo escribir specs efectivas, herramientas para SDD con IA o errores comunes al aplicar Spec-Driven Development. El resto del artículo construye esa base.

El flujo real de Spec-Driven Development con IA (de la idea al código)

En la práctica, SDD no es un proceso rígido ni burocrático. Tampoco pretende sustituir otras metodologías como DDD, TDD o BDD. Yo lo entiendo más bien como un flujo mental que se superpone a la forma en la que ya trabajamos y que cobra especial sentido cuando entran agentes de IA en la ecuación.

De la idea al problema bien formulado

Todo empieza con una idea vaga. Eso es normal. El error habitual es pasar de ahí directamente al código o al prompt.

Antes de escribir una sola línea de spec, me obligo a responder algo muy simple: ¿qué problema concreto estamos resolviendo y para quién? Si no puedo explicarlo en pocas frases, todavía no lo entiendo. Y si no lo entiendo yo, es imposible que un agente lo ejecute bien.

Este paso, aunque parece trivial, suele ser donde más valor se genera. Forzarte a formular el problema elimina ambigüedades antes de que se conviertan en deuda técnica.

La spec como contrato (no como documento bonito)

Aquí es donde SDD se separa claramente de “escribir documentación”. La spec no intenta impresionar a nadie. Su único objetivo es evitar malentendidos.

Una buena spec deja claras tres cosas fundamentales:

• Qué hace el sistema
• Qué no hace
• Cómo sabemos si está bien hecho

Cuando empecé a trabajar así, muchas discusiones desaparecieron. No porque todo el mundo estuviera de acuerdo, sino porque la spec obligaba a tomar decisiones antes de escribir código.

De la spec a tareas accionables

Una spec bien escrita se puede trocear casi sola en tareas. En este punto la IA ayuda mucho: saca a la luz casos borde, dependencias y huecos lógicos que a menudo pasamos por alto.

Aquí hay una advertencia importante: si la spec es ambigua, la IA no lo va a arreglar. Lo va a amplificar.

Este proceso tampoco tiene por qué ser completamente manual. En mi caso, suelo trabajar la spec dentro de una conversación con ChatGPT en modo canvas, iterando sección por sección hasta que el texto es lo suficientemente claro como para que otro humano —o un agente— pueda ejecutarlo sin hacer suposiciones. Curiosamente, por cómo funcionan los modelos, este proceso suele revelar escenarios extremos o restricciones que no habíamos considerado al principio.

Código asistido por IA (con límites claros)

Con una spec sólida, la IA deja de “inventar” y pasa a ejecutar. Genera código, tests y estructuras con mucha más coherencia y menos ruido.

Algo que aprendí rápido es que, cuando el resultado no me gusta, casi nunca el problema es el modelo. El problema suele estar en la spec. Revisarla y ajustarla casi siempre da mejores resultados que cambiar de herramienta o de prompt.

Validación contra la spec, no contra opiniones

El último paso no es preguntar “¿funciona?”, sino “¿cumple lo que prometimos?”. La spec se convierte en el criterio de verdad.

Si algo falla, no se parchea directamente el código. Se revisa primero la spec. En más ocasiones de las que parece, el fallo estaba ahí.

Qué hace que una spec sea realmente buena (criterios prácticos)

No todas las specs sirven para trabajar bien con IA. Algunas parecen completas, bien estructuradas e incluso “profesionales”, pero en cuanto intentas usarlas con un agente empiezan a hacer agua.

Con el tiempo he llegado a una conclusión bastante clara: una buena spec no es la que explica más cosas, sino la que reduce al mínimo lo que hay que interpretar.

Contexto que realmente acota, evita las florituras

El contexto no está para contar la historia del proyecto, sino para acotar decisiones. Quién va a usar esto, en qué situación y con qué limitaciones reales.

Cuando una spec dice “usuario final” o “uso general”, en realidad no está diciendo nada. En cambio, cuando defines un contexto concreto, la IA —y cualquier persona del equipo— deja de imaginar escenarios que no existen.

Una spec debe poder fallar

Si algo que estás definiendo no se puede falsear, no lo has pensado suficiente.

Si al terminar el desarrollo no puedes definir con claridad si se ha cumplido o no el objetivo, entonces no era un buen objetivo. Este punto que parece una tontería filosófica es especialmente importante cuando trabajamos con agentes de IA, estos, tienden a completar las cosas que no están claramente definidas y con ello “alucinar” añadiendo flujos que no estaban previstos o comportamientos inesperados.

El valor real de las exclusiones

Aquí es donde muchas specs flojean. Decir lo que no entra en alcance suele parecer innecesario… hasta que no se hace.

En mi experiencia, definir exclusiones reduce más errores que añadir funcionalidades. Reduce el contexto, evita sustos con cambios en el proyecto que no esperabas y te asegura que una spec no del todo clara no modifique normas de negocio que no deberían tocarse. Recuerda que el Dominio no se adapta (y cuando alguien intenta que lo haga, suelen pasar cosas interesantes…).

Evita redundancias

Por suerte, los estándares están llegando a nuestro día a día a la hora de trabajar con agentes. Si ves que tienes que incluir en todas tus specs cosas como “genera tests unitarios de esta o aquella manera”, lo más sensato es optimizar el trabajo y desplazar ese tipo de instrucciones a ficheros como Agents.md o guidelines.md.

De esta forma, el agente sabe cómo tiene que comportarse desde el principio, pero tú no tienes que repetir siempre los mismos bloques de texto. La spec se mantiene centrada en el problema y el comportamiento, que es donde realmente aporta valor.

Cómo encajan los roles en un equipo que trabaja con Spec-Driven Development

Una de las trampas más habituales al hablar de SDD es describirlo como “más documentación”. En un equipo real, el cambio no está en escribir más, sino en mover el punto donde se toman las decisiones importantes.

Cuando la spec es el centro, muchas fricciones clásicas desaparecen o, al menos, aparecen antes, cuando todavía son baratas de resolver.

PM / Producto: la spec como herramienta de alineación (no como entregable)

Producto no escribe una spec para “pasarle el marrón” a desarrollo. La spec es su herramienta principal para alinear a todo el equipo alrededor de tres cosas muy concretas:

• qué problema se está resolviendo,
• qué entra y qué queda explícitamente fuera,
• y qué significa exactamente que algo esté bien hecho.

En equipos que trabajan con IA esto se nota muchísimo. Una spec poco acotada se convierte rápidamente en prompts interminables, decisiones implícitas y cambios de dirección a mitad del camino. Una spec clara, en cambio, reduce ruido y hace visibles las decisiones desde el principio.

Dev: menos interpretación, más diseño consciente

El trabajo del developer deja de ser “adivinar qué quería decir producto”. Su rol pasa a tensionar la spec con preguntas incómodas, pero necesarias:

• ¿qué caso borde estás asumiendo sin decirlo?
• ¿qué dependencia implícita hay aquí?
• ¿qué restricción técnica hace que esto sea inviable, frágil o caro?

La clave es que estas conversaciones ocurren antes de que exista código. Con IA, este punto es crítico: cuanto más tarde aparece una ambigüedad, más caro es corregirla.

QA: convertir ambigüedad en verificaciones

QA deja de llegar al final para “romper cosas”. En SDD entra antes para transformar lenguaje impreciso en criterios comprobables:

• escenarios críticos,
• casos negativos (lo que NO debe pasar),
• y pruebas que validan comportamiento, no implementación.

Una regla práctica que suelo usar es esta: si una spec no se puede testear, probablemente no está lista para implementarse.

La IA: ejecuta rápido, interpreta mal

Yo trato a la IA como un miembro del equipo con dos características muy claras:

• es extremadamente rápida ejecutando, y
• es peligrosamente buena rellenando huecos.

La spec existe precisamente para reducir ese espacio de interpretación. No para limitar a la IA, sino para evitar que tome decisiones que nunca deberían haber sido suyas.

Checklist práctico antes de dar una spec por “lista”

Esta es, probablemente, la parte menos glamurosa del proceso… y también una de las más útiles. No es un checklist para cumplir por cumplir, sino una última pasada rápida para detectar ambigüedades antes de que se conviertan en trabajo extra.

Este es el checklist que uso cuando quiero evitar sorpresas (humanas o de IA):

• ¿El problema se entiende sin contexto adicional?
  Si alguien que no estuvo en la conversación original no lo entiende, un agente tampoco.
• ¿El objetivo puede fallar?
  ¿Podrías decir con claridad “esto no cumple la spec”? Si no, hay ambigüedad.
• ¿Está explícito qué NO entra en alcance?
  Si no hay exclusiones claras, alguien (humano o IA) las inventará.
• ¿Los criterios de aceptación son verificables y binarios?
  Nada de “debería”, “idealmente” o “más o menos”. O pasa, o no pasa.
• ¿Hay ejemplos suficientes para los flujos importantes?
  Al menos uno por flujo crítico. Los ejemplos reducen interpretación más que cualquier definición.
• ¿La spec describe comportamiento, no implementación?
  Si estás decidiendo arquitectura aquí, probablemente estás mezclando niveles.
• ¿Un agente podría ejecutar esta spec sin hacerte preguntas?
  Esta es la prueba final. Si la respuesta es no, la spec aún no está madura.

Regla práctica: si alguna casilla queda en duda, no pasa nada. Volver a la spec ahora es infinitamente más barato que hacerlo cuando ya hay código, tests o prompts en producción.

Si alguna respuesta es “no”, no pasa nada: vuelves a la spec. Es infinitamente más barato ajustar aquí que hacerlo cuando ya hay código, tests o prompts montados.

Plantilla simple de spec (la que uso de verdad)

La plantilla importa menos que la disciplina de usarla siempre. Esta es la que suelo utilizar porque me obliga a pensar en exclusiones y criterios de aceptación desde el principio:

Título

Problema que se quiere resolver

Contexto de uso

Objetivo

Alcance
- Incluye
- No incluye

Comportamiento esperado
- Flujo principal
- Flujos alternativos / edge cases

Criterios de aceptación
- Dado / Cuando / Entonces

Restricciones
- Técnicas / negocio / seguridad

Notas
- Decisiones abiertas / dudas

Si te obligas a rellenar No incluye y al menos 2–3 criterios de aceptación verificables, ya vas por delante del 90% de las specs que veo por ahí.

Ejemplo real: spec para el registro de un usuario (backend)

Para evitar ambigüedades y centrarnos en lo importante, este ejemplo está deliberadamente enfocado en el proceso backend, no en la UI. La idea es mostrar cómo una spec clara permite implementar la lógica sin discutir detalles de frontend.

Título
Registro de usuario (backend)

Problema que se quiere resolver
Permitir que un sistema cree cuentas de usuario de forma segura y consistente, garantizando la integridad de los datos y evitando registros duplicados.

Contexto de uso
Servicio backend que recibe peticiones de registro desde distintos clientes (web, móvil, API externa). El backend es la única fuente de verdad para la creación de usuarios.

Objetivo
Dado un email y una contraseña válidos, el sistema crea un nuevo usuario persistido y deja la cuenta en estado pendiente de verificación.

Alcance
- Incluye:
  - Endpoint de registro de usuario
  - Validación de email único
  - Validación de contraseña según política definida
  - Persistencia del usuario
  - Emisión de evento de "usuario registrado"
- No incluye:
  - Renderizado de formularios
  - Gestión de sesión o login
  - Envío del email de verificación
  - Recuperación o cambio de contraseña

Comportamiento esperado
- El sistema recibe una solicitud de registro con email y contraseña
- Verifica que el email no exista previamente
- Valida la contraseña según las reglas establecidas
- Almacena la contraseña de forma segura (hash)
- Crea el usuario con estado "pending_verification"
- Publica un evento de dominio indicando que el usuario ha sido registrado

Criterios de aceptación
- Dado un email no registrado y una contraseña válida, cuando se procesa la solicitud, entonces se crea un nuevo usuario en estado "pending_verification"
- Dado un email ya existente, cuando se procesa la solicitud, entonces no se crea ningún usuario y se devuelve un error de conflicto
- Dada una contraseña que no cumple la política, cuando se procesa la solicitud, entonces no se crea el usuario y se devuelve un error de validación

Restricciones
- El hash de la contraseña debe cumplir los estándares de seguridad del sistema
- El endpoint debe ser idempotente frente a reintentos
- El sistema debe cumplir RGPD en el tratamiento del email

Notas
- El envío del email de verificación se gestiona en otro servicio
- El formato exacto del evento se define en una spec separada

Este ejemplo muestra cómo una spec centrada en backend reduce discusiones innecesarias y permite a humanos y agentes implementar la lógica sin tener que inferir responsabilidades que no les corresponden.