AGENTS.md: un solo file di contesto per ogni agente di coding (Codex, Antigravity, Claude)

Hai passato un pomeriggio a scrivere un CLAUDE.md pulito. Il tuo agente ha finalmente smesso di tirare a indovinare il tuo stack e ha iniziato a lanciare il comando di test giusto. Poi un collega apre lo stesso repo con Codex, tu provi Antigravity CLI su un branch a parte, e tutto quel contesto faticosamente conquistato non viene ereditato. Ogni tool vuole il suo file, nel suo posto.

AGENTS.md è la risposta a questo casino: un singolo file in puro Markdown, alla radice del repo, che qualsiasi agente di coding legge prima di toccare il tuo codice.

Cos'è davvero AGENTS.md

Nessuna magia. È un file Markdown chiamato AGENTS.md, di solito alla radice del repository, che un agente carica come istruzioni permanenti prima di mettersi al lavoro. Pensalo come il README che scrivi per i tuoi colleghi AI invece che per quelli umani: cos'è il progetto, come si builda e si testa, le convenzioni da rispettare e le trappole da evitare.

È una convenzione aperta, già letta da Codex e da una lista crescente di tool per agenti, pensata apposta per essere portabile tra di loro. Un file, tanti agenti, invece di un file su misura per ogni tool.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Quando questa guida è stata scritta, ogni tool cercava il proprio file. Da allora la maggior parte è convergita su AGENTS.md:

• Codex legge AGENTS.md, così come GitHub Copilot CLI, Cursor, Amp e la maggior parte degli agenti CLI più recenti.
• Claude Code legge CLAUDE.md, e dalla versione 2.1.277 legge anche AGENTS.md da solo quando la tua directory di lavoro e le directory sopra di essa non hanno né CLAUDE.md né CLAUDE.local.md. Quando esiste un CLAUDE.md, Claude legge solo quel file, a meno che tu non cambi l'impostazione Project instructions in /config.
• Antigravity CLI legge AGENTS.md o GEMINI.md, alla radice del repository o in qualsiasi sottodirectory, più una cartella .agents/rules/ e regole globali sotto ~/.gemini/.

Il contenuto è quasi identico in tutti e tre: contesto del progetto, comandi, convenzioni. Quello che cambia ancora è quale file sceglie un tool quando ne trova più di uno. È esattamente per questo che duplicare a mano le stesse regole in tre file è una battaglia persa in partenza (più sotto vediamo come tenerli sincronizzati). Abbiamo verificato questi comportamenti il 10 ottobre 2026 sulla documentazione della memoria di Claude Code e sulla documentazione delle regole di Antigravity.

Se lavori soprattutto in Claude Code, la nostra guida a CLAUDE.md entra a fondo nella struttura specifica di Claude. AGENTS.md è il cugino neutro di quel file, indipendente dal provider.

Cosa metterci dentro

Tienilo corto e ad alto segnale. Un agente lo legge a ogni task, quindi ogni riga si gioca l'attenzione. L'essenziale:

• Lo stack, in un fiato. "Next.js 16, TypeScript, Prisma, MariaDB." Niente storia, niente marketing.
• I comandi che contano. Come installare, avviare, buildare, testare e fare il lint. Comandi esatti: npm test, non "lancia i test".
• Le convenzioni. Naming, organizzazione dei file, gestione degli errori, i pattern che fai davvero rispettare in review.
• Una mappa delle cartelle. Due righe su dove vivono le cose, così l'agente smette di greppare alla cieca.
• Regole "leggi prima di toccare". "Leggi docs/payments.md prima di modificare qualsiasi cosa sotto billing/." Questa singola abitudine evita un sacco di danni.
• I divieti netti. "Non creare mai un branch senza che te lo chiedano." "Niente percorsi assoluti legati alla macchina nei file committati."

Gli errori che fanno ignorare il file agli agenti

Un file di contesto fallisce in silenzio. L'agente non lancia un errore, semplicemente va alla deriva. Le cause tipiche:

1. Troppo lungo. Un file da 600 righe seppellisce le cinque regole che contano. Taglia tutto ciò che l'agente può dedurre dal codice stesso.
2. Contraddizioni. "Scrivi sempre i test" in una sezione, "salta i test per i prototipi" in un'altra. L'agente ne sceglie una a caso.
3. Percorsi legati alla macchina. /Users/you/project/... in un file committato si rompe per ogni collega e per ogni agente su ogni altra macchina. Usa percorsi relativi.
4. Comandi obsoleti. Il comando di test è cambiato sei mesi fa, il file no. Adesso l'agente lancia la cosa sbagliata con assoluta sicurezza.
5. Nessuna priorità. Tutto è "importante", quindi niente lo è. Metti per primi i punti non negoziabili ed etichettali.
6. Scarico di documentazione. Queste sono istruzioni, non un wiki. Linka la tua doc, non incollarla dentro.

Tenere un solo contesto tra i provider

Ecco la parte pratica che la maggior parte delle guide salta. Se tu, o il tuo team, usate più di un agente CLI, non vuoi tre copie divergenti delle stesse regole.

