CLAUDE.md e AGENTS.md: cosa scriverci, e cosa non ci va

Se usi più di un agente di programmazione, prima o poi nel repository ti ritrovi un CLAUDE.md e un AGENTS.md che dicono quasi la stessa cosa. E nessuno ricorda quale dei due è aggiornato.

In breve: Claude Code legge CLAUDE.md, Codex legge AGENTS.md, e puoi tenere un solo set di istruzioni per tutti e due. La risposta lunga riguarda soprattutto cosa lasciare fuori, perché è lì che questi file si guastano. Il nostro compreso, come vedrai.

Chi legge cosa

Claude Code legge CLAUDE.md, non AGENTS.md. Carica questi file, dal più generale al più specifico:

I file nelle cartelle sopra quella da cui lo avvii si caricano subito, quelli nelle sottocartelle quando Claude ci lavora dentro. Nessuno sostituisce gli altri: si accodano, e il più vicino alla cartella di lavoro viene letto per ultimo. Le regole si possono anche dividere in .claude/rules/, limitandone alcune a certi percorsi.

Codex legge AGENTS.md. Parte da quello globale in ~/.codex/, poi prende un file per cartella dalla radice del repository git fino a dove stai lavorando. I file più vicini arrivano dopo, quindi vincono. Un AGENTS.override.md sostituisce l'AGENTS.md della stessa cartella. Di default Codex smette di leggere a 32 KiB di istruzioni complessive (l'impostazione è project_doc_max_bytes).

AGENTS.md è un formato aperto che leggono anche tanti altri agenti, e per questo conviene farne la fonte.

Un solo set di istruzioni per tutti e due

Scrivi le istruzioni in AGENTS.md e fai in modo che CLAUDE.md lo importi. Claude Code supporta le importazioni con @:

@AGENTS.md

## Solo per Claude Code

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

Il file importato si carica per primo, e quello che scrivi sotto vale solo per Claude. Se non c'è niente di specifico da aggiungere basta un collegamento simbolico (ln -s AGENTS.md CLAUDE.md). Su Windows l'importazione dà meno problemi.

Poi controlla cosa è stato caricato davvero. In Claude Code lancia /context e guarda sotto Memory files. A Codex chiedi di riassumere le sue istruzioni: codex --ask-for-approval never "Summarize the current instructions.".

Cosa scriverci

Tutti e due i file si leggono all'inizio di ogni sessione e consumano contesto ogni volta. Anthropic consiglia di restare sotto le 200 righe per file, perché più il file cresce e meno viene rispettato.

E qui c'è la parte imbarazzante. Il CLAUDE.md del repository di Cobrain è lungo 51 righe, ben sotto quel limite, e pesa 43 KB: ogni riga è un paragrafo. Sono più dei 32 KiB di default di Codex, che quindi si fermerebbe a metà. Contare le righe era la misura sbagliata. Conta il peso.

Quello che si guadagna il posto:

• i comandi, esattamente come li scriveresti: installare, compilare, lanciare test e lint;
• le convenzioni diverse dal solito, tipo «usiamo pnpm, non npm» o «le date si salvano in UTC»;
• le trappole, cioè quello che si rompe ogni volta che il codice lo tocca qualcuno di nuovo, con il perché, così l'agente riconosce il caso anche quando si presenta un po' diverso;
• le regole ferme, dette in concreto: «mai committare con git add -A», «le migrazioni vanno in supabase/migrations/».

Le istruzioni specifiche vengono seguite. «Lancia npm test prima di committare» funziona, «assicurati che il codice funzioni» no.

Cosa non ci va

Quello che il codice dice già. Alberi delle cartelle, elenchi di dipendenze e panoramiche dell'architettura invecchiano, e l'agente può leggere direttamente l'originale.

Le procedure lunghe. Una checklist di rilascio in dieci passaggi che serve due volte al mese sta meglio in una skill o in uno script che si carica quando serve.

I segreti, mai. Questi file finiscono nel repository e li leggono strumenti che non controlli.

Quello che deve succedere per forza. Le istruzioni sono contesto, e il modello il contesto lo può ignorare. Se una cosa va bloccata ogni volta, serve un hook o una regola di permesso.

E la conoscenza del progetto: cosa ha deciso il cliente, perché una funzione è stata abbandonata, a chi chiedere della fatturazione, a che punto sono i lavori. Cambia ogni settimana, interessa a persone che il repository non lo aprono mai, e le AI che ne hanno più bisogno, quelle nelle app di chat, il repository non lo leggono. A essere sinceri, è proprio questo che ha gonfiato il nostro file.

Dove va la conoscenza del progetto

Claude Code un posto per quello che impara ce l'ha. La memoria automatica scrive appunti in una cartella sul tuo computer, con un indice MEMORY.md di cui a ogni sessione si caricano le prime 200 righe (o 25 KB). Aiuta. Però è locale: non ti segue su un altro computer, i colleghi non la vedono mai e Codex non la legge.

Per un team funziona una base di conoscenza fuori dal repository, che ogni agente raggiunge via MCP. Claude Code e Codex supportano MCP, e lo stesso vale per le app di chat. Nel file di istruzioni basta una sezione corta che ci rimanda:

## Conoscenza del progetto

Prima di iniziare chiama `start_session` per questo progetto sul connettore Cobrain
e leggi le ultime decisioni. Le decisioni nuove si scrivono lì, non in questo file.

AGENTS.md resta corto e cambia di rado, perché spiega solo come si lavora in questo codice. Quello che cambia davvero, cosa si è deciso e perché, sta in note che Claude Code, Codex, Claude e ChatGPT leggono e scrivono tutti, e che un collega apre senza clonare niente.

È il mestiere di Cobrain. Il collegamento è nelle guide per Claude Code e per Codex, e in costi di contesto c'è perché caricare meno dà risposte migliori.

Domande rapide

Claude Code legge AGENTS.md? Da solo no. Aggiungi un CLAUDE.md che contiene @AGENTS.md, oppure collega l'uno all'altro con un link simbolico.

Posso tenere tutti e due i file? Sì, purché uno sia la fonte e l'altro lo importi. Due file modificati a mano divergono nel giro di qualche settimana.

Quanto deve essere lungo CLAUDE.md? Anthropic consiglia meno di 200 righe, e tieni d'occhio anche il peso in byte. Se cresce, sposta le regole legate a certi percorsi in .claude/rules/ e le procedure nelle skill.

Dove deve tenere l'AI quello che impara sul progetto? In una memoria, non nel file di istruzioni. La memoria automatica di Claude Code va bene se riguarda solo te su questo computer. Se serve al team o alle altre AI, usa una memoria condivisa raggiungibile via MCP.