Un recente studio pubblicato dai ricercatori dell’ETH Zurich ha messo in discussione una convinzione sempre più diffusa nella comunità degli sviluppatori che utilizzano agenti di codifica basati su modelli linguistici avanzati: l’idea che fornire un file di descrizione completa del repository, come AGENTS.md, migliori automaticamente le prestazioni dell’intelligenza artificiale. Il lavoro, intitolato “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents” e pubblicato su arXiv, mostra risultati controintuitivi: l’inclusione sistematica di file di contesto a livello di repository può ridurre i tassi di successo e aumentare i costi operativi in modo significativo.
Il concetto di “ingegneria del contesto” nasce dall’osservazione che i modelli di grandi dimensioni, quando operano come agenti autonomi di programmazione, traggono beneficio da informazioni aggiuntive sul progetto. File come AGENTS.md o CLAUDE.md sono stati progressivamente considerati quasi indispensabili, fungendo da guida strutturale per l’AI: descrizioni dell’architettura, struttura delle cartelle, strumenti utilizzati, convenzioni di stile, istruzioni operative. Tuttavia, fino a oggi, mancavano verifiche sperimentali su larga scala che dimostrassero l’effettiva utilità di questi file in contesti reali di sviluppo software.
Per colmare questa lacuna, i ricercatori hanno costruito un nuovo benchmark denominato AGENTBENCH, derivato da attività già presenti in SWE-Bench e integrato con problemi tratti da progetti open source reali. Il benchmark è stato utilizzato per valutare diversi modelli di punta, tra cui Claude Sonnet 4.5, GPT-5.2 e QONE3-30B, analizzando il comportamento degli agenti in tre condizioni: assenza di file di contesto, presenza di file AGENTS.md generato automaticamente da un LLM e presenza di file scritto manualmente da uno sviluppatore.
I risultati hanno mostrato che l’aggiunta di un file AGENTS.md generato da un modello linguistico ha ridotto il tasso di successo delle attività di circa il 3%. Ancora più significativo è stato l’impatto sui costi: l’inclusione del file ha richiesto un numero maggiore di passaggi di inferenza per risolvere gli stessi problemi, con un incremento dei costi superiore al 20%. In altre parole, l’operazione che avrebbe dovuto rendere l’agente più efficiente si è trasformata in un fattore di degrado delle prestazioni e di aumento delle risorse computazionali necessarie.
Anche i file scritti da sviluppatori umani non hanno prodotto miglioramenti sostanziali. L’incremento medio delle prestazioni si è attestato attorno al 4%, un valore che, pur positivo, non compensa l’aumento di complessità e di token trasmessi a ogni ciclo di inferenza. È importante sottolineare che, nei sistemi basati su LLM, l’intero contenuto del file di contesto viene generalmente incluso nel prompt o nel sistema di memoria contestuale a ogni richiesta. Questo implica che ogni riga aggiunta ha un costo diretto in termini di token elaborati e di latenza.
Un elemento particolarmente interessante dello studio riguarda l’uso di modelli più potenti per generare file di contesto migliori. Anche quando AGENTS.md veniva creato da GPT-5.2, i risultati non cambiavano in modo significativo. Questo suggerisce che i modelli di ultima generazione possiedono già una conoscenza approfondita di librerie comuni, strutture di progetto e pratiche di sviluppo standard. L’informazione aggiuntiva, anziché chiarire, può diventare rumore ridondante che interferisce con i meccanismi di pianificazione dell’agente.
I ricercatori hanno definito questo fenomeno “tassa generata automaticamente”. L’espressione indica che la documentazione creata automaticamente, pur concepita per essere utile, introduce un costo latente sotto forma di sovraccarico cognitivo per il modello e di consumo computazionale aggiuntivo. Dal punto di vista architetturale, il problema è legato al modo in cui gli agenti di codifica pianificano le azioni: essi tendono a seguire in modo estremamente letterale le istruzioni presenti nel file di contesto. Se tali istruzioni sono superflue, troppo generiche o eccessivamente dettagliate, l’agente può intraprendere percorsi meno efficienti o eseguire controlli inutili.
Un esempio emblematico riguarda le descrizioni dettagliate della struttura delle cartelle. Gli agenti moderni sono in grado di navigare autonomamente nel repository, esplorare file e comprendere la gerarchia del progetto attraverso chiamate dirette agli strumenti di esplorazione del filesystem. Forzare la lettura preventiva di una descrizione testuale della struttura non aggiunge informazione sostanziale, ma consuma token e influenza il piano d’azione.
Analogamente, linee guida stilistiche come l’uso di camelCase o snake_case sono meglio gestite da strumenti automatizzati quali linter e formatter, che operano in modo deterministico. Inserire queste regole nel file di contesto può addirittura introdurre ambiguità se non sono universalmente applicabili a tutto il progetto. La documentazione ridondante, soprattutto quando generata automaticamente, può sovrapporsi a documentazione esistente ben strutturata, creando incoerenze e confusione.
Lo studio evidenzia tuttavia che non tutti i contenuti sono inutili. Le informazioni realmente distintive del progetto, come l’uso di strumenti non convenzionali per build e test, possono avere un impatto significativo. L’inclusione esplicita di strumenti alternativi come uv al posto di pip o bun al posto di npm ha portato a un aumento massiccio dell’utilizzo corretto da parte dell’agente, fino a 160 volte in alcuni casi. Questo dimostra che gli agenti seguono con grande fedeltà le istruzioni quando esse contengono elementi specifici e non deducibili dal contesto generale.
Dal punto di vista pratico, i ricercatori suggeriscono che un file AGENTS.md efficace dovrebbe essere breve, idealmente inferiore alle 300 righe e preferibilmente anche sotto le 60. La concisione riduce direttamente il costo di inferenza e minimizza il rischio di introdurre rumore. È inoltre consigliabile mantenere nel file radice solo le informazioni essenziali e collegare documentazione più dettagliata tramite riferimenti puntuali, ad esempio indicando file e numeri di linea, invece di copiare interi blocchi di codice che potrebbero diventare obsoleti.
Il contributo più rilevante dello studio non è soltanto la quantificazione del calo di performance o dell’aumento dei costi, ma la ridefinizione dell’obiettivo dell’ingegneria del contesto. Non si tratta di fornire all’AI il massimo numero possibile di informazioni, bensì di ridurre il carico informativo non necessario. In un’epoca in cui i modelli di grandi dimensioni incorporano già una vasta conoscenza generale, la chiave non è ripetere ciò che il modello sa già, ma segnalare ciò che è specifico, atipico o non inferibile automaticamente.
Questo lavoro mette quindi in discussione l’idea che file come AGENTS.md o CLAUDE.md siano configurazioni imprescindibili per ottenere buone prestazioni dagli agenti di codifica. La ricerca dimostra numericamente che file mal progettati possono trasformarsi in un ostacolo, peggiorando sia l’efficacia sia l’efficienza economica del sistema. Per gli sviluppatori e i team che integrano agenti AI nei flussi di lavoro, la lezione è chiara: l’ingegneria del contesto deve essere minimalista, mirata e strategica. L’obiettivo non è documentare tutto, ma fornire solo il contesto che il modello non può dedurre autonomamente.