SDD: Spec Driven Development

Una metodología de desarrollo es un acuerdo sobre cómo trabajar. No hace que programes mejor por sí sola: sirve para no improvisar, para que las decisiones importantes se tomen siempre de forma coherente y un humano (y un agente) entienda que se está construyendo.

Si nunca has utilizado una metodología, no pasa nada. Hay un momento en el que debes comenzar a hacerlo para poner orden, especialmente cuando usas un agente de IA: Un agente es rápido, incansable y literal. Hace exactamente lo que le pides y, justo donde terminan tus instrucciones, empieza a inventar. Si escribes un prompt de 3 líneas, rellenará todos los huecos con lo que le parezca más probable. A veces acierta, a veces no. Y cuando no acierta, no es que se equivoque: es que programó algo que no querías.

SDD (Spec Driven Development, o «desarrollo guiado por especificaciones») es una forma de solucionar esto. No se trata de una metodología nueva, sino que se fortalece en tiempos de IA. Su base es escribir lo qué quieres antes de construirlo, pero tiene un matiz nuevo: la especificación (spec) es lo que el agente lee y contra lo que se verifica el código.

En SDD la spec pasa a ser la fuente de la verdad (source of truth). El código se modifica en base a una spec, y no al revés.

(Sin SDD) prompt vago → el agente adivina → ¿era esto lo que quería?  🤷
(Con SDD) spec → plan → tareas → código → verificar contra la spec ✅

💡 SDD no es escribir más, es escribir ANTES. Esta guía es para alguien que programa y no ha usado metodologías. No necesitas saber TDD, BDD u otras metodologías: lo que haga falta lo iremos explicando por el camino.

Existen multitud de metodologías de trabajo. Echemos un vistazo a esta tabla comparativa para saber donde nos encontramos:

Vamos con cada una:

• 1️⃣ TDD (Test Driven Development): escribes primero un test que falla, luego el código mínimo para que pase y por último refactorizas (rojo → verde → refactor).

• 2️⃣ BDD (Behaviour Driven Development): igual que TDD, pero describe el comportamiento en un lenguaje que entienden negocio y máquina (GIVEN ... WHEN ... THEN).

• 3️⃣ SDD: En lugar de una función o un escenario, especifica una feature completa —qué, por qué, casos límite, criterios— y la usa como contexto para el agente.

• 4️⃣ Waterfall: Escribe la spec completa antes, pero la congela tras aprobarla y separa por meses la especificación de la implementación.

• 5️⃣ Vibe coding: Lanzas prompts al agente a ver qué sale. Te guías sólo por la intuición. Ideal para prototipos desechables. Muy peligroso para cualquier cosa que vayas a mantener.

⚠️ Ten en cuenta que muchas de estas metodologías no son reemplazos, sino complementarias. En tu caso puede interesarte tanto combinarlas como seguir alguna específica.

SDD tiene 4 puntos clave que conviene aclarar:

• 1️⃣ La spec es un contrato
• 2️⃣ Qué != Cómo
• 3️⃣ Niveles de rigor
• 4️⃣ Criterios verificables

La spec vive en el repositorio y es versionada con Git como cualquier otro fichero. Por lo tanto, es algo que se revisa, se discute y se modifica. Es diferente a las reglas del proyecto (AGENTS.md):

• Las reglas se aplican a todo y se cargan siempre.
• La spec es de una feature y tiene un alcance temporal.

Lo más importante en SDD: La spec describe qué quieres y por qué, nunca cómo lo vas a implementar:

• ❌ «Añadir una columna locked_until a la tabla users.»
• ✅ «Tras varios intentos fallidos, la cuenta debe quedar bloqueada temporalmente.»

En el momento en que tu spec dice «usa un Set para eliminar duplicados», ya no estás especificando: estás implementando. El cómo pertenece al plan técnico, que sí puedes tirar y rehacer cuando cambies de idea.

💡 Separar qué de cómo permite al agente proponer la mejor implementación, en lugar de atarte a una decisión que tomaste quizás sin evaluarlo correctamente.

No todo el mundo necesita el mismo rigor al utilizar SDD. Hay diferentes niveles a los que te puedes adaptar. Tres de los más populares serían los siguientes:

🧭 Si tienes dudas, empiezar por spec-first. Si el proyecto es a largo plazo, muévete a spec-anchored. El spec-as-source déjalo sólo para experimentos.

Una spec puede estar mal. La spec «La búsqueda debe ser rápida» es algo que no se puede comprobar, pero «Una búsqueda sobre 10.000 registros responde en menos de 200ms», sí.

Para ello, podemos usar uno de estos dos formatos:

• 1️⃣ Given / When / Then (heredado de BDD):

GIVEN un usuario con 5 intentos fallidos
WHEN introduce de nuevo la contraseña correcta
THEN la cuenta sigue bloqueada y ve el tiempo restante

• 2️⃣ EARS: Easy Approach to Requirements Syntax (heredado de Kiro):

