Spec-Driven Development: escribir la especificación antes que el código

Spec-Driven Development (SDD) invierte el orden en el que muchos equipos trabajan: en vez de escribir código y documentar después (si es que se documenta), primero se escribe una especificación clara y revisable de qué hay que construir, y recién ahí se pasa a la implementación. No es una idea nueva, pero se volvió mucho más relevante ahora que buena parte del código lo escriben agentes de IA: un agente sin una spec clara simplemente adivina el requerimiento, y adivina mal más seguido de lo que gustaría.

¿Qué entra en una spec?

Una buena especificación suele responder, en pocas líneas cada una:

• Contexto: por qué se necesita esto y qué problema resuelve.
• Alcance: qué queda adentro y qué queda explícitamente afuera.
• Comportamiento esperado: casos de uso concretos, incluyendo casos límite.
• Decisiones ya tomadas: para no reabrir debates que ya se cerraron (ej. "usamos Postgres, no Mongo").
• Criterios de aceptación: cómo se sabe que está terminado.

Un ejemplo mínimo de spec

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Feature: límite en artículos guardados

## Contexto
Los usuarios acumulan favoritos que nunca leen. Queremos un límite duro
que los obligue a priorizar.

## Alcance
- Guardar/quitar artículos con un tope de 5 por usuario.
- Fuera de alcance: notificaciones, reordenamiento manual.

## Comportamiento esperado
- Al llegar al límite, agregar uno más se rechaza con un mensaje claro.
- Re-guardar un artículo ya guardado es un no-op, no un error.

## Criterios de aceptación
- [ ] No se puede superar el límite bajo ningún flujo, incluyendo doble click.
- [ ] El usuario ve cuántos espacios ocupó y cuántos le quedan.

Con esa spec ya escrita, implementar (o pedirle a un agente que implemente) deja de ser una negociación sobre qué se quiso decir, y pasa a ser un chequeo: ¿el código cumple esto, sí o no?

Por qué importa más con agentes de IA

Cuando el trabajo de escribir código lo delegás a un agente, la especificación pasa a cumplir el mismo rol que cumplía antes un tech lead explicando el ticket en persona: es el lugar donde se resuelven las ambigüedades antes de que se conviertan en código que hay que deshacer. Un buen indicador de que una spec está incompleta es que dos implementaciones razonables (humanas o generadas) del mismo texto terminan siendo notablemente distintas.

Spec-Driven Development no reemplaza la conversación ni la iteración — las adelanta al momento en que todavía son baratas de cambiar.