AGENTS.md e CLAUDE.md: perché il tuo progetto ha due file di istruzioni

AGENTS.md e CLAUDE.md sono la stessa cosa con due nomi diversi: un file di testo nella cartella del tuo progetto, che l’agente legge da solo all’inizio di ogni sessione. Dentro ci scrivi quello che altrimenti rispiegheresti ogni volta: come si avvia questo progetto, dove stanno le cose, cosa non va toccato. Da quel momento non lo rispieghi più.

Se hai già lavorato qualche giorno con un agente su una cartella tua, sai qual è il problema che risolve. La sessione di ieri è finita, e con lei tutto quello che gli avevi spiegato. Oggi riapri, e riparti da «allora, questo progetto funziona così». Il file serve a quello, e a niente di più magico di quello.

I due nomi invece hanno una storia, e vale la pena conoscerla perché è la storia di come si stanno formando gli standard di questo mestiere, mentre lo impariamo. Alla fine dell’articolo saprai anche quale dei due nomi ti conviene usare, che è una decisione che dipende da come lavori tu, non da quale agente preferisci.

Cos’è, in concreto

È un file Markdown, cioè testo semplice con qualche cancelletto per i titoli: se non hai presente, in Markdown: cos’è e perché è diventato la lingua dell’IA c’è tutto quello che serve e ci vogliono dieci minuti. Nessun formato speciale, nessun campo obbligatorio. La guida ufficiale di AGENTS.md è esplicita su questo punto: sono titoli che scegli tu, e l’agente legge il testo che ci trova.

Sta nella cartella principale del progetto, si chiama AGENTS.md o CLAUDE.md, e l’agente lo carica all’avvio senza che tu debba nominarlo. Non è una configurazione da imparare: è una pagina di appunti che qualcuno legge davvero.

La descrizione più utile che ho trovato è quella della documentazione di OpenAI, ed è anche il modo giusto di pensarci quando ti siedi a scriverlo: mettici quello che diresti a una persona che entra nel progetto oggi. Come si avvia, come si controlla che funzioni, quali sono le convenzioni della casa, e soprattutto le trappole, cioè le tre cose che sembrano giuste e che invece qui non si fanno.

C’è un file che gli somiglia e non è la stessa cosa, ed è il README. Quello è per le persone: cos’è il progetto, come si installa, come si contribuisce. Il file per gli agenti contiene il resto, cioè i dettagli operativi che in un README sarebbero rumore e che a un agente servono per non sbagliare.

Il file di questo sito

Il modo più rapido per capire cosa ci va dentro è guardarne uno vero. Questo è il file del progetto che stai leggendo: il sito del libro, con il blog. Ha settanta righe scarse, ed è diviso in sette sezioni.

Comincia così:

# Istruzioni per gli agenti

Questo file è la prima cosa da leggere quando si lavora in questo repo. Vale
per qualunque agente: `CLAUDE.md` è un collegamento a questo file, non una
copia, così non possono divergere.

Poi c’è la sezione che è il vero motivo per cui il file esiste. Si chiama Le due cose da non sbagliare, e la prima dice questo:

**Il testo del libro non si scrive qui.** La fonte è `manoscritto/`, dentro
questo repo ma non pubblicata. Quello che sta in `src/content/capitoli/` è una
copia generata da `npm run importa`: modificarla a mano vuol dire perdere il
lavoro alla prossima importazione. Se va corretto un capitolo, si corregge il
manoscritto.

Guarda cosa fa quella frase. I capitoli che vedi sul sito sono file generati da un altro file: se un agente ne corregge uno dove lo trova, la correzione funziona, sembra a posto, e sparisce alla prossima rigenerazione. È un errore che non si vede subito, cioè il tipo peggiore, e non è deducibile guardando il codice, perché le due copie sono identiche. Questo è il materiale di cui è fatto un buon file di istruzioni: non cosa fa il progetto, ma dove si inciampa.

Le altre sezioni sono la struttura delle cartelle, i comandi (npm run dev, npm run importa), come si scrive sul sito, e cosa controllare prima di pubblicare qualcosa.

La sezione che ho tolto per mostrartelo

Il file ne ha una settima, e non è qui sopra. Parla di un secondo progetto collegato, quello dove stanno i dati di analytics e le decisioni su cosa scrivere: dice dove si trova e che il piano editoriale vive lì.

