CLAUDE.md o AGENTS.md: dove mettere le istruzioni per il tuo agente

Cosa sono CLAUDE.md e AGENTS.md

Sono file di istruzioni per agenti AI che lavorano sul codice. Invece di spiegare ogni volta come installare il progetto, quali test eseguire o quali file evitare, scrivi queste regole in un Markdown dentro il repository. L'agente lo legge all'inizio o quando entra in una sottocartella e usa quel contesto per lavorare con meno tentativi a vuoto.

• CLAUDE.md è il file nativo di Claude Code: contiene memoria e regole specifiche per Claude.
• AGENTS.md è una convenzione più portabile: funziona come manuale operativo per più agenti di coding.
• Entrambi servono a ridurre errori ripetuti, comandi sbagliati e istruzioni perse nelle chat.
• Non sono documentazione per utenti finali: sono istruzioni operative per software agent.

La decisione in una frase

Se il repository deve parlare a un solo agente, usa il file nativo di quell'agente. Se deve parlare a più agenti, crea una fonte comune. Per i team che usano Claude Code insieme a Codex, Copilot, Cursor o Zed, la fonte comune più pratica è AGENTS.md, con un CLAUDE.md di raccordo solo se Claude Code ha bisogno di regole in più.

• AGENTS.md contiene regole condivise: comandi, test, stile, architettura, limiti e workflow.
• CLAUDE.md contiene solo ciò che Claude Code deve sapere in più o in modo diverso.
• Quando una regola vale per tutti, non copiarla in due file: spostala in AGENTS.md.

Vuoi aggiungere un agente open source? Quando conviene Pi Agent accanto a Claude Code e Codex

Cosa cambia tra CLAUDE.md e AGENTS.md

CLAUDE.md è il meccanismo nativo di Claude Code per istruzioni persistenti. La documentazione Anthropic descrive scope diversi, file locali, caricamento nella gerarchia e import con @path. AGENTS.md nasce invece come formato aperto e prevedibile per i coding agent: un README per agenti, non per esseri umani.

• Claude Code legge AGENTS.md da solo dalla versione 2.1.277, ma solo se nella cartella di lavoro e in quelle sopra non trova CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md.
• Codex legge AGENTS.md prima di lavorare e costruisce una catena di istruzioni globali e di progetto.
• GitHub Copilot documenta AGENTS.md come istruzioni per agenti, accanto ai file .github/copilot-instructions.md.
• Zed supporta più nomi compatibili per regole di progetto, inclusi AGENTS.md e CLAUDE.md.

Il setup che evita duplicazioni

La soluzione operativa è rendere AGENTS.md il file canonico. Se non hai regole solo per Claude Code, non ti serve altro: Claude Code legge AGENTS.md quando nel progetto non c'è un CLAUDE.md. Se invece crei un CLAUDE.md, Claude Code legge quello al posto di AGENTS.md, quindi la prima riga deve importarlo. Anthropic documenta questo pattern e conferma che l'import non fa leggere AGENTS.md due volte.

• Scrivi in AGENTS.md tutto ciò che vale per qualunque agente.
• Crea CLAUDE.md solo se ti servono preferenze Claude-specific, con @AGENTS.md in testa.
• Se hai già un CLAUDE.md con @AGENTS.md puoi lasciarlo: copre anche le sessioni in cui Claude Code legge solo CLAUDE.md, per esempio, in alcuni casi, la prima dopo un aggiornamento da una versione precedente alla 2.1.277.
• Per leggere sempre entrambi i file senza import, imposta Project instructions su claude-md-and-agents-md in /config.
• Evita symlink se lavori anche su Windows: l'import @AGENTS.md è più portabile.
• Rivedi periodicamente i file annidati per rimuovere regole vecchie o contraddittorie.

# CLAUDE.md
@AGENTS.md

## Claude Code

