Spec-driven development con IA: primero la spec, después el código

La mayoría de los equipos usa la IA como si escribiera los prompts de memoria. Abres un agente, describes la tarea en tres frases, obtienes código, lo corriges, obtienes más código. Funciona, hasta que la tarea deja de caber en una sola frase. Entonces el agente adivina, y te encuentras corrigiendo las consecuencias de tu propia intención mal especificada. El spec-driven development invierte el orden: primero escribes la especificación y después el agente la implementa. El código es el resultado, no el punto de partida.

Por qué una especificación escrita supera a los prompts de memoria

Un prompt de memoria tiene tres defectos que crecen con la velocidad del agente. Primero, es efímero: se cae del contexto tras unos cuantos turnos, así que el agente empieza a trabajar a partir de su propia interpretación de hace diez mensajes. Segundo, es incompleto: en tu cabeza tienes restricciones (presupuesto de tiempo, formato de datos, ruta de rollback) que nunca dices en voz alta porque “son obvias”. Para un agente, nada es obvio. Tercero, no se puede verificar: como nunca escribiste qué había que construir, no tienes forma de comprobar si se construyó.

Una spec escrita elimina los tres. Es duradera, así que el agente vuelve a ella en cada turno en lugar de adivinar. Es completa, porque el acto de escribir te obliga a nombrar las restricciones que, de otro modo, se quedarían en tu cabeza. Es verificable, porque contiene criterios de aceptación con los que contrastar el código terminado. No es burocracia: es trasladar el pensamiento de la fase de correcciones a la fase de diseño, donde cuesta diez veces menos.

Anatomía de un buen SPEC.md

Una buena spec tiene una estructura fija, de modo que tanto la persona como el agente saben dónde buscar cada cosa. Cinco secciones cubren el 95% de los casos.

Objetivo. Una frase, dos como mucho: qué y para quién. No “cómo”, sino “por qué”. Si no puedes resumir el objetivo en dos frases, probablemente tienes dos tareas haciéndose pasar por una.

Requisitos funcionales. Una lista de comportamientos observables. Cada punto describe algo que el sistema hace, idealmente con la forma “cuando X, entonces Y”. Es el núcleo de la spec y donde pasas la mayor parte del tiempo.

Requisitos no funcionales. Las restricciones que es fácil pasar por alto: latencia, costo de las llamadas al LLM, límites de memoria, compatibilidad con versiones anteriores, ruta de rollback, seguridad de los datos. Suelen ser lo que decide si una implementación está lista para producción.

Fuera de alcance. Una lista explícita de lo que no vamos a hacer en esta iteración. Sin esta sección, el agente (servicial hasta el exceso) añade funcionalidades que nadie pidió, y tú acabas revisando código que nunca debió existir.

Criterios de aceptación. Una lista verificable de condiciones de “terminado”, idealmente en una forma que puedas convertir en tests. Si un criterio no se puede verificar, no es un criterio: es un deseo.

Cómo usa el agente la spec como contrato

Cuando la spec está lista, deja de ser una nota y se convierte en un contrato. El agente la recibe como contexto estable y trabaja dentro de sus límites: los requisitos funcionales le dicen qué construir; los no funcionales, dentro de qué márgenes moverse; el fuera de alcance, dónde detenerse, y los criterios de aceptación, cuándo dar la tarea por terminada.

Este cambio tiene consecuencias prácticas. Primero, puedes pedirle al agente que compruebe su propio trabajo frente a los criterios de aceptación antes de darlo por terminado, y que lo devuelva para corregirlo sin que tengas que intervenir. Segundo, cuando el agente quiere hacer algo que está fuera de la spec, se nota al instante: o está rompiendo el contrato o la spec estaba incompleta. En ambos casos recibes la señal pronto, y no en la revisión tras dos horas de generación.

El contrato también cambia la naturaleza de tu revisión. Sin spec, lees el código y te preguntas “¿hace esto lo que yo quería?”, apoyándote en tu recuerdo de lo que querías. Con spec, te preguntas “¿cumple los criterios de aceptación?”, y la respuesta es binaria e independiente de tu estado de ánimo. La revisión deja de ser una negociación y pasa a ser una comprobación frente a un estándar acordado de antemano. Lo mismo vale para un agente revisor: tiene un punto de referencia explícito, así que sus comentarios son concretos en lugar de vagos.

Iterar spec-first en lugar de code-first