Niente di segreto: nessuna chiave, nessun numero, nessun dato di nessuno. Dice solo dove sta una cosa. L’ho tolta per un motivo più banale, e lo scrivo perché prima o poi riguarda anche te: questo progetto regala già parecchio. Il libro si legge online per intero, gli articoli spiegano procedure che qualcuno vende. Fra il raccontare come lavoro e il consegnare il banco di lavoro già montato, a un certo punto una riga la tiri, e la tiri tu.

Te lo dico invece di mostrarti una versione ripulita facendola passare per l’originale, perché quella riga il giorno in cui qualcuno ti chiederà di vedere come lavori la dovrai decidere anche per il tuo file. E la parte interessante è quanto è stato facile: un taglio solo, una sezione intera, niente da oscurare riga per riga. Nessuna chiave da coprire, nessun numero, nessun piano. Da lì viene la regola che vale più di qualsiasi elenco di buone intenzioni:

Un file di istruzioni indica, non contiene. Dice dove sono le cose e come si fanno. Se ti accorgi che il tuo custodisce qualcosa, una password, un numero che non deve uscire, una strategia, quella roba è nel posto sbagliato, e il file te lo sta segnalando.

Perché i nomi sono due

Qui comincia la parte di storia, ed è breve.

Febbraio 2025. Anthropic pubblica Claude Code, un agente che lavora dentro il terminale. Il 24 febbraio è un’anteprima di ricerca, il 22 maggio diventa disponibile per tutti. Il file di istruzioni si chiama CLAUDE.md, e il nome dice tutto: è il file di Claude.

Agosto 2025. OpenAI pubblica AGENTS.md. Stessa idea, nome diverso, e la differenza è dichiarata fin dal principio: non è il file di Codex, è il file degli agenti. Un formato che chiunque può leggere, senza il nome di un prodotto sopra.

9 dicembre 2025. Ed è la data che racconta tutto il resto. Nasce la Agentic AI Foundation, un fondo dedicato ospitato dalla Linux Foundation. Non la Linux Foundation stessa, e la precisione qui conta: i progetti non sono stati consegnati alla fondazione, sono finiti in un fondo che quella ospita e governa in modo neutro. I progetti fondativi sono tre, e sono di tre aziende diverse:

Fra i membri fondatori e sostenitori ci sono, insieme, Anthropic, OpenAI, Google, Microsoft, AWS, Cloudflare e Bloomberg.

Vale la pena fermarsi un secondo su cosa significa. Due aziende che si fanno concorrenza diretta hanno messo i propri standard nella stessa casa neutra, lo stesso giorno. Un anno prima sarebbe stato difficile da immaginare. Se ti stavi chiedendo se questo mestiere sia cambiato negli ultimi dodici mesi, la risposta non è in una percentuale di adozione: è lì.

La conclusione facile, e perché è sbagliata

A questo punto la storia sembra scritta: il nome legato a un marchio perde, il nome neutro vince, CLAUDE.md è un residuo destinato a sparire.

Solo che non è andata così, e i fatti sono verificabili in due minuti.

Claude Code continua a leggere CLAUDE.md e non AGENTS.md. Non è un’interpretazione: la documentazione ufficiale lo scrive in una riga secca, e poi spiega come far convivere i due file. La richiesta di supporto nativo per AGENTS.md è aperta sul repository di Claude Code dal 21 agosto 2025 ed è la più votata di tutte: al 9 agosto 2026 ha 5.859 reazioni, di cui 4.530 pollici in su, e 347 commenti. È ancora aperta.

E i numeri di diffusione non dicono quello che ti aspetteresti. Cercando i due nomi fra i file dei progetti pubblici su GitHub, sempre il 9 agosto 2026:

Vanno letti con prudenza: sono file indicizzati e non progetti, il conteggio di GitHub è approssimato, e moltissimi progetti hanno tutti e due i file, questo compreso. Ma l’ordine di grandezza dice una cosa netta: nessun sorpasso, sono appaiati. Il terzo nome della lista è quello del file di Gemini, e serve a ricordare che nel frattempo ne sono nati altri.

