¿Qué es Spec-Driven Development (SDD)?

Spec-Driven Development es una forma de trabajar con agentes de IA donde primero escribes una especificación clara de lo que quieres construir (qué, por qué, cómo se ve un resultado correcto) y después dejas que el agente genere el código a partir de esa spec. La spec se vuelve la fuente de verdad, no el prompt del momento.

¿Cuál es la diferencia entre SDD y 'vibe coding'?

Vibe coding es pedirle al agente cosas con prompts cortos basados en la intuición del momento ('hazme un login bonito'). SDD parte de un documento corto pero estructurado que define el alcance, los criterios de aceptación y las decisiones técnicas. El primero genera ciclos de re-trabajo; el segundo permite verificar el resultado contra algo concreto.

¿SDD me obliga a escribir documentos enormes antes de programar?

No. Una buena spec puede tener entre 20 y 80 líneas. La idea no es documentar todo, es forzarte a aclarar tres cosas: qué hace la feature, qué NO hace, y cómo sabrás que está terminada. Eso es suficiente para que un agente como Claude Code te entregue algo usable.

¿Cómo implemento Spec-Driven Development con Claude Code?

El flujo básico es: 1) creas una carpeta specs/ en tu proyecto, 2) escribes un archivo .md con la spec siguiendo una plantilla, 3) le pides a Claude Code que lea esa spec y genere un plan de implementación, 4) apruebas el plan y dejas que ejecute, 5) verificas el resultado contra los criterios de aceptación de la spec.

¿Para qué tipo de proyectos sirve SDD?

Para casi cualquier feature que tarde más de 30 minutos en implementarse. Si es un cambio trivial (renombrar una variable, ajustar un margen) no necesitas spec. Pero para nuevas features, refactors, integraciones o cualquier cosa que toque varios archivos, SDD reduce drásticamente el re-trabajo.

¿Necesito alguna herramienta especial para hacer SDD?

No. Solo necesitas Claude Code (o cualquier agente de coding) y archivos markdown en tu repo. Existen herramientas como GitHub Spec Kit o Kiro que automatizan partes del flujo, pero puedes empezar hoy mismo solo con una carpeta specs/ y la plantilla que comparto en este post.

Spec-Driven Development con Claude Code: deja de hacer vibe coding

Si llevas un par de meses usando Claude Code o cualquier otro agente de coding, seguramente ya te pasó esto: le pides una feature, te entrega algo "casi", la corriges con otro prompt, vuelve "casi", y al final te das cuenta de que llevas dos horas en algo que no debió tomar más de 30 minutos.

Eso es vibe coding: trabajar con la IA por intuición, prompt tras prompt, sin un norte claro. Funciona para cosas chiquitas. Para todo lo demás, hay una mejor forma de hacerlo: Spec-Driven Development (SDD).

En este post te explico qué es, por qué cambia totalmente cómo trabajas con Claude Code, y te dejo la plantilla exacta que uso yo.

Vibe Coding vs Spec-Driven Development

Antes del cómo, una imagen vale más que mil prompts:

Comparación entre Vibe Coding y Spec-Driven Development

La diferencia no es que SDD sea "más profesional" o "más serio". La diferencia es que te obliga a pensar antes de escribir, y eso le da al agente algo concreto contra qué construir y verificar.

Cuando le mandas un prompt corto a Claude Code, el agente tiene que adivinar muchísimas cosas: tu stack, tus convenciones, qué consideras "terminado", qué casos borde te importan. Cuando le pasas una spec, todo eso ya está resuelto.

El flujo de SDD en 4 pasos

Los 4 pasos del flujo de Spec-Driven Development: Spec, Plan, Implementar, Verificar

Cada paso tiene un rol distinto:

Spec — Tú escribes (con o sin ayuda de Claude) qué quieres construir
Plan — Claude propone cómo lo va a hacer, archivo por archivo
Implementar — Claude ejecuta el plan
Verificar — Tú revisas contra los criterios de aceptación de la spec

El truco está en no saltarte ninguno. Cada paso filtra errores que costarían 10x corregir más adelante.

Paso 1: Crea tu carpeta de specs

Dentro de tu proyecto, crea una carpeta:

bash

mkdir specs

Cada feature va a ser un archivo .md adentro. Por ejemplo:

code

specs/
  001-login-con-google.md
  002-export-csv-de-reportes.md
  003-rate-limit-en-api-publica.md

El número al inicio te ayuda a ordenarlas y a referenciarlas después ("revisa la spec 002").

Paso 2: La plantilla de spec

Esta es la plantilla que uso. Cópiala y úsala como punto de partida:

markdown

# [Nombre de la feature]

## Contexto
Por qué construimos esto. Qué problema resuelve.
2-4 oraciones, no más.

## Alcance
### Qué SÍ incluye
- Bullet 1
- Bullet 2

### Qué NO incluye
- Bullet 1
- Bullet 2

