SDD en la práctica: la plantilla de spec que uso con agentes de IA

Vengo escribiendo sobre Spec-Driven Development (SDD) como una forma de trabajar con agentes de IA sin perder control sobre lo que se construye. En este artículo comparto algo concreto: la plantilla de spec que uso, sección por sección, con el porqué de cada parte. Es la misma estructura que aplico a cada cambio en este sitio, que desarrollo íntegramente con SDD: cada cambio tiene spec, plan y cierre verificado en producción.

Al trabajar con agentes de IA en tareas de desarrollo, el problema que aparece rápido es este: sin una estructura clara, el agente interpreta, asume, y a veces construye algo que no se pidió. Para mí la spec no es burocracia: es el contrato que le da al agente un espacio de trabajo acotado y verificable.

Por qué una plantilla y no una conversación libre

Cuando le pedís algo a un agente en lenguaje natural sin estructura, el agente rellena los huecos con su propia interpretación. Eso funciona para tareas triviales, pero se rompe apenas el cambio toca lógica de negocio, integraciones o algo que ya existe en producción.

Una plantilla de spec ayuda a resolver esto porque:

Obliga a explicitar el contexto antes de pedir código.
Convierte "quiero que funcione bien" en criterios verificables.
Da al agente (y a quien revisa después) un documento contra el cual comparar el resultado final.

No hace falta que la spec sea extensa. Hace falta que sea completa en lo esencial.

La plantilla, sección por sección

Esta es la estructura que uso. La copio tal cual al arrancar cualquier cambio, y voy completando cada sección antes de dejar que el agente escriba una sola línea de código.

markdown

# Spec: [nombre corto del cambio]

## Resumen
[Una o dos frases: qué se va a construir y por qué]

## Contexto
[Qué existe hoy, qué problema resuelve este cambio,
qué restricciones técnicas o de negocio aplican]

## Requisitos funcionales
- [Requisito 1]
- [Requisito 2]
- [Requisito 3]

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

## Fuera de alcance
[Qué NO incluye este cambio, para evitar scope creep del agente]

Resumen

Es la frase que te obliga a saber qué estás pidiendo antes de pedírselo a nadie, ni humano ni agente. Si no podés resumir el cambio en una o dos frases, todavía no lo entendiste lo suficiente como para especificarlo.

Contexto

Esta sección es la que más previene errores de interpretación. Un agente no tiene memoria de por qué existe el código actual, ni de las decisiones que se tomaron antes. El contexto le da ese trasfondo: qué hay hoy, qué restricción técnica no se puede romper, qué decisión de negocio ya está tomada y no se discute en este cambio.

Requisitos funcionales

Acá describo el comportamiento esperado, no la implementación. Es la diferencia entre "el usuario puede filtrar resultados por fecha" y "usar un date-picker de tal librería". Los requisitos funcionales le dejan al agente el espacio para proponer implementación, pero fijan qué tiene que pasar sí o sí.

Criterios de aceptación

Esta es la sección que convierte la spec en algo verificable. Cada criterio tiene que poder marcarse como cumplido o no cumplido, sin ambigüedad. Es lo que después se usa para cerrar el ciclo: si un criterio no se puede marcar como cumplido, el cambio no está terminado, sin importar cuánto código se haya escrito.

Fuera de alcance

Es la sección que evita que el agente (o uno mismo) empiece a "mejorar" cosas que no se pidieron. Con agentes de IA esto es especialmente importante: tienden a ampliar el alcance si no se los frena explícitamente.

Los gates: sin spec no hay ciclo, sin ciclo no hay código

Esta es la regla que sostiene todo el proceso, y la aplico sin excepciones: sin spec no hay ciclo, sin ciclo no hay código.

En la práctica esto significa:

No se abre un ciclo de trabajo sin spec aprobada. Ni por el agente ni por mí. Si la spec no está completa, no hay nada que ejecutar todavía.
No se escribe código sin un ciclo definido. El ciclo es el plan de ejecución que se deriva de la spec: qué se va a tocar, en qué orden, y cómo se va a verificar.
El cierre se verifica contra los criterios de aceptación, no contra la sensación de "quedó bien". En este sitio, cada cambio tiene spec, plan y cierre verificado en producción: el cierre no es "lo subí", es "lo subí y confirmé que cumple lo que decía la spec".

