AGENTS.md: cosa metterci e cosa no

AGENTS.md è un file markdown che metti nella radice del repository per spiegare agli agenti di programmazione come si costruisce, si prova e si scrive codice in quel progetto. Il sito ufficiale del formato lo dichiara adottato da oltre 60.000 progetti open source, e lo leggono senza nessuna configurazione strumenti come Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Zed e Windsurf. Funziona meglio corto che lungo, ed è la parte controintuitiva: uno studio su 124 pull request ha misurato un tempo di esecuzione mediano più basso del 28,64% quando il file è presente, mentre riempirlo di istruzioni superflue peggiora le risposte invece di migliorarle. Claude Code è l'eccezione da conoscere subito, perché legge CLAUDE.md e questo formato non lo apre affatto.

Cos'è il file AGENTS.md e quali strumenti lo leggono

È un README scritto per gli agenti invece che per le persone, un solo file di testo nella radice del progetto dove metti le informazioni che un collaboratore appena arrivato ti chiederebbe il primo giorno. Il formato nasce per chiudere una frammentazione diventata ingestibile, perché ogni strumento aveva inventato il proprio file di regole e mantenerne cinque allineati nello stesso repository era lavoro buttato.

Oltre a quelli già citati, l'elenco delle integrazioni sul sito del formato comprende Google Jules, Devin, JetBrains Junie, Warp, VS Code e il coding agent di GitHub Copilot. Non c'è niente da installare e nessun campo obbligatorio, perché è markdown normale che ogni agente inietta nel proprio contesto all'inizio della conversazione.

AGENTS.md serve davvero o è solo cerimoniale

Serve, e per la prima volta esiste una misura invece di un'opinione. Un gruppo di ricercatori guidato da Jai Lal Lulla ha pubblicato su arXiv "On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents", depositato il 28 gennaio 2026, in cui hanno fatto lavorare Codex e Claude Code su 10 repository e 124 pull request nelle due condizioni, con il file e senza.

Il risultato è un tempo di esecuzione mediano inferiore del 28,64% e un consumo di token in uscita inferiore del 16,58%, a fronte di un comportamento di completamento delle task paragonabile. Dieci repository restano un campione piccolo e gli stessi autori parlano di associazione e non di causa dimostrata, però la direzione ha senso: un agente che non deve dedurre da solo quale comando lancia i test smette di esplorare a tentativi e arriva prima al punto.

Cosa scrivere dentro AGENTS.md

Le informazioni che non si deducono guardando il codice, cominciando dai comandi esatti. Come si installano le dipendenze, come si lancia la suite di test e come si verifica che una modifica non abbia rotto niente: sono le tre righe che ripagano da sole il tempo speso a scrivere il file, perché senza di esse l'agente prova la strada più comune e sbaglia quando il progetto ne usa un'altra.

Servono poi una descrizione del progetto in una frase, che dica a cosa serve e non com'è fatto, e il gestore di pacchetti quando non è quello standard del linguaggio. Vanno dichiarati anche gli strumenti non ovvi, del tipo che si scoprono solo sbagliando: un progetto Python che si aspetta uv e non pip, oppure un'applicazione Laravel dove ogni comando passa da vendor/bin/sail perché gira dentro container. Per il resto conviene puntare al codice invece di copiarlo, indicando file e riga dove sta l'esempio buono, così l'istruzione resta valida anche quando quel codice cambia.

Cosa non metterci dentro

L'albero delle cartelle, le convenzioni di formattazione e tutto quello che uno strumento automatico già impone. L'elenco delle directory invecchia nel giro di settimane e a quel punto lavora contro di te, perché un percorso sbagliato scritto con autorità manda l'agente a cercare file che non esistono più. Le regole di stile stanno nel linter e nel formattatore, che le applicano davvero, mentre scritte a parole restano un suggerimento che consuma spazio.