- Usa plan mode prima di modifiche in src/billing o src/auth.
- Per task lunghi, proponi prima un /goal con criteri di successo e comando di verifica.
- Se una regola comune cambia, aggiorna AGENTS.md invece di duplicarla qui.

Cosa mettere nei file di istruzioni

Questi file devono ridurre esplorazione inutile e fallimenti ripetuti. Non devono diventare una wiki completa del progetto. Scrivi ciò che un agente deve sapere in quasi ogni sessione: come installare, testare, orientarsi, rispettare vincoli e consegnare lavoro verificabile.

• Comandi validati: install, dev server, build, test, typecheck, lint.
• Struttura del progetto: dove vivono dati, route, componenti, test e script generati.
• Regole non negoziabili: file da non modificare, standard editoriali, sicurezza, privacy.
• Workflow di consegna: controlli finali, formato summary, divieti su commit o push se applicabili.
• Esempi concreti di errori già visti e come evitarli.

Cosa tenere fuori e dove metterlo

Il file di istruzioni viene caricato a ogni sessione: ogni riga ha un costo fisso. Guide lunghe, tutorial, changelog e procedure valide per un solo tipo di task vanno altrove. Per decidere dove, chiediti quanto spesso serve un'informazione e quanto resta stabile.

• AGENTS.md o CLAUDE.md: fatti validi in quasi ogni sessione, come comandi, struttura e divieti.
• Regole per cartella: in Claude Code, CLAUDE.md nelle sottocartelle o regole in .claude/rules/ legate a percorsi, caricate solo quando l'agente lavora su quei file.
• Spec del task: obiettivo, non-obiettivi, decisioni e verifiche. Ti permette di chiudere una chat piena di tentativi e ripartire senza perdere niente.
• Memoria automatica: Claude Code salva da solo correzioni e preferenze in una cartella locale per repository. Non è condivisa con il team, quindi le regole comuni restano in AGENTS.md.
• Skill: procedure ripetute. Claude Code e Codex caricano all'inizio solo nome e descrizione e leggono il resto quando serve.
• Subagent: test, log e ricerche che producono molto output. Lavorano in un contesto separato e restituiscono una sintesi.
• Script: passaggi meccanici e stabili, che non serve più far ragionare all'agente in linguaggio naturale.
• Da nessuna parte: segreti, token, URL privati e dati personali non vanno in nessun file letto dall'agente.

Quando una procedura ripetuta merita una skill?

Errori comuni

Quasi tutti i problemi di contesto nascono da un'informazione messa nel posto sbagliato. Questi sono i casi più frequenti.

• Tutto nella chat: ripeti le stesse regole a ogni sessione e le perdi quando ricominci.
• Tutto nel file di istruzioni: più cresce, più contesto consuma e meno l'agente lo segue.
• Import per accorciare il file: @path lo rende più ordinato, ma il testo importato entra comunque nel contesto.
• Regole critiche affidate solo al testo: Claude Code tratta CLAUDE.md come contesto, non come vincolo. Per bloccare davvero un'azione serve un hook.
• Log ed esplorazioni nella chat principale: le decisioni utili finiscono sepolte sotto output che non rileggerai.
• Subagent in parallelo sugli stessi file: più agenti che modificano codice insieme creano conflitti. Usali per letture, test e ricerche.

Come collegarlo al lavoro agentico

Un buon file di istruzioni non sostituisce un buon task. Serve a dare al coding agent una base costante; poi, per lavori lunghi, devi comunque scrivere obiettivo, scope e verifiche. È lo stesso principio del comando /goal: il contesto spiega come lavorare, il goal spiega quando fermarsi.

• Metti in AGENTS.md i comandi che l'agente deve conoscere sempre.
• Nel prompt o in /goal indica risultato atteso, file coinvolti, vincoli e test da eseguire.
• Quando una correzione si ripete in più sessioni, promuovila dal prompt al file di istruzioni.
• Quando una procedura diventa lunga e riusabile, promuovila dal file di istruzioni a una skill o a una guida dedicata.