Cuando empieza un proyecto nuevo desde cero, programar con IA parece pura magia. Escribe un prompt y el modelo genera sin dudar un componente limpio o un endpoint de backend que funciona.
Pero a medida que la base de código crece, llega el golpe de realidad.
Hacia las 100 000 líneas de código, una IA corriente empieza a perder el aliento de forma notable. Intenta adivinar, rastrea el repositorio a ciegas y alucina funciones que no existen. Hacia las 300 000 líneas, el criterio autónomo del modelo prácticamente se derrumba: la ventana de contexto no basta, el grep clásico sobre todo el proyecto quema miles de tokens y el desarrollo se convierte en un ciclo interminable de arreglar código roto.
Justo ahí es donde los contratos del sistema toman las riendas.
¿Qué es un contrato en AITM?
Un contrato no es un comentario en línea cualquiera, ni una línea de un README.md olvidado que deja de ser cierta tras dos sprints.
Es comportamiento del sistema consultable por máquina.
Describe con precisión qué debe hacer una parte concreta de la aplicación y apunta a los archivos fuente, las pruebas y los elementos de la interfaz exactos. En lugar de tantear y leer decenas de archivos, el agente le hace al sistema una pregunta directa: "¿Dónde y cómo está implementado este comportamiento?", y recibe al instante una respuesta precisa.
Cada contrato de AITM se apoya en tres pilares clave:
- behavior: La esencia en una línea de lo que hace el código. El campo más importante de todos. El agente compara esta regla con la implementación real del archivo. Si surge una contradicción, el sistema sabe de inmediato que se trata de un bug o de un contrato desactualizado.
- confidence: Una métrica de fiabilidad de la información. Indica qué tan fiable es la descripción en relación con el resto de los datos del sistema (por ejemplo, si el comportamiento está verificado con pruebas reales).
- variables: El enlace con el lenguaje de comunicación común del sistema (por ejemplo,
BL.PIPELINE). Funciona como puente entre la lógica de negocio del frontend y del backend, de modo que los contratos pueden filtrarse al instante por una parte concreta de la interfaz o de la capa de datos.
Un ejemplo real de producción
En AITM un contrato está estructurado y disponible de inmediato a través de la API GraphQL:
contractsForFile(path: "src/pipeline/MergeQueueService.ts", projectId: "ctm-dashboard") {
id # "GM-057"
module # "Git/Merge"
behavior # "El reinicio tras self-merge es manual: después del merge, dev-watch sigue sirviendo el código previo al merge hasta que el usuario pulsa Restart en el menú o Settings.selfMergeRestartMode vale 'auto'."
confidence # "tested"
}
Esta es la diferencia fundamental con la documentación estática. El agente solicita el contrato antes de abrir o escribir una sola línea de código. No actúa a ciegas, no malgasta contexto y sabe exactamente qué peso dar a la regla.
Ahorramos tokens y tiempo de cómputo: Claude Sonnet con esfuerzo bajo o medio
Uno de los mayores beneficios de guiar con precisión mediante contratos es la eficiencia del propio modelo de IA.
En AITM nuestros agentes trabajan con Claude Sonnet con un esfuerzo (thinking) de bajo a medio. Cuando el modelo dispone de un contrato preciso, no necesita minutos de "pensar", especular sobre la arquitectura de todo el repositorio ni quemar un enorme presupuesto de razonamiento en una investigación trivial.
Gracias al contrato, el modelo recibe un mapa ya hecho:
- Sabe exactamente a qué archivo ir.
- Conoce el comportamiento esperado (
behavior). - Sabe cuánto debe fiarse de la información (
confidence).
Incluso con un esfuerzo menor, Claude Sonnet entrega un trabajo limpio y totalmente determinista, porque no tiene que apoyarse en su propia "suposición", sino que sigue estrictamente la especificación dada.
El resultado con 500K líneas de código
La verdadera fuerza de este enfoque no se aprecia en los primeros días de un proyecto, sino cuando la base de código alcanza un tamaño empresarial.
En nuestro propio sistema, con más de 500 000 líneas de código, hoy funcionan de forma fiable unos 3 500 contratos:
- Se acabó el grep a ciegas: El agente no rastrea cientos de archivos, va directo a lo seguro.
- Reducción radical de tokens y alucinaciones: La ventana de contexto se mantiene limpia y el modelo no sufre sobrecarga de información.
- Resultados consistentes: Incluso en un proyecto de medio millón de líneas, la IA alcanza la misma rapidez y precisión que con el primer prompt en un repositorio vacío.