La sottrazione conta perché lo spazio è limitato. Philipp Schmid, che su philschmid.de ha raccolto le pratiche efficaci, indica come tetto le 300 righe e cita il caso di HumanLayer che tiene il proprio file sotto le 60, dato che il numero di istruzioni seguite con costanza da un modello di frontiera si aggira sulle 150 o 200 e una parte di quel budget è già spesa dall'infrastruttura dell'agente prima che tu scriva una parola. Da qui la diffidenza verso i file generati da un comando /init: producono pagine di riassunto del codebase che il modello può leggere da sé, occupano il budget con materiale ridondante e cominciano a invecchiare dal primo commit successivo.

Come si usa AGENTS.md con Claude Code

Claude Code non legge AGENTS.md, legge CLAUDE.md, e la documentazione di Anthropic non ha cambiato posizione su questo nemmeno nelle versioni uscite a luglio 2026. Le strade per non mantenere due file sono due, entrambe accettate ufficialmente. La prima è un collegamento simbolico, ln -s AGENTS.md CLAUDE.md nella radice del repository, che fa arrivare lo stesso contenuto a tutti e due i mondi. La seconda è tenere un CLAUDE.md minimo che importa l'altro file con la sintassi @AGENTS.md, utile quando ti servono anche istruzioni specifiche per quello strumento oltre a quelle condivise.

Quando il lavoro con Claude Code è già organizzato in skill e workflow, questo file resta il livello sotto: descrive il progetto una volta per tutte, mentre le skill descrivono i procedimenti da seguire. I due piani conviene tenerli separati, come raccontato nel bilancio di un anno di Claude Code e nel pezzo su come una skill trasforma una task in un workflow strutturato.

Come si gestisce in un monorepo

Con più file, uno per pacchetto, invece di uno enorme in cima. Gli agenti leggono il file più vicino nell'albero delle directory, quindi quello dentro packages/api ha la precedenza per chi lavora là dentro e riceve le istruzioni giuste senza portarsi dietro quelle del frontend. La radice tiene solo ciò che vale per tutti, ovvero lo scopo del monorepo e gli strumenti condivisi.

Le spiegazioni lunghe vanno in un documento a parte dentro docs, citato dal file principale, così l'agente lo apre quando gli serve invece di trascinarselo dietro a ogni richiesta. Lo stesso vale per il contesto che arriva già strutturato da un server MCP come quello descritto nel pezzo su Laravel Boost, perché lo schema del database e le versioni dei pacchetti le chiede l'agente quando gli servono. Sulla scelta dello strumento da mettere davanti a tutto questo resta utile il confronto tra le AI per programmare e i loro prezzi reali.

Domande frequenti su AGENTS.md

Dove va messo il file AGENTS.md? Nella radice del repository, allo stesso livello del README, perché è lì che tutti gli agenti lo cercano. In un monorepo ne puoi aggiungere uno dentro ogni pacchetto e vince quello più vicino al file su cui si sta lavorando.

Il file AGENTS.md sostituisce CLAUDE.md di Claude Code? Non lo sostituisce, perché Claude Code continua a leggere solo CLAUDE.md. Il modo pulito di averne uno solo è un collegamento simbolico con ln -s AGENTS.md CLAUDE.md, oppure un CLAUDE.md di due righe che importa l'altro con @AGENTS.md.

Quanto deve essere lungo il file di istruzioni per gli agenti? Il meno possibile, con 300 righe come tetto ragionevole e diversi progetti che restano sotto le 60. Ogni riga in più occupa contesto in ogni singola richiesta, quindi se non cambia il comportamento dell'agente sta togliendo spazio a qualcosa che lo cambierebbe.

Cursor legge AGENTS.md o serve ancora il suo file di regole? Cursor lo legge in modo nativo, come Copilot, Gemini CLI, Codex, Aider, Zed e Windsurf, quindi il file di regole proprietario serve solo per le impostazioni specifiche di quell'editor.