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 CLAUDE.md come adattatore per Claude Code.

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

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 CLAUDE.md, non AGENTS.md direttamente.
• 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 e farlo importare da CLAUDE.md. Anthropic documenta esplicitamente questo pattern per i repository che già usano AGENTS.md con altri agenti. Il vantaggio è semplice: modifichi una sola fonte, ma Claude Code continua a ricevere istruzioni native.

• Scrivi in AGENTS.md tutto ciò che vale per qualunque agente.
• Crea CLAUDE.md con import e una sezione breve per preferenze Claude-specific.
• 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 non mettere qui

Non tutto il contesto merita di entrare in AGENTS.md o CLAUDE.md. Se il contenuto è lungo, raro, procedurale o valido solo per un tipo di task, meglio spostarlo in documentazione, regole path-specific o skill. Il file di istruzioni deve restare breve abbastanza da essere letto e seguito.

• Non mettere guide lunghe che servono una volta ogni tanto.
• Non mettere tutorial completi, decision log storici o changelog.
• Non mettere segreti, token, URL privati o dati personali.
• Non mettere istruzioni contraddittorie tra root e sottocartelle.
• Per capacità riusabili, valuta una skill: è un livello diverso rispetto alle istruzioni di progetto.

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.

Domande frequenti