Verrebbe da chiamarla una guerra fra due standard, come quella dei browser di fine anni Novanta, e per un pezzo il paragone tiene: due aziende, lo stesso lavoro fatto con nomi diversi, e chi scrive in mezzo. Ma la parte che non torna è quella che conta. Allora l’incompatibilità la pagavi tu, perché la stessa pagina andava scritta due volte e non c’era scorciatoia; qui il formato è lo stesso, il contenuto è lo stesso, cambia il nome del file, e la differenza si annulla con una riga che ti mostro fra poco. E la casa neutra, che allora arrivò dopo anni di macerie, stavolta l’hanno fondata insieme prima che i danni li facesse qualcuno.

Speriamo che finisca meglio, insomma. Anche perché quella storia lì si è risolta, ma non per generosità di qualcuno e non in fretta: il conto lo ha pagato per anni chi scriveva le pagine, e la via d’uscita è venuta dal basso, da chi si è rifiutato di fare il lavoro due volte. È lo stesso motivo per cui i due numeri qui sopra sono appaiati e non c’è un vincitore: non lo decide un annuncio, lo decide quello che la gente si ritrova nei propri progetti. Il tuo compreso.

Quindi cos’è successo davvero? Che ogni azienda ha regalato una cosa e se n’è tenuta un’altra. Anthropic ha donato il protocollo, cioè MCP, il meccanismo con cui un agente parla con gli strumenti esterni, e si è tenuta il nome del file. OpenAI ha donato il nome del file. Non è il marchio che perde: è che si standardizza il pezzo che conviene standardizzare, e la domanda interessante non è chi ha vinto, ma quale pezzo la tua cassetta degli attrezzi condivide con tutti e quale si tiene per sé.

Per te che stai per scriverne uno, la conseguenza è pratica e un po’ noiosa: nel 2026 i due file esistono entrambi, e ti conviene sapere quale ti serve.

Quale dei due ti serve

La domanda da farsi non riguarda il file. Riguarda te:

Su questo progetto lavora più di un agente?

Se hai Claude Code e basta, CLAUDE.md va benissimo e il resto è cerimonia. Scrivi quello, chiudi la questione e passa alla parte su cosa metterci dentro.

Se invece ci lavorano in due, Claude Code e Codex, oppure tu con uno e un collaboratore con un altro, allora il file vero si chiama AGENTS.md, perché lo leggono tutti, e a Claude Code si dà CLAUDE.md come rimando. Ci sono due modi, tutti e due documentati da Anthropic.

Il collegamento simbolico. Un file che non contiene niente e punta a un altro: il sistema lo tratta come se fosse quel file, ma esiste in una copia sola. È quello che ho fatto qui:

ln -s AGENTS.md CLAUDE.md

Il comando non stampa niente quando funziona. Da quel momento ls -l mostra la freccia, e si vede a occhio nudo che non sono due file:

-rw-r--r--   3880 byte   AGENTS.md
lrwxr-xr-x      9 byte   CLAUDE.md -> AGENTS.md

Guarda le due dimensioni, perché lì c’è tutto. Il file vero pesa quello che pesa. Il collegamento pesa nove byte, cioè le nove lettere di AGENTS.md: dentro non c’è il testo, c’è solo il nome dell’altro file. È un cartello.

Quando Claude Code apre CLAUDE.md, il sistema legge il cartello, va a prendere l’altro file e gli passa quelle righe. Claude Code non si accorge di niente e non deve saperlo. Tu scrivi una volta sola, ogni agente apre il nome che si aspetta, e il testo resta uno.

Il file va tenuto insieme al progetto, cioè dentro Git, ed è il punto: serve proprio perché vale per chiunque apra quella cartella, te compreso fra tre mesi. Il collegamento viene registrato come collegamento e non come copia, così chi si scarica il progetto se lo ritrova già fatto senza dover rifare niente.

Un modo di romperlo però c’è, e conviene conoscerlo. Certi programmi, quando salvano, non riscrivono il file ma ne creano uno nuovo e lo mettono al posto del vecchio: in quel caso il cartello sparisce e al suo posto resta un file vero, cioè di nuovo due copie. Si controlla in un secondo, e vale la pena farlo la prima volta che l’agente tocca quel file: rilanci ls -l e guardi se la freccia c’è ancora.

L’inclusione. Se ti serve anche scrivere qualcosa solo per Claude Code, il collegamento non basta e si usa l’altra strada: un CLAUDE.md vero che tira dentro l’altro file e poi aggiunge il suo pezzo.

