Spec-Driven Development: crea tu primera spec y mira la diferencia

Imagina que tienes una API de tareas. Nada complicado — un GET /tasks que las lista, un POST /tasks que las crea. Alguien te pide algo nuevo: un endpoint que exporte esas tareas a CSV.

Pídeselo a tu agente directo, como siempre: "agrega un endpoint para exportar tareas a CSV". Va a funcionar. Va a generar código, un archivo nuevo, tal vez hasta tests. Ahora ciérralo y ábrelo otra vez en tres semanas.

¿Por qué exporta también el campo internal_notes? ¿Por qué eligió comas y no punto y coma? ¿Qué pasa si una tarea no tiene fecha? No lo sabes, porque nunca lo decidiste tú — lo decidió el agente, en el momento, sin que nadie se lo pidiera. Y en tres semanas, ni tú te acuerdas de haberlo permitido.

Eso es lo que vamos a arreglar hoy. No con más cuidado al escribir el prompt — con un archivo.

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

Spec-Driven Development es una forma de trabajar con agentes de IA en la que escribes primero una especificación — qué debe hacer el código, por qué, y qué no debe hacer — y recién después dejas que el agente lo implemente. La spec, no el código, es la fuente de verdad: cuando algo cambia, editas la spec primero y el código se regenera a partir de ahí.

No es la documentación de siempre, la que se escribe una vez y nadie vuelve a abrir. Aquí el agente la lee cada vez que trabaja en el proyecto, así que se mantiene viva por necesidad, no por disciplina de equipo.

Vamos a construir una para que lo sientas, no para que lo memorices.

Paso 1: escribe la spec antes que el código

Crea una carpeta specs/ en tu proyecto y adentro un archivo export-csv.md:

# Spec: Exportar tareas a CSV

## Qué y por qué
Los usuarios necesitan sacar sus tareas del sistema para abrirlas en Excel
o Sheets. Hoy no hay forma de hacerlo sin copiar y pegar manualmente.

## Criterios de aceptación
- GET /tasks/export devuelve un archivo CSV descargable.
- Columnas: id, title, status, due_date. En ese orden.
- Separador: coma. Encoding: UTF-8.
- Si una tarea no tiene due_date, la celda queda vacía (no "null", no "N/A").
- Respeta los mismos filtros que GET /tasks (?status=pending, etc.)

## Fuera de alcance
- No exporta campos internos (internal_notes, created_by).
- No soporta otros formatos (Excel, JSON) en esta versión.
- No es una exportación programada — solo bajo demanda.

Nota lo que NO hiciste: no dijiste qué librería usar, ni en qué archivo va el código, ni cómo se llama la función. Eso viene después. Aquí solo decidiste el qué, el por qué, y — esto es lo que la mayoría se salta — el qué NO. La sección "Fuera de alcance" es la que evita que tu agente decida por su cuenta exportar internal_notes "porque parecía útil".

Paso 2: ahora sí, el plan técnico

Con la spec ya escrita, pídele a tu agente: "lee specs/export-csv.md y arma un plan técnico". No le pediste código todavía — le pediste el cómo.

# Plan: Exportar tareas a CSV

- Librería: csv-stringify (ya está en package.json, no agregamos dependencias)
- Archivo nuevo: src/routes/tasks/export.ts
- Reutiliza el mismo query builder que GET /tasks para respetar filtros
- Header de respuesta: Content-Type: text/csv, Content-Disposition: attachment

¿Ves la diferencia con pedir "agrega un endpoint" directo? Ahora el agente no está inventando la arquitectura sobre la marcha — está siguiendo una decisión que tú ya tomaste y que quedó escrita. Si mañana otro dev — o tú mismo, dormido — necesita tocar este endpoint, no tiene que leer el código para entender el porqué. Lo lee en el plan.

Paso 3: tareas atómicas, no una tarea gigante

Del plan salen tareas chicas, cada una comprobable por separado:

# Tasks: Exportar tareas a CSV

- [ ] Crear route GET /tasks/export
- [ ] Reutilizar filtros existentes de GET /tasks
- [ ] Formatear filas: due_date vacío si es null
- [ ] Test: exportación respeta filtro ?status=pending
- [ ] Test: tarea sin due_date exporta celda vacía

Fíjate que cada línea es algo que puedes revisar en 30 segundos con un vistazo al diff. Eso es lo que lo vamos a llamar una tarea atómica — no "construir la exportación", sino un paso tan chico que si el agente se equivoca, lo ves de inmediato, no tres pantallas después.

Paso 4: recién ahora, que implemente

"Implementa specs/export-csv.md siguiendo el plan y las tareas." Y ahora sí, deja que corra.

Revisa el resultado contra las tres cosas que escribiste — no contra si "se ve bien". ¿Exportó internal_notes? No debería, lo pusiste en fuera de alcance. ¿Respetó los filtros? Está en criterios de aceptación, revísalo.

La prueba real: cambia un requisito

Aquí es donde se siente la diferencia. Dos semanas después, alguien pide: "el CSV también necesita la columna priority".

Sin spec, volverías a explicarle todo al agente desde cero — o peor, editarías el código directo y ya nadie sabría por qué el CSV tiene esa columna. Con spec, abres export-csv.md, agregas una línea en Criterios de aceptación, y le dices "implementa el cambio". El plan y las tareas se actualizan solos, o los ajustas tú en dos minutos. El cambio real fue una línea. El código que se regeneró fue mucho más — pero la intención quedó controlada en un solo lugar.

Eso es Spec-Driven Development: la spec, no el código, es la fuente de verdad. Cuando algo cambia, cambias la spec primero.

Lo mismo, pero en OpenCode

Si trabajas en OpenCode, el framework equivalente es OpenSpec. La diferencia de fondo no está en la sintaxis — está en que OpenSpec fuerza tres fases: propuesta, aplicación y archivo. No puedes "implementar" sin que exista antes una propuesta aprobada. Es la misma disciplina de Claude Code, pero con el candado puesto por la herramienta, no por tu memoria.

Cuándo vale la pena — y cuándo es solo fricción

Ya lo construiste una vez, así que esto no es teoría abstracta: es lo que acabas de vivir.

Vale la pena cuando:

• El proyecto va a vivir semanas o meses, no horas.
• Otra persona (o tú en tres semanas) va a tener que entender el porqué, no solo el qué.
• La feature toca varios archivos o decisiones de arquitectura — no un cambio de una línea.
• Trabajas en equipo y necesitas que el agente decida lo mismo sin importar quién escribió el prompt.

Es solo fricción cuando:

• Es un prototipo que vas a tirar mañana.
• Es un fix de una línea — escribir una spec para eso es más lento que el bug.
• Todavía no sabes qué estás construyendo — estás explorando, no implementando. La spec prematura te encierra en una decisión que aún no deberías tomar.

La regla que te queda después de hacerlo una vez: si el costo de que el agente entienda mal tu intención es mayor que el costo de escribir tres párrafos, escribe la spec. Si no, no la escribas — y sigue con el flujo normal de siempre.