WHEN el usuario falla 5 veces seguidas, THE SYSTEM SHALL bloqueará la cuenta 15 minutos.

No es obligatorio usar ninguno de los dos y existen otros, pero nos sirven de ejemplos que obligan a escribir criterios que un test podría comprobar.

Para entender correctamente como funciona SDD se suele dividir en fases. El nombre cambia según quién te lo cuente, pero en esencia el ciclo siempre es el mismo:

     ↓
Constitución  (una sola vez)
     ↓
Especificar → Aclarar → Planificar → Tareas → Implementar → Verificar ─┐
                 ↑                                                     │
                 └──────────  (si algo falla, se corrige la spec)  ────┘

• 1️⃣ Constitución: las reglas que se aplican a todo el proyecto (AGENTS.md)
• 2️⃣ Especificar: Trabajar en la spec: qué y por qué, sin el cómo.
• 3️⃣ Aclarar: el agente revisa la spec y encuentra sus huecos. El humano revisa.
• 4️⃣ Planificar: cómo se hará (arquitectura, modelos, tecnología, API, migraciones...).
• 5️⃣ Tareas: dividir el plan en piezas pequeñas, ordenadas y verificables.
• 6️⃣ Implementar: el agente construye tarea a tarea, idealmente con tests o TDD.
• 7️⃣ Verificar: se revisa el código contra la spec, no solo contra los tests.

📌 La fase que casi todo el mundo se salta es aclarar (merece la pena dedicarle tiempo). Si encuentras algo raro en el plan, arregla la spec, no el plan. Normalmente significa que la spec dejó algo abierto. Arreglando la spec, arreglas todas las iteraciones siguientes.

SDD no inventa formatos. Todo son ficheros Markdown versionados con Git dentro de tu repositorio. Se define un fichero AGENTS.md por proyecto, y luego, un spec.md, plan.md y tasks.md por cada feature:

• 1️⃣ AGENTS.md: Se define en la fase de Constitución
• 2️⃣ spec.md: Se define en la fase de Especificación, se puede modificar en Aclarar
• 3️⃣ plan.md: Se define en la fase de Planificación
• 4️⃣ tasks.md: Se define en la fase de Tareas

Una estructura de carpetas podría ser la siguiente:

mi-proyecto/
├── AGENTS.md                       # Constitución (se carga siempre)
├── .opencode/
│   └── skills/                     # Skills (bajo demanda, agente decide)
│       ├── entorno-tests/SKILL.md
│       └── cliente-http/SKILL.md
├── specs/                          # SDD docs, una por feature
│   ├── 001-bloqueo-login/
│   │   ├── spec.md                 # Qué / por qué + criterios
│   │   ├── plan.md                 # Cómo (datos técnicos)
│   │   └── tasks.md                # Subtareas verificables
│   ├── 002-busqueda-filtros/
│   │   ├── spec.md
│   │   ├── plan.md
│   │   └── tasks.md
│   └── 003-exportar-csv/
│       └── ...
├── src/                            # El código (Implementación)
└── tests/                          # Tests para verificar

Veamos un ejemplo de los ficheros AGENTS.md y los ficheros de la primera feature:

En OpenCode puedes generar con /init un AGENTS.md y luego revisarlo. Ahí van las reglas prioritarias que valen para cualquier tarea:

## Principios del proyecto

- TypeScript estricto, sin `any`.
- Toda funcionalidad nueva lleva tests (Vitest).
- No añadir dependencias sin justificar.
- No cambiar la API pública sin actualizar la spec correspondiente.
- Los comandos habituales son `pnpm test` y `pnpm lint`. No usar `npm`.

Recuerda que si hay instrucciones que no vas a usar siempre, es interesante meterlas en skills. En la guía Skills e instrucciones te explico más sobre el tema.

El fichero spec.md es el documento central. Describe el problema, los criterios y los límites, sin detalles de implementación:

# Spec: Bloqueo de cuenta tras intentos fallidos

## Por qué

Hoy se pueden probar contraseñas sin límite. Queremos frenar los ataques de
fuerza bruta sin castigar al usuario legítimo que se equivoca.

## Alcance

- Bloquear temporalmente la cuenta tras intentos fallidos consecutivos.
- Aplica solo al login con contraseña (no a login social).

## Criterios de aceptación

- [ ] AC1: Si un usuario acumula 5 intentos fallidos seguidos,
      se le bloquea la cuenta durante 15 minutos.
- [ ] AC2: Si está bloqueada, incluso contraseña correcta se rechaza,
      indicando los minutos restantes.
- [ ] AC3: Un intento correcto reinicia el contador de fallos.
- [ ] AC4: Al agotarse el bloqueo, el contador vuelve a cero.
- [ ] AC5: El bloqueo es por cuenta, no por IP.

## Fuera de alcance

- Notificar al usuario por email.
- Bloqueo permanente o desbloqueo manual.
- Cambios en la pantalla de login más allá del mensaje de bloqueo.

## Preguntas abiertas