@AGENTS.md

## Claude Code

Usa la modalità piano per le modifiche sotto `src/pagamenti/`.

Su Windows il collegamento simbolico richiede privilegi da amministratore, e la documentazione consiglia direttamente l’inclusione.

Quello che non va fatto, ed è l’unico vero errore possibile qui, è tenerne due copie con lo stesso contenuto. All’inizio sono identiche. Poi correggi una cosa in una e non nell’altra, e da quel momento hai due agenti che lavorano sullo stesso progetto seguendo istruzioni diverse. Te ne accorgi settimane dopo, quando uno dei due fa una cosa che l’altro non farebbe mai, e non hai idea del perché.

Il file lo scrive l’agente

Adesso la parte pratica, e la buona notizia è che non devi scriverlo tu da zero. Sia Claude Code sia Codex hanno un comando che lo genera guardando il progetto: si chiama /init in tutti e due, si scrive nella conversazione, e produce un file di partenza basato su cosa trova nella cartella.

Le documentazioni di entrambe le aziende dicono la stessa cosa su quel risultato, e conviene prenderla sul serio: è un punto di partenza, non un file finito. Quello che esce descrive bene il progetto e conosce male il tuo modo di lavorarci, che è precisamente la parte che serve.

Quindi il lavoro tuo non è scrivere, è dire cosa scrivere e controllare cosa è uscito. Questa è la richiesta da dare all’agente, adattandola al tuo caso:

Genera il file di istruzioni per questo progetto.

Prima dimmi come lo chiamerai e perché: qui ci lavora anche un altro
agente, quindi voglio capire se conviene AGENTS.md con un rimando o un
file solo.

Regole per il contenuto:
- niente che tu possa ricavare da solo leggendo la cartella: non voglio
  l'albero delle directory, l'elenco delle dipendenze o una panoramica
  dell'architettura;
- voglio le trappole, i motivi e le convenzioni che si discostano da
  quello che faresti di default;
- istruzioni concrete e verificabili, non principi generali;
- niente chiavi, password, dati di clienti o numeri riservati;
- sotto le duecento righe.

Prima di scrivere il file, elencami cosa hai intenzione di metterci e
fermati: voglio togliere delle cose prima che tu lo crei.

Le clausole che contano sono tre, e valgono per qualunque cosa deleghi, non solo per questo file.

«Niente che tu possa ricavare da solo». È il criterio più utile che esista per questo file, e non me lo sono inventato: viene da /doctor, un comando di Claude Code che legge un file di istruzioni già scritto e ti dice quali parti converrebbe togliere. Non cancella niente da solo, propone e decidi tu.

Le parti che propone di togliere sono sempre le stesse: l’elenco delle cartelle, l’elenco delle librerie usate e i riassunti di come è fatto il progetto. Cioè le cose che l’agente vede da sé aprendo la cartella. Quelle che tiene sono le trappole, i motivi di una scelta e le abitudini di casa che si discostano da quello che farebbe di suo. Se un file ce l’hai già, è il modo più rapido per accorciarlo.

«Istruzioni concrete e verificabili». «Scrivi codice pulito» non dice niente a nessuno. «Esegui npm run lint prima di ogni commit» si può controllare. Su questo la documentazione di Anthropic e quella di OpenAI dicono quasi le stesse parole, il che è un buon segno che il consiglio non dipenda da quale agente usi.

«Elencami cosa hai intenzione di metterci e fermati». È la clausola che trasforma la generazione in una conversazione. Il momento buono per togliere roba è prima che il file esista, non dopo: dopo, guardare un file già scritto e decidere di accorciarlo costa fatica e non lo fa quasi nessuno.

E poi lo rileggi. Non è una formalità: è l’unica parte che non si delega, perché tu sai cose sul tuo progetto che l’agente non può sapere. Cerca tre cose: quello che sarebbe stato ovvio anche senza scriverlo, quello che è scritto in modo troppo vago per essere seguito, e quello che non deve uscire di casa.

Cosa non ci va

Tre cose, e la terza è quella che delude quasi tutti.

Quello che si deduce. Già detto sopra, ma è la metà del volume dei file che si trovano in giro: sezioni che elencano le cartelle e le librerie usate. L’agente quelle le vede.

