Claude Code ora legge AGENTS.md: CLAUDE.md e AGENTS.md a confronto e la directory .claude

Che cos’è claude.md e cosa dovresti inserirvi?

CLAUDE.md è un file Markdown di testo semplice contenente istruzioni che Claude Code carica nel contesto della sessione. Ti offre uno spazio in cui registrare informazioni che altrimenti dovresti ripetere: comandi di compilazione e test, convenzioni di programmazione, architettura del progetto e regole del flusso di lavoro.

Non è richiesto alcun formato specifico per il documento. Puoi organizzarlo con normali titoli ed elenchi Markdown, scegliendo la struttura che rende facili da comprendere le istruzioni del tuo progetto. Di Claude Code /init Il comando genera un file iniziale basato sul progetto, come descritto nella documentazione ufficiale sulle buone pratiche.

Un utile punto di partenza è trattare quattro aree:

• Comandi di compilazione e test: i comandi che i collaboratori devono usare per compilare il progetto e verificare le modifiche.
• Convenzioni di codice: denominazione, formattazione e altre convenzioni pertinenti al repository.
• Architettura del progetto: i componenti principali e il modo in cui si integrano.
• Regole del flusso di lavoro: i passaggi che vuoi che Claude segua quando apporta e verifica modifiche.

Considerale indicazioni persistenti. Le istruzioni entrano nel contesto di Claude; non sono una configurazione applicata automaticamente. Se devi configurare Claude Code stesso, usa il file di impostazioni appropriato invece di aspettarti che il testo in CLAUDE.md funzioni come valore di un'impostazione.

La distinzione è importante quando si organizza un repository: le informazioni sul progetto vanno nei file di istruzioni, mentre la configurazione dell'applicazione va nelle impostazioni. Il centro delle guide di Claude Code offre un punto di partenza per il flusso di lavoro nel suo complesso.

Dove collocare CLAUDE.md

Claude Code supporta istruzioni di progetto condivise e istruzioni personali in diverse posizioni. La documentazione sui file di istruzioni descrive queste posizioni consolidate e il funzionamento dell'individuazione delle istruzioni.

I file di istruzioni nelle directory superiori vengono caricati all'avvio. I file nelle sottodirectory vengono caricati su richiesta, consentendo alle istruzioni di diventare pertinenti mentre Claude lavora in quelle parti del progetto.

Per le istruzioni condivise, scegli una posizione adatta al tuo team. Un CLAUDE.md nella directory radice colloca le indicazioni accanto agli altri file di primo livello del repository. .claude/CLAUDE.md le colloca insieme ai file del progetto specifici di Claude.

Le istruzioni personali influiscono su più aspetti della sola organizzazione dei file

CLAUDE.local.md ha uno scopo diverso rispetto al file di progetto condiviso: contiene le tue istruzioni personali per quel progetto. Nella versione 2.1.277, la sua presenza influisce anche sul fatto che Claude Code ricorra o meno a AGENTS.md.

Questo significa che l'aggiunta di un file di istruzioni locale può cambiare quali istruzioni condivise entrano nel contesto. Prima di crearne uno in un repository che si basa su AGENTS.md, controlla l'impostazione Istruzioni del progetto descritta di seguito.

Le posizioni indicate sopra provengono da una documentazione in continuo aggiornamento, la cui formulazione esatta di settembre 19 non è stata verificata. Il comportamento di ripiego nella sezione successiva è documentato specificamente per la release contrassegnata dal tag 2.1.277.

Claude Code legge AGENTS.md automaticamente?

Sì, a determinate condizioni. Le note di rilascio di Claude Code 2.1.277 affermano: «Aggiunto il supporto per AGENTS.md: in un progetto senza CLAUDE.md, Claude Code legge invece AGENTS.md».

Il comportamento predefinito prevede un ripiego, quindi la sola presenza di un file AGENTS.md non significa che verrà caricato. In questa release, il controllo non riguarda soltanto un CLAUDE.md.

Che cosa impedisce il ripiego predefinito?

La presenza di uno qualsiasi di questi file in qualunque punto del percorso dalla radice del file system alla directory di lavoro impedisce il ripiego predefinito su AGENTS.md :

