AGENTS.md: un solo file di contesto per ogni agente di coding (Codex, Gemini, 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 Gemini 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

Al momento il panorama è frammentato per tool:

• CLAUDE.md è quello che cerca Claude Code.
• GEMINI.md è la convenzione di Gemini CLI.
• AGENTS.md è lo standard trasversale, letto da Codex e da altri, progettato per essere quello neutro.

Il contenuto è quasi identico in tutti e tre: contesto del progetto, comandi, convenzioni. L'unica vera differenza è il nome del file che ogni tool legge di default. È esattamente per questo che duplicare a mano le stesse regole in tre file è una battaglia persa in partenza (più sotto vediamo come tenerli sincronizzati).

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 file canonico, puntatori sottili. Metti tutto in AGENTS.md e rendi CLAUDE.md e GEMINI.md file di una riga che dicono "vedi AGENTS.md", oppure usa dei symlink. Una sola fonte di verità, tutti i tool serviti.
• Un file, condiviso per convenzione. Se i tuoi tool possono puntare a un percorso personalizzato, indirizzali tutti su AGENTS.md e cancella il resto.

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 Gemini 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.