Quello che non deve uscire. Chiavi, password, dati di clienti, numeri riservati. Un file di istruzioni finisce nel controllo versione, viene letto da chiunque apra il progetto, e in certi casi viene condiviso senza pensarci. Vale la regola di prima: indica, non contiene.

Le cose che devono succedere sempre. Ed è il punto delicato. Il file non è un regolamento: la documentazione di Anthropic è netta, quel contenuto è contesto, non configurazione applicata. L’agente lo legge e prova a seguirlo, ma non c’è nessun meccanismo che glielo imponga, e un’istruzione vaga o in conflitto con un’altra viene seguita male, o non viene seguita.

Quindi se una cosa deve accadere per forza, come un controllo prima di ogni salvataggio o un blocco su una cartella intera, quella non si scrive nel file. Si mette in un hook, cioè un comando che il programma esegue automaticamente in un momento preciso, che scatta a prescindere da cosa decide l’agente. Scriverla nel file e considerarla garantita è il modo più comune di restare delusi da questo strumento.

Un’ultima cosa che aiuta nei progetti grandi: i file si annidano. Puoi metterne uno nella cartella principale e altri nelle sottocartelle, e vale il più vicino al file su cui si sta lavorando. Se hai una cartella con regole tutte sue, il posto giusto delle sue regole è dentro quella cartella, non nel file principale che si allunga.

Domande frequenti

Se uso solo Claude Code, AGENTS.md mi serve?

No. Scrivi CLAUDE.md e non pensarci più. La domanda torna utile il giorno in cui apri quel progetto con un altro agente, o lo passi a qualcuno che ne usa un altro, e quel giorno non devi imparare niente: chiedi al tuo agente di rinominare il file in AGENTS.md e di lasciare al suo posto un collegamento che punti lì. È il lavoro di un minuto, ed è il meccanismo spiegato sopra: il comando te l’ho mostrato per farti capire cosa succede, non perché tu debba impararlo a memoria.

Ho già un AGENTS.md, devo riscriverlo per Claude Code?

No, e sarebbe l’errore. Metti il collegamento o l’inclusione, e resta un file solo. Claude Code ha anche un comando /import che porta dentro la configurazione di un altro agente, ma fa una copia una tantum: è comodo per traslocare, non per tenere allineate due cose.

Quanto deve essere lungo?

Anthropic indica sotto le duecento righe, e le ragioni sono due. La prima è che quel testo occupa spazio nella memoria di lavoro dell’agente, e lo occupa all’avvio: lo paghi prima ancora di avere chiesto qualcosa, e lo ripaghi ogni volta che riapri il progetto. La seconda è che più è lungo, più le istruzioni che contano si perdono in mezzo alle altre.

Se il tuo cresce, il segnale non è che serve un file più grande: è che una parte va spostata altrove, in un file di regole legato a una sottocartella o in una procedura separata.

L’agente lo legge davvero, o fa finta?

Lo legge, all’inizio di ogni sessione. Ma «legge» non vuol dire «obbedisce»: vale quello che c’è scritto sopra, è contesto e non una regola applicata. Se un’istruzione viene ignorata di continuo, quasi sempre è scritta in modo troppo vago, oppure ce n’è un’altra da qualche parte che dice il contrario.

E GEMINI.md?

È lo stesso meccanismo per lo strumento da terminale di Google, ed è molto meno diffuso degli altri due. Se un giorno ti serve, la logica non cambia: un file vero, gli altri che ci puntano.

Da dove continuare

Se non hai ancora un progetto tuo su cui provare tutto questo, il capitolo 5 parte esattamente da lì: una cartella vuota, un obiettivo piccolo, e un agente a cui spiegare cosa stai facendo.

Se invece hai già visto una modifica sparire senza capire perché, come nel caso dei file generati di cui parla questa pagina, il capitolo 6 è dedicato agli errori che non si vedono, che sono quelli che costano.

Puoi anche iscriverti agli aggiornamenti per ricevere i prossimi articoli.

Fonti ufficiali

• AGENTS.md, il formato
• Claude Code: i file di memoria e la sezione su AGENTS.md
• Codex CLI, documentazione OpenAI
• Linux Foundation: nascita della Agentic AI Foundation
• Anthropic: la donazione del Model Context Protocol
• La richiesta di supporto ad AGENTS.md in Claude Code