• CLAUDE.md
• .claude/CLAUDE.md
• CLAUDE.local.md

Le istruzioni gestite, le istruzioni personali in ~/.claude/CLAUDE.mde .claude/rules/ impediscono effettivamente Non questo ripiego.

Per esempio, considera un repository con un AGENTS.md condiviso e nessun file di istruzioni Claude idoneo lungo il percorso delle directory superiori. La modalità predefinita legge le istruzioni di AGENTS. Se poi aggiungi CLAUDE.local.md, il ripiego predefinito viene impedito, anche se il nuovo file contiene istruzioni personali anziché le indicazioni condivise del team.

Come funziona l'individuazione di AGENTS.md

Il supporto integrato è fornito dal agents-md plugin, versione 0.1.0. Individua entrambi AGENTS.md e .claude/AGENTS.md lungo il percorso delle directory superiori e aggiunge le istruzioni annidate quando Claude legge file sotto la directory radice del progetto.

I contenuti già caricati tramite un'importazione o un collegamento vengono deduplicati. Questo è importante se un file di istruzioni Claude include già gli stessi contenuti di AGENTS.

Alla data limite di pubblicazione di settembre 19, l'annuncio della release afferma che questo supporto non è ancora disponibile su Bedrock, Vertex o Foundry.

Configura Claude Code per leggere un solo file o entrambi

Apri /config e modifica Istruzioni del progetto per scegliere il comportamento di caricamento delle istruzioni. Il README del plugin con tag v2.1.277 documenta quattro valori esatti.

Il README include una precisazione importante per managed-only: i contenuti annidati di CLAUDE.md possono comunque essere aggiunti. Non interpretare questo valore come una garanzia che nessun contenuto di istruzioni Claude annidate possa entrare nella conversazione.

Configurazione esatta per la versione 2.1.277

Per caricare entrambe le famiglie di istruzioni, usa questa configurazione:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": {
        "instructionFiles": "claude-md-and-agents-md"
      }
    }
  }
}

Per questa release, inseriscila nelle impostazioni utente in ~/.claude/settings.json, in un file fornito tramite --settingso nelle impostazioni gestite. Il file di progetto .claude/settings.json fornisce effettivamente Non queste opzioni del plugin.

Le modifiche si applicano alla successiva ricostruzione del contesto, per esempio al turno successivo o in una nuova conversazione. Tieni presente questa tempistica quando verifichi se un'impostazione ha modificato le istruzioni caricate.

Importare le istruzioni condivise rimane un'opzione

Puoi anche inserire @AGENTS.md all'interno di un CLAUDE.mdadiacente. In questo modo le istruzioni condivise vengono importate esplicitamente tramite il file di istruzioni Claude.

Le importazioni nei file di istruzioni Claude usano @path/to/file.md e sono state introdotte nella v0.2.107. La versione 2.1.277 deduplica i contenuti di AGENTS già importati da CLAUDE.md.

Questo ti offre due modi per organizzare le indicazioni condivise: configurare Claude Code per caricare entrambi i file oppure usare un'importazione per includere i contenuti di AGENTS in un file di istruzioni Claude. Scegli la soluzione che rende chiara la relazione ai collaboratori del repository.

Che cosa va nella directory .claude?

La .claude directory contiene diversi tipi di file di progetto. Hanno scopi diversi, quindi scegli la posizione in base a ciò che stai scrivendo: indicazioni persistenti, configurazione, un prompt riutilizzabile, la definizione di un sottoagente o una procedura.

Le impostazioni personali valide per tutti i progetti si trovano in ~/.claude/settings.json. Le definizioni personali dei sottoagenti usano ~/.claude/agents/, e le skill personali usano ~/.claude/skills/<name>/SKILL.md.

Comandi, subagenti e skill

Un file di comando come .claude/commands/deploy.md crea /deploy. La versione 2.1.3 ha unificato i comandi slash e le skill, e i file di comando esistenti continuano a funzionare insieme alle skill.

