Configurare Claude Code per leggere AGENTS.md

In breve: come configurare Claude Code

Segui questa sequenza:

1. Esegui claude --version. Serve la v2.1.277 o una versione successiva.
2. Se necessario, aggiorna il programma. Un’installazione nativa accetta claude update; con Homebrew e WinGet vanno invece usati i rispettivi comandi di aggiornamento del package manager.
3. Verifica che la sessione possa recuperare i feature flag di Anthropic. Il caricamento nativo di AGENTS.md non è disponibile nelle sessioni con provider di terze parti come Amazon Bedrock, Google Cloud's Agent Platform e Microsoft Foundry, né quando le impostazioni relative alla telemetria o al traffico non essenziale impediscono di scaricare quei flag.
4. Inserisci AGENTS.md oppure .claude/AGENTS.md nel percorso del progetto. Con la modalità predefinita, assicurati che nella directory di lavoro o in quelle superiori non siano presenti CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md di progetto.
5. Se ti servono entrambe le famiglie di file, apri /config e imposta Project instructions su claude-md-and-agents-md.
6. Fai la prova in una sessione nuova. La prima sessione successiva all’installazione o all’aggiornamento costituisce un’eccezione: prima di valutare il risultato, aprine un’altra.

Questa è la procedura nativa. Se in /config non compare Project instructions, conserva in CLAUDE.md l’import documentato @AGENTS.md.

Come Claude Code sceglie davvero le istruzioni di progetto

Il nuovo comportamento funziona come un selettore, non come una scansione indiscriminata di tutti i file di istruzioni. Nella modalità predefinita claude-md-or-agents-md, Claude Code cerca prima le istruzioni Claude a livello di progetto. Passa a AGENTS.md solo se non trova nessuno dei file Claude idonei nella directory di lavoro o in quelle superiori.

Il dettaglio meno evidente riguarda l’ambito. Un CLAUDE.local.md in una directory superiore impedisce il fallback. Non hanno invece questo effetto un file personale ~/.claude/CLAUDE.md, un CLAUDE.md gestito dall’organizzazione e .claude/rules/. È una distinzione che spiega perché due sviluppatori possano aprire lo stesso repository e osservare comportamenti diversi.

Quando si applica il fallback, all’avvio della sessione Claude Code legge AGENTS.md e .claude/AGENTS.md dalla directory di lavoro e dalle directory superiori. Il file AGENTS.md di una sottodirectory può essere caricato in seguito, quando Claude legge un file al suo interno, purché quella sottodirectory non contenga un proprio file Claude idoneo. Non vengono letti direttamente AGENTS.local.md, AGENTS.override.md né i file sotto .agents/.

Il meccanismo assomiglia più al selettore elettrico di un edificio che a una ricerca tra cartelle: prima viene scelto il circuito attivo delle istruzioni. I file collegati all’altro circuito possono essere perfettamente validi, ma restare comunque esclusi.

Scegliere consapevolmente la modalità Project instructions

Apri /config, individua Project instructions e scegli in base a quale deve essere la fonte autorevole del repository:

• Fallback, claude-md-or-agents-md: ideale per un repository che usa già AGENTS.md e non contiene file Claude di progetto. È la modalità predefinita.
• Entrambi, claude-md-and-agents-md: indicata quando AGENTS.md contiene le regole condivise e CLAUDE.md aggiunge indicazioni specifiche per Claude.
• Solo Claude, claude-md: adatta a un team che non è ancora pronto a rendere disponibili a Claude Code le istruzioni condivise tra agenti.
• Solo gestiti, managed-only: pensata per un contesto di avvio controllato, in cui vanno caricate le policy dell’organizzazione e la memoria automatica, ma non le istruzioni del repository.

In modalità Entrambi, Claude Code legge in ogni directory il contenuto Claude prima del contenuto AGENTS. Inoltre evita di caricare due volte lo stesso AGENTS.md se CLAUDE.md lo importa già o è un collegamento simbolico a quel file.

La scelta entra in vigore dal messaggio successivo e rimane valida nelle nuove sessioni. Può anche essere configurata nel plugin integrato agents-md@builtin tramite le impostazioni utente, un file --settings oppure le impostazioni gestite. Claude Code ignora l’opzione nei file di impostazioni locali e di progetto: un repository non può quindi imporre silenziosamente a tutti gli sviluppatori la stessa selezione. Un amministratore può invece stabilirla centralmente con le impostazioni gestite.

