Del prompt al spec: cómo una especificación gobierna a los agentes

Le pides a un agente "hazme el módulo de facturación" y te devuelve algo. Funciona a medias, inventó una regla que nadie pidió y borró otra que sí importaba. No falló el modelo: falló el encargo. Le diste un deseo, no un contrato. Esa es la diferencia entre un prompt y una especificación, y es la línea que separa el vibe coding del trabajo gobernado.

En Qirava dejamos de pedirle a la IA "a ver qué sale". No escribimos prompts sueltos con la esperanza de que el modelo adivine bien. Primero escribimos la spec: qué se va a construir, con qué criterios se acepta y qué queda fuera. Luego, y solo luego, se ejecuta. A este método lo llamamos SDD, Spec-Driven Development: la especificación manda, la ejecución obedece.

01 · el problemaUn prompt pide, una spec gobierna

Un prompt es una petición en lenguaje natural. Es rápido, flexible y ambiguo por diseño. Sirve para explorar, para preguntar, para tantear. Pero la ambigüedad que lo hace cómodo es la misma que lo hace peligroso cuando el resultado tiene que ser correcto: el modelo llena los huecos que dejaste, y los llena a su criterio, no al tuyo.

Una spec es otra cosa. Es un documento que fija el contrato: el alcance (qué entra y qué no entra), las entradas y salidas esperadas, las reglas de negocio, y sobre todo los criterios de aceptación, esas condiciones verificables que deciden si el trabajo está bien o mal. Un prompt se responde. Una spec se cumple o no se cumple, y eso se puede comprobar.

El prompt te da lo que el modelo cree que quisiste. La spec le exige lo que tú definiste.

La diferencia no es de formato, es de poder. Cuando un agente recibe un prompt, la fuente de verdad vive en la cabeza de quien lo escribió. Cuando recibe una spec, la fuente de verdad es un documento que ambos pueden citar, revisar y auditar. Esa idea de "escribe primero el resultado deseado, luego construye hacia atrás" no la inventamos nosotros: es el corazón del método working backwards de Amazon, donde un producto empieza por su nota de prensa y sus preguntas frecuentes antes de existir una sola línea de código [1].

02 · el gobiernoLa spec gobierna al agente, no al revés

Aquí está el giro que cambia todo: en Qirava, cada agente nace bajo gobierno. No es un asistente genérico al que le tiras un prompt. Al arrancar, carga dos cosas: una skill universal, qirava-llm-governance, que fija las reglas del juego para todos, y la skill de su rol, que le da su oficio.

Los roles se arman como paquetes de skills con cuatro capas: universal, primaria, secundaria y prohibida. Esa última capa importa tanto como las otras: define lo que ese agente no puede hacer. Un rol de marketing no toca arquitectura; un rol de QA no aprueba lo que él mismo produjo. Así se ve el elenco:

La spec es lo que le dice a cada uno de estos agentes qué construir y con qué criterio se acepta. Sin spec, un agente gobernado sabe cómo comportarse pero no qué lograr. Con spec, tiene ambas cosas: el oficio y el encargo, el marco y la meta. Por eso rinde más: deja de gastar capacidad adivinando el objetivo y la invierte en cumplirlo. La industria camina en la misma dirección; herramientas como GitHub Spec Kit existen precisamente para poner la especificación, y no el prompt improvisado, en el centro del desarrollo con IA [2].

03 · la fronteraDeliberar no es ejecutar: la línea que ningún borrador cruza

Hay un principio que sostiene todo el método y conviene decirlo sin rodeos: los borradores deliberan, pero no simulan ejecución. Deliberar es proponer, evaluar y decidir. Ejecutar es hacer el cambio real. Son cosas distintas y no se deben mezclar.

Un agente en estado de borrador puede analizar una spec, discutir alternativas, señalar riesgos y recomendar un camino. Lo que no puede es fingir que ya hizo el trabajo, ni tocar el sistema real como si estuviera aprobado. Esa frontera es lo que evita que una propuesta se cuele como un hecho, y es la razón por la que las compuertas de madurez tienen sentido: un borrador vive en G1, delibera cuanto haga falta, pero solo cruza a G2 (operativa) cuando el CEO aprueba. Recién ahí ejecuta.

Y cuando por fin se ejecuta, no se da por bueno a la primera. QA en Qirava es un bucle con regresión profesional: se prueba contra los criterios de aceptación de la spec hasta certificar, no se hacen retests amañados para "pasar". Si algo se rompió en otra parte, la regresión lo caza. La spec cierra el círculo: definió el criterio al principio y es la vara con la que se mide al final.

Todo esto se apoya en una fuente documental de verdad, un DOCUMENT_INDEX que dice cuál es la versión válida de cada cosa. Las skills viven en un toolkit; el gobierno, en un vault; se consumen por symlink. No hay copias sueltas ni verdades paralelas. Un agente que necesita saber "cuál es la regla" no la improvisa: la busca en el índice.

Un prompt confía en la memoria de quien lo escribió. Una spec confía en un documento que cualquiera puede auditar.

Al final, pasar del prompt a la spec no es burocracia: es lo que convierte a un agente listo pero suelto en un agente listo y gobernado. El prompt pregunta "¿qué sale?". La spec responde antes: "esto es lo que tiene que salir, y así sabremos si salió". Con ese contrato en la mano, el agente deja de adivinar y empieza a cumplir.