CLAUDE.md vs AGENTS.md:quale agente legge quale file.

Cos'è ciascun file

Sono entrambi Markdown semplice che un agente carica nel suo contesto all'inizio di una sessione. Ci scrivi comandi di build e di test, stile del codice, struttura del progetto e regole come "non modificare mai i file generati". Sono istruzioni, non impostazioni imposte: l'agente le tratta come indicazioni.

• CLAUDE.md è specifico di Claude Code. Può stare nella radice del progetto (./CLAUDE.md o ./.claude/CLAUDE.md), in ~/.claude/CLAUDE.md per tutti i tuoi progetti e nelle sottocartelle. Un CLAUDE.local.md contiene note private per un progetto.
• AGENTS.md è un formato aperto descritto su agents.md, un README per gli agenti. Lo leggono Codex, Cursor, l'agente di coding di GitHub Copilot, Gemini CLI, Zed e molti altri. In un monorepo, un AGENTS.md in una sottocartella vale per quella parte, e vince il file più vicino.

Il contenuto è dello stesso tipo. Cambia lo strumento che raccoglie il file.

Cosa fa Claude Code con AGENTS.md

La documentazione di Claude Code descrive tre casi, per la versione 2.1.277 o successive:

• Solo un AGENTS.md nel progetto, nessun CLAUDE.md: Claude Code legge l'AGENTS.md.
• Entrambi i file nel progetto: Claude Code legge solo i file CLAUDE.md.
• Un CLAUDE.md che importa AGENTS.md con @AGENTS.md: Claude legge il CLAUDE.md con AGENTS.md incluso.

Il secondo caso è quello che sorprende. Se aggiungi un CLAUDE.md, anche minuscolo, a un repository che ha un AGENTS.md, Claude smette di leggere l'AGENTS.md a meno che il CLAUDE.md non lo importi. Lo stesso vale per un CLAUDE.local.md. Le versioni più vecchie di Claude Code leggevano solo CLAUDE.md, ed è per questo che l'importazione resta la scelta sicura. La documentazione descrive anche un'impostazione Project instructions in /config per far leggere a Claude entrambi i file insieme.

Mantenere un solo insieme di istruzioni

Scegli un file come fonte di verità. Sono documentati due modi:

1. Importare AGENTS.md da CLAUDE.md

   Crea un CLAUDE.md accanto ad AGENTS.md la cui prima riga sia @AGENTS.md, poi aggiungi sotto le istruzioni solo per Claude. Le importazioni usano la sintassi @percorso, i percorsi relativi si risolvono a partire dal file che li contiene e i file importati possono importarne altri fino a quattro livelli di profondità.

2. Collegamento simbolico da CLAUDE.md a AGENTS.md

   Esegui ln -s AGENTS.md CLAUDE.md se non hai nulla di specifico per Claude da aggiungere. La documentazione avverte che gli strumenti di modifica di Claude non scrivono attraverso un collegamento simbolico, e che su Windows un collegamento simbolico nel commit può essere estratto come file di testo di una riga, quindi l'importazione è la scelta più sicura per un repository condiviso.

Evita un terzo approccio: un CLAUDE.md che dice "leggi AGENTS.md" a parole. Claude vede il file solo se decide di aprirlo, mentre un'importazione lo carica ogni volta.

Un AGENTS.md condiviso

Metti in AGENTS.md ciò che serve a qualsiasi agente:

# AGENTS.md

## Commands
- Install: `npm ci`
- Test: `npm test`
- Lint: `npm run lint`

## Conventions
- TypeScript, strict mode. No default exports.
- Update the tests with every change.

## Do not
- Edit files under `generated/`.
- Commit without running the tests.

Mantienilo breve e specifico. La documentazione di Claude Code suggerisce di restare sotto circa 200 righe per CLAUDE.md, perché i file più lunghi costano contesto e vengono seguiti con meno affidabilità.

Errori comuni

• Due file che si allontanano. Una copia viene aggiornata, l'altra no. Usa l'importazione.
• Aggiungere un CLAUDE.md e perdere l'AGENTS.md. Vedi sopra: importalo.
• Mettere segreti in uno dei due file. Vengono inseriti nel commit e caricati in ogni sessione.
• Regole vaghe. "Scrivi codice pulito" non serve a nulla. "Esegui npm test prima di dire che hai finito" sì.
• Regole contraddittorie tra il file di una cartella superiore e quello di una sottocartella.

Leggere e rivedere questi file

Sono entrambi normale Markdown, quindi DotMD apre CLAUDE.md e AGENTS.md come qualsiasi file .md, con un indice e la cronologia di ogni modifica, e mostra cosa ci ha cambiato un agente. La lettura è gratuita. Vedi anche Claude Code e Codex con DotMD.

Domande su CLAUDE.md e AGENTS.md

Altre domande