Verificare quale file ha caricato una nuova sessione

Usa un’informazione innocua, non un’istruzione distruttiva. Aggiungi questa riga al file che vuoi verificare:

Project probe: BASALT-HERON.

Chiudi quindi la sessione, avviane una nuova nel repository e chiedi: What is the project probe? Se la risposta corretta è BASALT-HERON, il contenuto è entrato nel contesto della sessione. Al termine, rimuovi la riga.

Non affidarti soltanto a /context. Un AGENTS.md caricato direttamente non compare nell’elenco Memory files. Con il fallback predefinito, una sessione interattiva può mostrare all’avvio la riga AGENTS.md loaded. La domanda basata sul probe innocuo funziona anche con le altre modalità di selezione.

Se il probe non riesce, controlla nell’ordine:

1. Versione: v2.1.277 o successiva.
2. Numero della sessione: non deve essere la prima dopo l’installazione o l’aggiornamento.
3. Provider: non deve trattarsi di una sessione il cui provider impedisce il recupero dei feature flag di Anthropic.
4. Ambiente: nessuna variabile relativa alla telemetria o al traffico non essenziale deve aver disabilitato quel recupero.
5. Plugin e policy: il plugin integrato agents-md deve essere abilitato; né disableAllHooks né allowManagedHooksOnly devono bloccarlo.
6. Gerarchia dei file: con la modalità predefinita, al livello corrente o in quelli superiori non devono esserci CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md idonei.
7. Modalità: /config deve corrispondere al comportamento desiderato.

Se Project instructions non compare in /config, è già un indizio diagnostico: la sessione usa una versione non supportata oppure non può accedere alla funzionalità.

Mantenere l’import quando il supporto nativo non è disponibile

L’import esistente resta il livello di compatibilità più sicuro per Bedrock, Vertex, Foundry, altri provider di terze parti, gli ambienti con telemetria limitata e i team che usano versioni diverse. Inserisci quanto segue in CLAUDE.md, accanto a AGENTS.md:

@AGENTS.md

Sotto puoi aggiungere istruzioni specifiche per Claude. Claude legge prima il file condiviso importato e poi le integrazioni dedicate. Conservare questo ponte non provoca un doppio caricamento quando la modalità Entrambi viene selezionata in una sessione supportata.

Funziona anche un collegamento simbolico da CLAUDE.md ad AGENTS.md, ma l’import è la scelta multipiattaforma più sicura. Su Windows, la creazione di symlink può richiedere privilegi elevati o Developer Mode, mentre Git deve avere la corretta impostazione per i collegamenti simbolici. Un hook SessionStart che stampa AGENTS.md andrebbe rimosso quando il caricamento diretto funziona, perché potrebbe iniettare una seconda copia.

Questa versione cambia i costi di manutenzione. In precedenza, un team con un’unica policy valida per più agenti spesso manteneva due file, uno shim di importazione o un hook. Nelle sessioni supportate, ora il percorso predefinito può ridursi a un solo file di istruzioni versionato. Il prezzo della licenza Claude non cambia: Anthropic include Claude Code nel piano Pro da $20 al mese. Il risparmio sta nei minori punti di sincronizzazione e nelle minori probabilità che una sessione lavori con regole obsolete.

Per completare la configurazione, la guida generale a Claude Code illustra installazione, contesto di progetto e flusso quotidiano dei comandi. Se il repository definisce anche agenti specializzati, la guida ai subagent ne spiega il contesto di avvio separato.

Sette scenari in cui questa funzione conviene davvero

La classifica segue l’ampiezza del problema di coordinamento eliminato dal nuovo selettore.

I primi tre casi offrono il ritorno maggiore, perché l’errore si moltiplica tra persone e repository. Per un repository individuale con un solo agente, la comodità esiste ma resta contenuta.

Tre prodotti che si potrebbero costruire

1. Uno strumento diagnostico per le istruzioni multi-agent

Si può creare una CLI locale con un controllo CI che spieghi esattamente quali file di istruzioni verranno caricati da ciascun coding agent. Platform team e società di consulenza pagherebbero per avere una risposta affidabile prima di estendere la configurazione a tutti i repository.

