Quando si avvia un nuovo progetto da zero, programmare con l'IA sembra pura magia. Si scrive un prompt e il modello genera senza esitare un componente pulito o un endpoint backend funzionante.
Ma man mano che la codebase cresce, arriva il brusco risveglio.
Intorno alle 100 000 righe di codice, una normale IA inizia a perdere sensibilmente il fiato. Prova a indovinare, cerca nel repository alla cieca e inventa funzioni che non esistono. Intorno alle 300 000 righe il giudizio autonomo del modello collassa praticamente del tutto: la finestra di contesto non basta, il classico grep sull'intero progetto brucia migliaia di token e lo sviluppo si trasforma in un ciclo infinito di correzioni di codice rotto.
È proprio qui che i contratti di sistema prendono in mano le redini.
Che cos'è un contratto in AITM?
Un contratto non è un normale commento inline nel codice, né una riga di un README.md dimenticato che dopo due sprint smette di essere vera.
È comportamento del sistema interrogabile da una macchina.
Descrive con precisione cosa deve fare una parte specifica dell'applicazione e rimanda ai file sorgente, ai test e agli elementi dell'interfaccia esatti. Invece di brancolare e leggere decine di file, l'agente pone al sistema una domanda diretta: "Dove e come è implementato questo comportamento?" e ottiene subito una risposta precisa.
Ogni contratto in AITM poggia su tre pilastri fondamentali:
- behavior: L'essenza in una riga di ciò che fa il codice. Il campo più importante di tutti. L'agente confronta questa regola con l'implementazione reale nel file. Se emerge una contraddizione, il sistema sa subito che si tratta di un bug o di un contratto obsoleto.
- confidence: Una metrica di affidabilità dell'informazione. Indica quanto è attendibile la descrizione rispetto agli altri dati del sistema (ad esempio se il comportamento è verificato da test reali).
- variables: Il collegamento con il linguaggio comune del sistema (ad esempio
BL.PIPELINE). Fa da ponte tra la logica di business del frontend e del backend, così i contratti si possono filtrare in un attimo per una specifica parte dell'interfaccia o del livello dati.
Un esempio reale dalla produzione
In AITM un contratto è strutturato e immediatamente disponibile tramite l'API GraphQL:
contractsForFile(path: "src/pipeline/MergeQueueService.ts", projectId: "ctm-dashboard") {
id # "GM-057"
module # "Git/Merge"
behavior # "Il riavvio dopo self-merge è manuale: dopo il merge, dev-watch continua a servire il codice precedente al merge finché l'utente non clicca Restart nel menu oppure Settings.selfMergeRestartMode è 'auto'."
confidence # "tested"
}
Questa è la differenza fondamentale rispetto alla documentazione statica. L'agente richiede il contratto prima ancora di aprire o scrivere una sola riga di codice. Non agisce alla cieca, non spreca contesto e sa esattamente quale peso dare alla regola.
Risparmiamo token e tempo di calcolo: Claude Sonnet con effort basso o medio
Uno dei maggiori vantaggi della guida precisa tramite contratti è l'efficienza del modello di IA stesso.
In AITM i nostri agenti lavorano su Claude Sonnet con effort (thinking) da basso a medio. Quando il modello ha a disposizione un contratto preciso, non servono minuti di "riflessione", non deve speculare sull'architettura dell'intero repository né bruciare un enorme budget di ragionamento in ricerche banali.
Grazie al contratto il modello riceve una mappa già pronta:
- Sa esattamente in quale file andare.
- Conosce il comportamento atteso (
behavior). - Sa quanto fidarsi dell'informazione (
confidence).
Anche con un effort inferiore, Claude Sonnet svolge così un lavoro pulito e del tutto deterministico, perché non deve affidarsi alla propria "stima", ma segue rigorosamente la specifica data.
Il risultato su 500K righe di codice
La vera forza di questo approccio non emerge nei primi giorni di un progetto, ma quando la codebase raggiunge dimensioni enterprise.
Nel nostro sistema, con più di 500 000 righe di codice, oggi funzionano in modo affidabile circa 3 500 contratti:
- Fine del grep alla cieca: L'agente non cerca tra centinaia di file, va direttamente sul sicuro.
- Riduzione radicale di token e allucinazioni: La finestra di contesto resta pulita e il modello non soffre di sovraccarico informativo.
- Risultati coerenti: Anche su un progetto da mezzo milione di righe, l'IA raggiunge la stessa velocità e precisione del primo prompt su un repository vuoto.