AGENTS.md si e' diffuso piu' in fretta di quasi ogni altra convenzione nel mondo degli agenti di coding. OpenAI lo ha pubblicato nell'agosto 2025 come formato aperto ed essenziale: un file markdown alla radice del repository, letto dall'agente prima di iniziare a lavorare. A dicembre 2025 e' stato donato alla Agentic AI Foundation della Linux Foundation, insieme al Model Context Protocol e a goose di Block, con OpenAI, Anthropic, Google e Block tutte dietro la stessa fondazione.
Cosa standardizza AGENTS.md, e perche' si e' diffuso cosi' in fretta
Il problema che AGENTS.md risolve e' circoscritto ed e' reale. Prima che esistesse, ogni agente di coding leggeva le istruzioni di progetto da dove il suo fornitore aveva deciso di cercarle, un file .cursorrules, un CLAUDE.md, una configurazione specifica dello strumento sepolta in una dotfolder. Un team che supportava piu' di un agente doveva duplicare gli stessi comandi di build, le stesse convenzioni di codice, le stesse istruzioni di test in tre o quattro formati diversi, e tenerli allineati a mano. AGENTS.md da' a ogni agente un unico posto prevedibile dove guardare, separato dal README che legge per primo una persona.
Basta questo a spiegare la curva di adozione. Il conteggio dello stesso sito agents.md parla di oltre 60.000 progetti open source e piu' di 20 strumenti supportati, tra cui Codex di OpenAI, Jules di Google, Cursor, Factory, Aider, VS Code, GitHub Copilot, Junie di JetBrains e Devin. Un formato che ogni fornitore importante di agenti legge gratis, senza alcun lock-in, era destinato a diffondersi. La donazione alla Linux Foundation formalizza cio' che era gia' vero nella pratica: e' l'unico formato di istruzioni che un team puo' scrivere una volta sola.
File di istruzioni contro registro di consegna: due lavori diversi
Ed e' qui che la copertura di AGENTS.md, quasi tutta scritta come notizia di adozione o guida su "come scrivere un buon AGENTS.md", confonde in silenzio due lavori che non hanno niente in comune. Un file AGENTS.md viene letto prima che l'agente inizi un task. Gli dice quale comando di test lanciare, quali cartelle non toccare, quali convenzioni segue il codebase. E' un input. Quando la sessione finisce, AGENTS.md non si e' mosso: dice ancora la stessa cosa che diceva prima che l'agente toccasse qualcosa, perche' descrive il progetto, non descrive la sessione.
Cio' che serve a un revisore dopo il fatto e' l'oggetto opposto: un registro di cosa e' effettivamente successo in quella specifica esecuzione, quali file sono cambiati, quali comandi sono stati eseguiti, quali delle istruzioni in AGENTS.md l'agente ha davvero seguito e quali ha silenziosamente ignorato. Il loop che produce l'output di un agente di coding, piano, modifica, esecuzione, verifica, genera esattamente questa informazione mentre gira. AGENTS.md non e' costruito per catturarla, e niente nel formato gliela chiede. Un AGENTS.md scritto benissimo e uno vuoto lasciano un team nella stessa posizione nel momento in cui qualcuno chiede cosa e' successo nella sessione di martedi' scorso: nessuno dei due file cambia.
Cosa non dicono i numeri di adozione
Sessantamila repository con un file AGENTS.md sono un segnale reale su quanti team hanno standardizzato le proprie istruzioni. Non dicono niente su quanti di quei team sappiano anche rispondere, per ogni singola modifica, a chi l'ha autorizzata, quale contesto l'agente era autorizzato a vedere, e quale prova esiste che il codice consegnato corrisponda a quanto richiesto. Sono domande diverse, e la seconda non diventa piu' facile da rispondere solo perche' la prima e' diventata piu' facile da porre.
Vale anche la pena essere onesti sul fatto che piu' istruzioni aiutino davvero. Uno studio dell'ETH di Zurigo, che valuta AGENTS.md e file di contesto simili a livello di repository su task SWE-bench e su un insieme separato di repository con file scritti davvero da sviluppatori, ha trovato che i file di contesto riducono il tasso di successo dei task rispetto a non dare all'agente alcun contesto di repository, aumentando allo stesso tempo il costo di inferenza di oltre il 20%. Il meccanismo che i ricercatori descrivono e' specifico: gli agenti seguono le istruzioni fedelmente, quindi quando un AGENTS.md dice loro di lanciare piu' test, leggere piu' file o cercare piu' a fondo, lo fanno esattamente, anche quando niente di tutto questo serve al task in questione. Non e' un argomento contro AGENTS.md. E' un motivo per tenerlo minimale, e un promemoria che un file costruito per orientare il comportamento non e' lo stesso oggetto di un file costruito per provare quale sia stato quel comportamento.
Perche' un AGENTS.md scritto bene puo' comunque non lasciare niente di dimostrabile
Prendi un team che fa tutto per bene: un AGENTS.md snello e curato, un agente che lo segue fedelmente, un task che finisce senza intoppi. Quel team non puo' comunque consegnare a un cliente, un revisore o una nuova assunzione un oggetto che dica, per questa specifica consegna, ecco il contesto autorizzato, ecco cosa e' girato, ecco chi ha revisionato, ecco la firma. AGENTS.md non era mai destinato a produrlo, perche' risponde a "cosa deve fare l'agente qui" una volta sola, all'inizio, per ogni sessione che girera' mai su questo repository. Non sa, e non ha un campo per saperlo, cosa e' effettivamente successo in una qualunque di quelle sessioni.
E' lo stesso spazio vuoto a cui gli hook di Claude Code si avvicinano senza chiuderlo del tutto: un hook puo' intercettare un'azione mentre succede, un passo avanti rispetto a ricostruirla dopo da una trascrizione, ma l'intercettazione non e' comunque un registro firmato legato a un task specifico e all'autorizzazione di una persona specifica. AGENTS.md sta un livello piu' indietro, a monte della sessione stessa. Avere il file di istruzioni giusto e' ormai il minimo indispensabile, non un elemento distintivo. Non era mai destinato a essere il livello che risponde alla domanda piu' difficile.
Cosa dovrebbe tenere una software house accanto al proprio AGENTS.md
Scrivi l'AGENTS.md, tienilo corto, e non aspettarti che faccia anche l'altro lavoro. Cio' che prova una consegna e' un artefatto separato: quale contesto l'agente era autorizzato a vedere per questo specifico task, cosa ha effettivamente fatto, e una firma umana sul risultato prima che parta, il livello che sta sopra l'agente, non dentro la sua configurazione. Un file di istruzioni standardizzato rende l'agente piu' facile da istruire. Non e' mai stato pensato per rendere la consegna piu' facile da provare, e trattarlo come se lo facesse e' il vuoto che un team scopre solo quando qualcuno pone la domanda a cui AGENTS.md non e' mai stato costruito per rispondere.