Le definizioni dei subagenti usano Markdown con frontmatter YAML. I campi obbligatori sono name e description; i campi facoltativi rilevanti includono tools, modele permissionMode. Gestiscili con /agents, e usa la guida ai subagenti per quella parte della configurazione del progetto.

Le skill raccolgono procedure riutilizzabili in una cartella contenente SKILL.md, con script e materiale di riferimento facoltativi. Claude può selezionare le skill pertinenti, oppure puoi invocarne una con /skill-name; il corpo della skill viene caricato quando viene usata. La guida alle skill descrive questo flusso di lavoro.

Queste strutture precedono la versione che ha introdotto il fallback AGENTS. Il changelog associato al tag conferma che impostazioni di progetto, comandi, agenti e skill esistevano già nella v2.1.277. Le descrizioni dettagliate delle directory si basano su documentazione aggiornata nel tempo, la cui formulazione esatta alla data limite non è stata verificata.

CLAUDE.md e memoria automatica a confronto

CLAUDE.md e la memoria automatica differiscono per chi scrive il contenuto. Tu scrivi i file di istruzioni per definire le indicazioni del progetto; Claude salva il contesto utile nella memoria automatica.

Il changelog associato al tag documenta il salvataggio automatico e la gestione tramite /memory nella versione 2.1.59. La memoria automatica svolge quindi un ruolo distinto dalle istruzioni che mantieni deliberatamente in CLAUDE.md o AGENTS.md.

Per decidere dove collocare le informazioni, basati su questa distinzione relativa a chi le scrive. Inserisci comandi di build espliciti, convenzioni, note sull'architettura e regole del flusso di lavoro nei file di istruzioni. Usa /memory per gestire il contesto utile che Claude salva automaticamente.

Punti chiave

• CLAUDE.md contiene istruzioni persistenti in Markdown che Claude Code legge e inserisce nel contesto; non impone una configurazione.
• Claude Code 2.1.277 aggiunge il fallback condizionale a AGENTS.md , con Bedrock, Vertex e Foundry esclusi al momento del rilascio.
• Un file presente in una directory superiore, CLAUDE.md, .claude/CLAUDE.md, oppure CLAUDE.local.md disabilita il fallback predefinito.
• Imposta le istruzioni del progetto su claude-md-and-agents-md per caricare entrambe le famiglie di istruzioni.
• Nella v2.1.277, le opzioni del plugin vanno nelle impostazioni utente, in un file --settings o nelle impostazioni gestite, non nel file di progetto .claude/settings.json.
• La .claude contiene anche impostazioni, comandi, subagenti e skill; la memoria automatica contiene il contesto salvato da Claude.

FAQ

Che cos'è CLAUDE.md?

CLAUDE.md è un file Markdown di testo semplice contenente istruzioni persistenti per Claude Code, come comandi di build, convenzioni di codifica, note sull'architettura e regole del flusso di lavoro. Claude lo legge e lo inserisce nel contesto della sessione, e /init può generare un file iniziale basato sul progetto.

Quale file viene caricato quando esistono sia CLAUDE.md sia AGENTS.md?

Nella configurazione predefinita di Claude Code 2.1.277 claude-md-or-agents-md di Claude Code, un file di istruzioni Claude che soddisfa i criteri disabilita il fallback AGENTS. Seleziona claude-md-and-agents-md per caricarli entrambi, oppure importa le istruzioni AGENTS adiacenti con @AGENTS.md all'interno di CLAUDE.md.

Perché l'aggiunta di CLAUDE.local.md interrompe il fallback AGENTS?

La versione 2.1.277 include CLAUDE.local.md tra i file che disabilitano il fallback predefinito quando vengono trovati nel percorso dalla radice del filesystem alla directory di lavoro. La sua presenza può quindi cambiare se le istruzioni condivise AGENTS vengono caricate, anche se il suo scopo è fornire indicazioni personali per il progetto.

Posso abilitare entrambi i file nel file di progetto .claude/settings.json?

Nella v2.1.277, il file di progetto .claude/settings.json non fornisce le opzioni del plugin agents-md . Usa /config, oppure inserisci la configurazione documentata pluginConfigs nelle impostazioni utente, in un file --settings o nelle impostazioni gestite.