Estos gates no son para desacelerar el trabajo. Son para evitar el peor escenario con agentes: código que funciona pero no resuelve lo que se pidió, o que resuelve algo distinto y nadie lo nota hasta producción.

Flow lite vs. flow full: no toda spec necesita el mismo peso

Un error común al adoptar SDD es aplicar el mismo nivel de formalidad a todos los cambios. Eso genera fricción innecesaria en tareas chicas y termina empujando a la gente a saltarse el proceso por completo. Por eso trabajo con dos modos:

Flow lite

Para cambios pequeños, acotados, de bajo riesgo: un ajuste de copy, una corrección de estilo, un fix puntual sin impacto en lógica de negocio.

Resumen + criterios de aceptación. Nada más.
El contexto se resuelve en una línea si hace falta.
El ciclo es casi inmediato: spec corta, ejecución, verificación.

Flow full

Para cambios que tocan lógica de negocio, integraciones, o cualquier cosa que si sale mal genera trabajo de corrección considerable.

Todas las secciones de la plantilla, completas.
El contexto se detalla con las restricciones reales.
El plan de ejecución (el "ciclo") se documenta antes de tocar código.
El cierre se verifica explícitamente contra cada criterio.

La decisión de qué flow usar no depende del tamaño del código que se va a escribir, sino del impacto del cambio. Un cambio de una línea que altera una regla de negocio va por flow full. Un refactor grande pero mecánico y de bajo riesgo puede ir por flow lite.

Registrar el consumo de tokens por agente

Algo que sumé a mi práctica y que me resultó útil desde el principio: registrar el consumo de tokens por agente y por ciclo.

¿Por qué me sirve?

Visibilidad del consumo real. Un cambio "chico" en apariencia puede consumir muchos más tokens de los esperados si el agente entra en iteraciones de prueba y error. Ese dato es información, no solo un número de facturación.
Comparación entre flow lite y full. Con el registro por ciclo se puede ver si un cambio que se trató como lite en realidad tuvo un consumo de flow full, señal de que la clasificación inicial estuvo mal.
Trazabilidad del proceso. Cuando un cierre se verifica en producción, tener el consumo de tokens asociado a esa spec y ese ciclo da una foto completa: qué se pidió, qué se ejecutó, qué costó.

No hace falta una herramienta sofisticada para esto. Alcanza con anotar, junto a cada spec cerrada, el agente usado y el consumo aproximado del ciclo. Con el tiempo, ese registro se convierte en una fuente de datos para decidir mejor cuándo vale la pena flow full y cuándo no.

Cómo se ve en la práctica

En este sitio, cada cambio, desde un ajuste de contenido hasta una modificación de infraestructura, sigue el mismo esqueleto: spec, plan (el ciclo), ejecución y cierre verificado en producción. No es un proceso que reserve para proyectos grandes; es la misma disciplina que aplico en algo tan simple como un blog, porque una disciplina que no se sostiene en lo simple difícilmente se sostenga en lo complejo.

Qué me llevo

La spec es un contrato de trabajo con el agente, no burocracia: acota el espacio y da algo contra qué verificar.
Los criterios de aceptación verificables y el "fuera de alcance" son las secciones que más vueltas me ahorran.
Los gates sin excepciones (sin spec no hay ciclo, sin ciclo no hay código) evitan el código que funciona pero resuelve otra cosa.
El peso del proceso se decide por impacto, no por tamaño: flow lite para lo acotado, flow full para lo que toca negocio o integraciones.
Registrar el consumo por agente y ciclo ayuda a revisar si la clasificación fue acertada.

La plantilla que compartí arriba es la que uso; puede servirle a otros equipos como punto de partida para adaptarla a su contexto. Si estás trabajando en algo parecido o tu equipo está evaluando cómo incorporar agentes de IA, me interesa intercambiar experiencias: podés escribirme por LinkedIn. Y si querés seguir leyendo sobre SDD, te invito a recorrer mi proyecto: https://sdd.estebanburgos.com.ar.