La domanda è già visibile: claude code setup registra circa 1,900 ricerche mensili negli Stati Uniti, mentre claude md vs agents md ne totalizza 480 ed è cresciuta del 1,500% su base annua. La versione minima vendibile analizza l’albero dei file, legge la versione di Claude Code e la configurazione del provider, segnala i file che ne oscurano altri e stampa un piano dell’ordine di caricamento. Un livello a pagamento per i team potrebbe applicare la stessa policy a più repository.

È l’opportunità più solida perché risolve un problema diagnostico, non uno di template. Il limite è il rischio di piattaforma: Anthropic potrebbe integrare questi controlli in claude doctor. Per restare difendibile, il prodotto dovrebbe quindi coprire più coding agent e conservare una cronologia delle divergenze delle policy, anziché dipendere da un singolo comando Claude.

2. Un generatore di policy AGENTS.md con linter

Un editor guidato potrebbe trasformare comandi di build, regole di test, confini tra directory e requisiti di review in un AGENTS.md conciso, verificandolo poi alla ricerca di conflitti e formulazioni vaghe. Il cliente ideale è un piccolo team di sviluppo che sta adottando più agenti.

agents md registra circa 2,900 ricerche mensili negli Stati Uniti. La query più specifica agents md best practices ne totalizza 210 ed è cresciuta del 750% su base annua. Per un MVP servono uno scanner del repository, una breve intervista, una bozza generata e regole di lint per le istruzioni duplicate o contraddittorie. Lo strumento dovrebbe rispettare le indicazioni del provider sulla sintesi dei file di progetto, invece di produrre un manuale di policy smisurato.

Il limite è una difendibilità ridotta: qualsiasi coding agent può preparare una bozza Markdown. Il prodotto si giustifica solo se la validazione rispecchia davvero l’ordine di caricamento e dimostra che ogni strumento di coding supportato ha acquisito il risultato.

3. Un audit di migrazione per flotte miste

Si può offrire un report che mappi CLAUDE.md, AGENTS.md, import, symlink, hook, regole annidate ed eccezioni dei provider, per poi definire un piano di migrazione sicuro verso un’unica fonte. Le agenzie e i team più grandi che usano diversi strumenti agentici sono i probabili acquirenti.

Le 480 ricerche mensili di claude md vs agents md, cresciute del 1,500% su base annua, mostrano in modo insolitamente diretto quanto sia diffusa la confusione. L’MVP può essere un analizzatore del repository in sola lettura accompagnato da un piano per la pull request. Non dovrebbe mai eliminare automaticamente un ponte, perché le sessioni non supportate potrebbero averne ancora bisogno.

Il limite è una finestra temporale ristretta. Quando i team convergeranno su una convenzione stabile per i file condivisi, le migrazioni una tantum diminuiranno. Il servizio dovrà quindi puntare sugli audit ricorrenti delle policy e sui controlli di compatibilità dei provider.

Limiti e valutazione realistica

Il fallback nativo elimina un ponte. Non trasforma però le istruzioni di progetto in regole vincolanti, non rende compatibile ogni provider e non risolve i conflitti tra indicazioni. Anthropic descrive i file di istruzioni come contesto. Se un comando deve essere sempre bloccato, occorre una regola di autorizzazione o un hook PreToolUse.

Inoltre, AGENTS.md non diventa visibile negli stessi strumenti diagnostici di CLAUDE.md. Un caricamento diretto non compare in /memory né nell’elenco Memory files di /context. Questa incoerenza rende utile mantenere il probe innocuo nella checklist di migrazione.

Non rimuovere un import funzionante da una flotta con provider misti soltanto perché il test nativo riesce su un portatile. Non scegliere la modalità Entrambi senza prima controllare le contraddizioni. In una directory, il contenuto Claude viene letto prima di quello AGENTS, ma l’ordine nel contesto non costituisce un rigido sistema di precedenza delle policy.

Resta comunque un miglioramento operativo importante. Un repository che considera già AGENTS.md la propria fonte condivisa può ora funzionare con Claude Code senza fingere che il secondo nome di file sia quello autorevole. Una piccola funzionalità, con un effetto rilevante sul coordinamento.

Se vuoi costruire un sistema affidabile di istruzioni multi-agent per i tuoi repository, posso aiutarti a progettarne l’architettura e la distribuzione.