El spec es el artefacto, no el prompt

La primera vez que intenté llevar a producción un agent no trivial, el artefacto bajo review era un system prompt gigante — seis párrafos, una lista de tools, unos pocos diálogos de ejemplo, y una lista de "no hagas" que crecía cada vez que algo se rompía. Los reviewers comentaban sobre la prosa. Los nuevos comportamientos llegaban como ediciones de prompt, a veces en PRs, a veces pegadas en Slack. No había una única respuesta a la pregunta ¿qué se supone que debe hacer este agent?

Eso no escala más allá de un agent.

Cómo se ve un spec

Un spec es un único artefacto bajo control de versiones por agent. Dice:

• Identidad: nombre, rol, de qué es responsable en una oración.
• System prompt: el prompt real, tal como se renderiza. Incluye referencias a instrucciones canónicas que otros specs comparten.
• Lista de tools: cada tool que el agent puede llamar, con el contrato que el MCP server impone. Sin tools mágicas.
• Guardrails: cosas que el agent debe rechazar. Concretas, testeables.
• Output schema: la forma del structured output, validado en el límite. Texto libre solo cuando el consumidor es el usuario.
• Evaluaciones: qué escenarios debe pasar este agent. Benchmarks públicos más la suite held-out.

Los reviewers aprueban el spec. El runtime se genera a partir de él.

Qué cambia

Tres cosas, todas ellas load-bearing.

Los reviews son sobre comportamiento, no sobre redacción. "Hacé el agent más útil" deja de ser un comentario de PR útil. La conversación pasa a ser "falta este guardrail", o "esta tool no está en la lista — ¿debería estar?", o "el output schema no cubre el caso vacío". Realmente podés estar en desacuerdo sobre algo concreto.

Las mejoras se acumulan. Cada ajuste de prompt que alguien entregó en Slack el trimestre pasado ahora está en el spec o no lo está. Si no lo está, o se vuelve a derivar desde primeros principios o se descarta en silencio — ambos son buenos resultados.

El onboarding es un directorio. Un ingeniero nuevo lee cuatro specs y sabe qué hace el sistema. No lee fragmentos de prompt dispersos en doce archivos.

Dónde es más difícil de lo que suena

Los specs no son gratis. Tres costos honestos:

1. Necesitás una capa de tools. Si tu agent está llamando httpx.get(...) inline, no hay disciplina de spec que imponer. El spec asume que las tools son tipadas, versionadas y descubribles. MCP encaja.
2. Necesitás una suite de evals real. Sin una, el spec es solo prosa esperanzada. La eval es lo que convierte al spec en un contrato.
3. Necesitás escribir el spec. Esta es la parte que se siente como burocracia hasta que el segundo agent entra en producción.

Se paga solo la primera vez que tenés que debuggear una regresión en producción leyendo algo que no sean chat logs.