Due approcci puliti:

• Un solo AGENTS.md, nient'altro. Se nessuno ha bisogno di regole solo per Claude, tieni un unico AGENTS.md: Codex, Antigravity CLI e Claude Code 2.1.277 o successivo lo leggono tutti. La trappola è silenziosa: un CLAUDE.md, o un CLAUDE.local.md personale, aggiunto più tardi fa sì che Claude Code smetta di leggere AGENTS.md.
• Un file canonico, un'importazione. Metti tutto in AGENTS.md e fai iniziare CLAUDE.md con la riga @AGENTS.md, poi scrivi sotto le regole solo per Claude. Claude legge prima il file importato. Il nostro stesso repository funziona così: il suo CLAUDE.md è quell'unica riga. Anche un collegamento simbolico (ln -s AGENTS.md CLAUDE.md) funziona, ma male su Windows, dove crearne uno richiede i privilegi di amministratore o la Modalità sviluppatore, e un clone senza core.symlinks riceve un file di testo di una riga al posto delle tue istruzioni.

In entrambi i casi la regola è la stessa: scrivi il contesto una volta, non una volta per provider. È anche l'unico modo per cui resta corretto, perché un singolo file è l'unico file che la gente mantiene davvero.

Quando lanci più agenti in parallelo

Un AGENTS.md a livello di repo risponde a "cos'è questo progetto". Non risponde a "chi è questo agente". Quando lanci un agente Backend, uno Frontend e uno QA in parallelo sullo stesso codice, ognuno ha bisogno del contesto di progetto condiviso più il proprio ruolo.

È questo lo strato che AgentsRoom aggiunge sopra il tuo AGENTS.md. Ogni agente riceve un ruolo dedicato con il suo system prompt (DevOps, Frontend, Security e altri), così il file condiviso resta snello mentre ogni agente sa comunque qual è il suo compito. È provider-agnostic per design, quindi lo stesso setup fa girare Claude, Codex o Antigravity fianco a fianco, e le tue istruzioni riutilizzabili vivono in una Prompt Library invece di essere ridigitate in ogni sessione.

Arrivato a quel punto, il metodo per far girare più agenti in parallelo senza perdere il filo è la lettura che segue naturalmente.

In sintesi

Scrivi un solo AGENTS.md. Tienilo corto, tienilo aggiornato, tienilo portabile. Punta ogni tool su quel file invece di mantenere un file per agente. Il tuo contesto smette di essere legato al CLI da cui hai cominciato per caso, e i tuoi agenti, qualunque siano, partono tutti dallo stesso punto.

Vuoi tutti i tuoi agenti su un solo schermo, ciascuno con il suo ruolo e il tuo contesto condiviso? Scarica AgentsRoom, collega il tuo provider e metti la tua flotta al lavoro.

Domande frequenti

Cos'è AGENTS.md?

Un file Markdown, di solito alla radice di un repository, che gli agenti di coding caricano come istruzioni permanenti prima di lavorare: cos'è il progetto, come compilarlo e testarlo, le convenzioni da rispettare e le trappole da evitare. È una convenzione aperta condivisa tra tool, non il file di un solo tool, letta da Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp e, dalla versione 2.1.277, da Claude Code.

Claude Code legge AGENTS.md?

Sì, da Claude Code 2.1.277, ma solo quando non c'è nessun CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md nella tua directory di lavoro o sopra di essa. In quel caso carica ogni AGENTS.md dalla directory di lavoro risalendo verso l'alto, e l'AGENTS.md di una sottodirectory quando apre un file lì dentro. Se esiste un CLAUDE.md, Claude legge solo quel file, a meno che tu non imposti Project instructions su claude-md-and-agents-md in /config. Sulle versioni precedenti, metti la riga @AGENTS.md in cima a un CLAUDE.md.

Antigravity usa AGENTS.md o GEMINI.md?

Entrambi. Antigravity legge un AGENTS.md, un GEMINI.md o una cartella .agents/rules/ alla radice del repository o in qualsiasi sottodirectory, e le regole globali da ~/.gemini/. Le regole si sommano invece di sostituirsi, e quando due di esse sono in conflitto vince la regola della directory più specifica.

Meglio tenere AGENTS.md o CLAUDE.md?

Tieni AGENTS.md come l'unico file che mantieni. Se ti servono anche regole solo per Claude, aggiungi un CLAUDE.md la cui prima riga sia @AGENTS.md e scrivi quelle regole sotto: Claude legge prima il file importato. Se non te ne servono, AGENTS.md da solo basta per Claude Code 2.1.277 o successivo. Evita due copie complete delle stesse regole: quella che nessuno modifica diventa obsoleta.

Dove va messo AGENTS.md?

Alla radice del repository per le regole che valgono ovunque. Claude Code e Antigravity leggono anche i file AGENTS.md nelle sottodirectory, quindi un package o un servizio con i propri comandi può avere il proprio file, letto quando l'agente lavora in quella cartella.