El cambio mental clave: cuando la implementación sale mal, no corriges el código, corriges la spec. El código es barato y reproducible; el agente lo regenerará en un minuto. La spec es la fuente de verdad, así que es ahí donde corriges la causa, no el síntoma.

En la práctica es así: el agente entrega una implementación, tú la lees a la luz de los criterios de aceptación y encuentras un desajuste. En lugar de escribir “cambia esto y aquello” en el chat, vuelves a la spec, añades el requisito que faltaba o aclaras el ambiguo, y pides que se vuelva a implementar la parte afectada. Tras unas cuantas iteraciones, la spec es precisa y el código es su reflejo fiel. Las correcciones por chat hacen lo contrario: el código cuadra, pero la spec se queda atrás y ya nadie sabe qué es verdad.

Este enfoque también te protege de la trampa más común con la IA: entregar rápido algo que parece funcionar, pero que resuelve la mitad del problema. Los criterios de aceptación son implacables: o se cumplen todos o la tarea no está terminada, por muy bonito que se vea el código.

Una spec corta es una buena spec

Una spec debería caber en 400-800 palabras. No es un límite arbitrario: es el umbral por debajo del cual la spec sigue siendo legible de un vistazo, tanto para una persona como para la ventana de contexto del agente. Una spec más larga suele ser síntoma de uno de dos problemas: o la tarea es demasiado grande y conviene dividirla en varias specs más pequeñas, o estás describiendo la implementación en lugar de la intención.

La segunda trampa es traicionera. Cuanto más “cómo” metes en la spec, menos margen le dejas al agente para una solución que podría superar tu primera idea, y más rápido queda obsoleta la spec con cada cambio de código. La spec describe el qué y el por qué; deja el cómo al agente, salvo que el “cómo” sea un requisito no funcional estricto.

Un ejemplo de esqueleto de spec que cabe en el límite:

• Objetivo: un endpoint para exportar en PDF las facturas de un cliente, usado por el panel de facturación.
• Funcionales: cuando un cliente solicita una exportación, el sistema devuelve un PDF con todas las facturas del periodo elegido; cuando el periodo está vacío, devuelve un mensaje claro; cuando el cliente no tiene permisos, devuelve 403.
• No funcionales: respuesta en menos de 2 s para 100 facturas; ningún PDF almacenado en disco; logs sin datos personales.
• Fuera de alcance: envío por correo electrónico, exportación a otros formatos, facturación recurrente.
• Aceptación: un test para un periodo con facturas devuelve un PDF válido; un test con un periodo vacío devuelve un mensaje, no un error; un test sin permisos devuelve 403; tiempo de respuesta p95 inferior a 2 s.

Cómo escala esto en un equipo

Spec-first deja de ser una disciplina personal y se convierte en un protocolo de equipo. La spec es un artefacto compartido que puedes poner en un PR junto al código, enlazar en un issue y revisar igual que un diff. Revisar una spec es más barato que revisar una implementación, porque se lee en un minuto y detecta suposiciones erróneas antes de que nadie escriba una línea de código.

Para un equipo, esto aporta tres cosas. Onboarding: una persona nueva lee la spec y entiende la intención sin hacer arqueología en el código. Coherencia: dos personas con la misma spec obtienen del agente soluciones comparables, porque el contrato es el mismo. Auditabilidad: a posteriori sabes qué había que construir y por qué, así que las decisiones son reproducibles en lugar de quedar encerradas en la memoria de alguien.

En la práctica, adopta una regla sencilla: todo cambio que toque más de unos pocos archivos lleva una spec que una persona aprueba antes de la implementación. El agente puede escribir el primer borrador (se le da bien), pero la aprobación es humana. Sin esa decisión, la spec deja de ser un contrato y se convierte en otro texto generado en el que nadie confía.

TL;DR

El spec-driven development con IA invierte el orden: primero escribes un SPEC.md corto (400-800 palabras) con un objetivo, requisitos funcionales y no funcionales, una sección de fuera de alcance y criterios de aceptación, y solo entonces el agente lo implementa. La spec es un contrato: el agente trabaja dentro de sus límites y, cuando algo sale mal, corriges la spec, no el código. Una spec corta se mantiene legible y actualizada; como artefacto de equipo, escala el onboarding, la coherencia y la auditabilidad. Una spec escrita supera a los prompts de memoria porque es duradera, completa y verificable, y la aprobación final siempre corresponde a una persona.