- ¿El bloqueo debe contar por cuenta, por IP o por ambas?
- ¿El usuario recibe algún aviso mientras está bloqueado?
- ¿Se aplica también al inicio de sesión con proveedores externos?

Ahora bajamos al detalle técnico. El plan se deriva de la spec y se puede rehacer sin tocarla:

# Plan: Bloqueo de cuenta tras intentos fallidos

## Modelo de datos

- Añadir a `users` las columnas:
  - `failed_attempts` (int)
  - `locked_until` (timestamp, nullable)
- Migración reversible.

## Lógica

- En `auth.login()`, comprobar `locked_until` antes de validar contraseña.
- Tras un fallo, incrementar `failed_attempts` (de forma atómica).
- Al llegar a 5, fijar `locked_until = now + 15min`.
- Al acertar, resetear.

## Interfaz

- El error de bloqueo responde `429` con la cabecera `Retry-After`.

## Riesgos

- Relojes desincronizados: usar siempre el tiempo del servidor.
- Condiciones de carrera al incrementar el contador.

## Descartado

- Guardar el estado en Redis: innecesario para el volumen actual.

Por último, el plan se parte en tareas pequeñas, ordenadas y verificables. Cada una debe poder revisarse por separado y decir con qué criterio se comprueba:

# Tareas: Bloqueo de cuenta tras intentos fallidos

- [ ] T1 · Modelo y migración (`failed_attempts`, `locked_until`).
      Verde cuando la migración sube y baja sin errores.
- [ ] T2 · Lógica de conteo y bloqueo en `auth.login()`.
      Verde cuando pasan los criterios `AC1`, `AC3` y `AC5` en unitarios.
- [ ] T3 · Respuesta de error con `Retry-After` y minutos restantes.
      Verde cuando pasa el `AC2` en un test de integración.
- [ ] T4 · Reseteo del bloqueo al expirar.
      Verde cuando pasa el `AC4` con el reloj simulado.

Ahora que ya sabemos la estructura y contenido de los documentos SDD, veamos el ciclo completo trabajando con OpenCode.

• 1️⃣ Constitución: Arranca OpenCode en tu proyecto y ejecuta /init para generar el AGENTS.md. Revísalo y ajustalo. Si consideras que algo no es absolutamente necesario, pásalo a skills.

• 2️⃣ Especificar: Pídele que escriba la spec, pero sin código:

Crea specs/001-bloqueo-login/spec.md para esta feature: bloquear la cuenta
durante 15 minutos tras 5 intentos fallidos de login. Escribe solo el qué y
el por qué, con criterios de aceptación verificables y una sección de fuera
de alcance. No escribas implementación.

• 3️⃣ Aclarar: Intenta no saltarte este paso. El agente puede preguntar las dudas como método de refinamiento. También se te ocurrirán dudas y aclaraciones:

Lee specs/001-bloqueo-login/spec.md y hazme todas las preguntas necesarias
para cerrar las dudas antes de planificar. No propongas soluciones todavía.

• 4️⃣ Planificar: Ahora, fase de planificación, luego, revisa el plan y corrige la spec si algo no te convence:

Con la spec cerrada, crea specs/001-bloqueo-login/plan.md. Propón la
arquitectura, el modelo de datos, la interfaz y los pasos de migración.
No escribas todavía el código de producción.

• 5️⃣ Tareas: Divide el plan en piezas revisables:

Divide el plan en specs/001-bloqueo-login/tasks.md en tareas pequeñas,
ordenadas y verificables. Cada tarea debe indicar con qué criterio de la
spec se comprueba.

• 6️⃣ Implementar: Ahora se trata de implementar el código que cumpla las spec:

Implementa la tarea T1. Escribe primero el test que falla y luego el código
mínimo para pasarlo. No toques las tareas siguientes.

• 7️⃣ Verificar: Recorre los criterios uno a uno, no el diff:

Lee la spec y tasks.md. Recorre los criterios de aceptación uno a uno y
dime cuáles se cumplen y cuáles no, con la ruta y el test que lo demuestra.
No cambies nada sin avisarme.

Si repites este ciclo a menudo, puedes crear comandos personalizados (/specify, /plan, /tasks) que automaticen cada paso. En la Guía de OpenCode tienes cómo se crean.

📌 Todo lo anterior se puede hacer a mano con Markdown y/o con un agente, de hecho deberías empezar así. Si necesitas algo más guiado, puedes probar GitHub Spec Kit o OpenSpec.

• ❌ Specs sin mantener: Decide desde el inicio si vas spec-first o spec-anchored.
• ❌ Waterfall en Markdown: Vigila features demasiado grandes. Ajústala al tamaño del cambio.
• ❌ Specs sin el cómo: Si tu spec habla de tablas, librerías o patrones, ya no es una spec.
• ❌ Criterios no verificables: «Debería ser intuitivo» no sirve; evita criterios no verificables.
• ❌ Investiga lo que no sepas: En aclarar, debería responder el humano las preguntas del agente.
• ❌ No revisar: Siguen haciendo falta tests y mecanismos de revisión humana.