Dos personas dan a un agente de IA lo que parece la misma solicitud y obtienen resultados de calidad completamente distinta. ¿Qué es lo que realmente difiere entre esas solicitudes y cómo detectarlo antes de que la IA empiece siquiera a trabajar? La respuesta es una regla sencilla: cuanto mejor y más específicamente se describe una solicitud, mejor la ejecuta la IA. Parece obvio, pero en la práctica es la causa más común de malos resultados: no una capacidad insuficiente del modelo, sino una solicitud insuficientemente descrita.
Mal prompt: "Corrige el bug del inicio de sesión."
Buen prompt: "En AuthService.login() se produce un error cuando un usuario introduce un correo con mayúsculas: la comparación en la BD distingue mayúsculas de minúsculas. Corrige la normalización del correo para que ocurra ANTES de la comparación; no toques el hash de contraseñas ni la limitación de frecuencia en LoginThrottle.ts."
El segundo prompt contiene cuatro elementos clave de los que carece el primero:
- La ubicación exacta (archivo/función), no una descripción genérica.
- Una descripción de la causa raíz, no solo del síntoma.
- Exactamente qué hacer, no solo "corregirlo".
- Lo que no debe romperse: un límite explícito al cambio.
Sin el punto 4, la IA tiende a "mejorar" cosas que nunca se quiso que se tocaran, y ese es exactamente el momento en que se rompe la lógica posterior.
Es parecido a explicar a un niño de cinco años lo que debe hacer. Se le dice qué y cómo, pero es igual de importante decirle qué no hacer. Para un niño, ese límite es sobre todo educativo; para la IA, es una definición precisa de lo que no debe explorar ni modificar, y ese límite afina el resultado mucho más que cualquier descripción de qué buscar.
La misma lógica se aplica dentro de un único prompt: si se amontonan varios requisitos no relacionados a la vez, la IA no sabe cuál tiene prioridad y a menudo interpreta la Task de forma distinta a la pretendida. De ahí la regla sencilla: un prompt = una cosa concreta.
Esto vale tanto para los prompts escritos a mano como para las Tasks generadas automáticamente. Y esta disciplina es justamente lo que se puede automatizar, para que un prompt no salga de lo que una persona recuerde en ese momento, sino del conocimiento real y actual del código (Contracts, el mapa del DOM, la lógica de negocio) que AITM mantiene por cuenta de la persona usuaria.
Antes de ver la estructura del prompt en sí, vale la pena saber una cosa más: AITM no escribe todos los prompts de Task de la misma manera. Cuando se crea una Task, primero se clasifica a sí misma (o se elige) en una de tres categorías — bug (corregir un comportamiento existente), enhancement (mejorar algo que ya existe) o feature (funcionalidad completamente nueva) — y cada categoría produce un conjunto distinto de requisitos y criterios de verificación. Por ahora, centrémonos en lo que los tres tipos comparten: una estructura fija de 5 bloques.
Cómo lo hace realmente AITM: la estructura real del prompt
AITM no escribe los prompts de Task de forma libre. Cada prompt de Task generado desde Chat o Brainstorm consta de 5 bloques fijos, en este orden, y cada bloque resuelve un problema concreto que de otro modo llevaría a una Task poco clara:
- Role — como máximo 3 frases que describen qué rol y qué grado de enfoque conservador debe adoptar el agente. Sin este bloque, el agente no sabe cuánta "creatividad" se le permite, y la creatividad sin barreras es exactamente lo que lleva a cambios no deseados.
- Context — por qué existe la Task: el informe de la persona usuaria, el historial del problema, quién es responsable del área. Se separa con la frase "Context (background only — implement nothing from this block)", porque sin esa frase el agente corre el riesgo de implementar accidentalmente algo de la historia de fondo en lugar de centrarse únicamente en los requisitos.
- Requirements — un bloque numerado por requisito, cada uno con un criterio de aceptación preciso y verificable. Dividir los requisitos en bloques numerados resuelve directamente el problema comentado arriba: un bloque, una cosa concreta, sin mezclar varios requisitos en una sola frase.
- Scope — tres líneas: In scope (qué puede cambiarse), Out of scope (qué no debe cambiarse y quién es su responsable), Must not break (qué Contracts deben seguir cumpliéndose). Es una implementación directa de la regla "decir a la IA también lo que no debe hacer": sin este bloque, el agente no sabe dónde están los límites de su cambio.
- Output and verification — cada archivo nuevo que crea la Task, más comandos de verificación concretos limitados solo a lo que este cambio específico podría romper. De este modo la Task no se cierra con un "parece terminado", sino con un medible "este comando exacto pasó".
Obsérvense las referencias a Contracts como %AUTH-012: es una referencia a un Contract concreto, insertada con una sintaxis exacta que AITM reconoce y expande automáticamente en la descripción completa del comportamiento. Esta es exactamente la diferencia entre "escribir un prompt propio" y un sistema que impone por la persona usuaria una estructura y unas citas precisas.
Qué contiene realmente un Contract. En AITM, un Contract es un registro de la base de datos SQLite del proyecto, no un comentario de código. Tiene un ID corto (un prefijo de módulo más un número), un módulo (a qué parte del sistema pertenece el comportamiento) y, lo más importante, un campo de comportamiento: una descripción precisa, de varias frases, del mecanismo, a menudo con una referencia a líneas concretas de un archivo y al número de la Task en la que se originó el comportamiento. También incluye una lista de los archivos que toca el Contract, opcionalmente una zona de peligro y una lista de variables con las que se relaciona. Cuando el agente ve una referencia "Must not break" en el prompt, AITM inserta toda esta descripción en lugar del código a secas, de modo que el agente sabe exactamente qué comportamiento no debe violar.
¿Y las pruebas unitarias? También tienen su propio código: cada bloque de prueba de las pruebas de AITM lleva una etiqueta única al inicio de su descripción. Esto permite direccionar una prueba concreta con la misma precisión que un Contract. Un Contract además se empareja con la ruta del archivo de prueba, de modo que una referencia a un Contract acaba llevando no solo la descripción del comportamiento sino también un enlace directo a la prueba que lo protege.