## Comportamiento
Describe el flujo desde el punto de vista del usuario.
"Cuando el usuario hace X, el sistema responde con Y."

## Decisiones técnicas
- Stack/librería a usar (si ya está decidido)
- Estructura de archivos esperada
- Restricciones (rendimiento, compatibilidad, etc.)

## Criterios de aceptación
- [ ] Criterio verificable 1
- [ ] Criterio verificable 2
- [ ] Criterio verificable 3

La sección clave es "Qué NO incluye". Es lo que evita que Claude se entusiasme y te agregue tres features extra que nadie pidió.

Paso 3: Pídele a Claude que genere el plan

Una vez que tienes tu spec, abre Claude Code en tu proyecto y manda este prompt:

code

Lee specs/001-login-con-google.md y genera un plan
de implementación detallado:
- Lista de archivos a crear o modificar
- Orden de ejecución
- Tests que vas a escribir
- Dudas o decisiones que necesitas que yo resuelva antes

NO escribas código todavía. Solo el plan.

Ese "NO escribas código todavía" es importantísimo. Claude tiene tendencia a saltar directo a la implementación. Tú quieres ver el plan primero para corregir el rumbo cuando todavía es barato.

Paso 4: Aprueba y deja que ejecute

Si el plan está bien, le dices:

code

El plan está bien. Procede con la implementación.
Avanza archivo por archivo y al terminar cada uno,
muéstrame qué hiciste antes de pasar al siguiente.

Si algo en el plan no te late, lo discutes ahí mismo, antes de que se escriba una sola línea de código de verdad. Esto es lo que ahorra horas.

Paso 5: Verifica contra la spec

Cuando termina, vuelve a tu spec original y abre la sección de Criterios de aceptación. Recorre uno por uno:

¿Se cumple? ✓
¿No se cumple? Le dices a Claude exactamente qué criterio falta y por qué.

Aquí es donde SDD se siente distinto. En vez de revisar "¿se ve bien?" estás revisando contra una lista que tú escribiste. La conversación con la IA se vuelve objetiva.

Un ejemplo real: spec mínima

Para que veas qué tan corta puede ser una spec útil, este es un ejemplo real (45 líneas):

markdown

# 002 — Export de reportes a CSV

## Contexto
Los usuarios piden poder bajar sus reportes mensuales para
abrirlos en Excel. Hoy solo pueden verlos en la web.

## Alcance
### Qué SÍ incluye
- Botón "Exportar CSV" en la página /reportes
- Endpoint /api/reportes/export que devuelve el archivo
- Solo exporta el reporte que está visible en pantalla

### Qué NO incluye
- Export de varios reportes a la vez
- Programar exports automáticos
- Otros formatos (Excel, PDF)

## Comportamiento
1. Usuario abre /reportes y ve un reporte
2. Hace click en "Exportar CSV"
3. Se descarga un archivo reporte-YYYY-MM.csv
4. El CSV tiene las mismas columnas que la tabla en pantalla

## Decisiones técnicas
- No usar librerías externas, generar el CSV a mano
- El endpoint devuelve Content-Type: text/csv
- Encoding UTF-8 con BOM para que Excel lo abra bien

## Criterios de aceptación
- [ ] El botón aparece solo si hay datos en la tabla
- [ ] El nombre del archivo incluye año y mes
- [ ] Excel lo abre con acentos correctos
- [ ] Si la tabla está vacía, el botón está deshabilitado
- [ ] El endpoint requiere autenticación

Con esto, Claude Code tiene todo lo que necesita para entregarte algo verificable. Sin spec, te hubiera entregado un export "genérico" con tres librerías nuevas y la mitad de los criterios sin cumplir.

Cuándo NO usar SDD

No todo necesita spec. Si la tarea es:

Renombrar una variable
Ajustar un margen o un color
Agregar un log
Un cambio que toca un solo archivo y un solo concepto

Vibe coding está bien. SDD es para todo lo demás: features nuevas, refactors, integraciones, cualquier cosa que toque varios archivos o que tarde más de 30 minutos.

Lo que cambia en tu día a día

Después de un par de semanas trabajando así, vas a notar tres cosas:

Menos re-trabajo. Claude entrega algo más cercano a lo que querías a la primera.
Mejores conversaciones con el equipo. Las specs sirven también para discutir scope con tu PM o tu cliente, antes de programar nada.
Un historial útil. La carpeta specs/ se vuelve una memoria viva del proyecto. Mejor que cualquier ticket de Jira.

Spec-Driven Development no es una metodología pesada ni una certificación. Es solo el hábito de escribir 30 líneas antes de pedirle 300 a la IA. Y con agentes como Claude Code, ese pequeño cambio es la diferencia entre llegar a algo usable en 20 minutos o pelearte con prompts toda la tarde.

Si te sirvió este post, sígueme en mis redes para más contenido sobre cómo trabajar mejor con Claude Code y otros agentes de IA.