Claude Code ora legge AGENTS.md: cosa è cambiato nella versione 2.1.277

Il 18 settembre 2026 è stato aggiunto il supporto per AGENTS.md in Claude Code 2.1.277. Se la funzionalità è disponibile nella sessione e nella directory di lavoro e, nell'intera catena di directory a monte, non è presente alcun CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md, Claude Code legge AGENTS.md per impostazione predefinita, senza import manuale. In precedenza, si otteneva questo risultato importando @AGENTS.md in CLAUDE.md oppure creando un collegamento simbolico da CLAUDE.md ad AGENTS.md: per maggiori dettagli, leggi l'articolo su un unico file di istruzioni per più agenti.

Se usi Claude Code e uno o due altri strumenti nello stesso repository, la modalità Project instructions che scegli determina quali file di istruzioni Claude Code legge. Di seguito trovi le condizioni per ciascuna delle quattro modalità e i passaggi per migrare dalla configurazione precedente.

Altri materiali sulla configurazione degli strumenti sono disponibili nella documentazione di Ailoot.

Cosa è cambiato nella versione 2.1.277?#

Il CHANGELOG.md ufficiale del progetto Claude Code su GitHub lo descrive così:

Traduzione: è stato aggiunto il supporto per AGENTS.md: in un progetto senza CLAUDE.md, Claude Code ora legge AGENTS.md; l'impostazione si può cambiare in “Project instructions” tramite /config (non ancora disponibile su Bedrock, Vertex o Foundry).

Prima di questa versione, l'assenza di CLAUDE.md, .claude/CLAUDE.md e CLAUDE.local.md nella cartella di lavoro e nelle directory superiori non bastava, da sola, ad attivare la lettura di AGENTS.md. Servivano un import esplicito, un collegamento simbolico o un hook manuale. Ora, quando la funzionalità è disponibile, l'agente carica il file automaticamente.

Quali file impediscono la lettura automatica di AGENTS.md#

Se hai un file personale ~/.claude/CLAUDE.md con impostazioni di stile di programmazione, questo non impedirà a Claude Code di leggere l'AGENTS.md del progetto. Tuttavia, qualsiasi CLAUDE.local.md nella cartella di lavoro, anche se non è aggiunto a Git e contiene appunti personali, blocca la lettura automatica di AGENTS.md nella modalità predefinita. L'import esplicito continua a funzionare; per leggere direttamente entrambi i file, devi cambiare modalità.

Se in Project instructions è selezionata una modalità di lettura diretta (vedi “4 modalità Project instructions: quale scegliere” qui sotto) e nella directory di lavoro o in quelle superiori non è presente alcun CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md, all'avvio della sessione Claude Code legge ogni AGENTS.md e .claude/AGENTS.md presente in queste directory. Per il caso in cui non ci siano file che bloccano il caricamento, la documentazione mostra una riga di questo tipo in una sessione interattiva:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

Un file AGENTS.md in una sottodirectory viene caricato quando Claude apre un file in quella directory con lo strumento Read. In modalità claude-md-or-agents-md, ciò avviene solo se la sottodirectory non contiene un proprio CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md. Per la modalità claude-md-and-agents-md, la documentazione descrive la regola generale: CLAUDE.md e AGENTS.md vengono letti insieme, prima CLAUDE.md e poi AGENTS.md in ciascuna directory. AGENTS.local.md, AGENTS.override.md e qualsiasi elemento nella directory .agents/ non vengono letti automaticamente.

Nella documentazione di Ailoot trovi materiali sulla configurazione dell'ambiente di lavoro di un agente AI, inclusi file di istruzioni con il contesto del progetto.

4 modalità Project instructions: quale scegliere#

Il comportamento delle modalità nella tabella è descritto nella documentazione di Anthropic. La colonna a destra dà indicazioni su quale scegliere:

Puoi scegliere la modalità anche senza interfaccia, tramite settings.json:

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

Claude Code ignora questo valore nelle impostazioni project e local. Secondo la documentazione di Anthropic, si può impostare in ~/.claude/settings.json, in un file --settings o nelle impostazioni gestite dall'organizzazione.

Se hai già configurato un file di istruzioni condiviso da più strumenti AI nello stesso repository, le istruzioni per le versioni precedenti alla 2.1.277 spiegano come funziona l'import @. Questo metodo funziona ancora.

Perché Project instructions non è presente in /config#

Per prima cosa, verifica la versione con il comando claude --version. Se è precedente alla 2.1.277, aggiorna Claude Code. Se la versione è adeguata ma la sezione continua a non comparire, verifica gli altri motivi elencati sopra. Finché la funzionalità non è disponibile, l'import di @AGENTS.md in CLAUDE.md resta una soluzione alternativa funzionante.

Cosa fare con il vecchio import @AGENTS.md#

I passaggi successivi dipendono dalla configurazione precedente. Per prima cosa, assicurati che la funzionalità sia disponibile nella sessione, come descritto nella sezione precedente.

• CLAUDE.md con un import @AGENTS.md. Puoi lasciarlo così: Claude Code non leggerà il file due volte con nessun valore di Project instructions. Eliminare CLAUDE.md è facoltativo: l'import dà già a Claude accesso al contenuto di AGENTS.md. Continua a verificare il caricamento tramite l'import usando /memory; una domanda diretta a Claude sul contenuto delle istruzioni è solo una verifica debole.
• CLAUDE.md che chiede a parole di leggere AGENTS.md. Una richiesta del genere non è un import e, da sola, non garantisce che il file venga caricato. Sostituisci la formulazione con un import @AGENTS.md se vuoi mantenere CLAUDE.md (per esempio, per gli strumenti che lo leggono a loro volta). Se decidi di eliminare del tutto CLAUDE.md e hai selezionato la modalità claude-md-or-agents-md, verifica prima che CLAUDE.md non contenga istruzioni esclusive e che nella directory di lavoro o in quelle superiori non ci siano altri CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md; altrimenti, Claude Code continuerà a leggere il file rimanente invece di AGENTS.md. Dopo averlo eliminato, assicurati che la transizione sia avvenuta: quando non rimangono file che bloccano il caricamento, in una sessione interattiva appare la riga AGENTS.md loaded. Se CLAUDE.md rimane e in modalità claude-md-and-agents-md vengono letti entrambi i file, controlla /memory (nella versione 2.1.280+). Una domanda diretta a Claude non permette di distinguere il caricamento diretto dall'import.
• Collegamento simbolico CLAUDE.md ad AGENTS.md. Puoi mantenerlo: nessuna modalità comporta una lettura duplicata. Prima di eliminare il collegamento in modalità claude-md-or-agents-md, verifica che le istruzioni necessarie siano state conservate e che nella directory di lavoro o in quelle superiori non ci siano altri CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md. Verifica il caricamento allo stesso modo: la riga AGENTS.md loaded all'avvio della sessione quando non ci sono file che bloccano il caricamento, oppure /memory (versione 2.1.280+). Se CLAUDE.md rimane in modalità claude-md-and-agents-md, una domanda diretta a Claude è solo una verifica debole. L'assenza di un errore non basta a confermare il caricamento.
• Un hook SessionStart che stampava manualmente il contenuto di AGENTS.md. Quando il file viene letto direttamente, un hook del genere aggiunge una seconda copia al contesto. Mentre l'hook è attivo, la domanda “cosa contengono le tue istruzioni?” non conferma la lettura diretta: Claude può rispondere sulla base del testo aggiunto dall'hook. Procedi così:
  1. Verifica che la funzionalità sia disponibile: versione 2.1.277 o successiva, la sessione riceve i flag delle funzionalità, il plugin è attivo e la prima sessione dopo l'installazione o l'aggiornamento è terminata. Scegli una modalità di lettura diretta: né claude-md né managed-only. Per la modalità predefinita, verifica anche che non ci siano file che bloccano il caricamento.
  2. Rimuovi l'hook.
  3. Chiudi la sessione e aprine una nuova. L'hook SessionStart aggiunge il testo all'avvio, quindi il suo contenuto resta nel contesto di una sessione già aperta. La risposta di Claude sul contenuto delle istruzioni in quella sessione non conferma la lettura diretta.
  4. Verifica il caricamento nella nuova sessione. Nella versione 2.1.280 o successiva, il percorso di AGENTS.md è visibile in /memory. Nelle versioni dalla 2.1.277 alla 2.1.279, se non ci sono file che bloccano il caricamento, cerca la riga AGENTS.md loaded all'avvio: la documentazione la descrive specificamente per il caso in cui non sia stato trovato CLAUDE.md. Se mantieni CLAUDE.md e usi la modalità claude-md-and-agents-md, la verifica è limitata: /memory non mostra AGENTS.md in queste versioni, la documentazione non descrive una riga di caricamento per questo caso e una parafrasi delle istruzioni non permette di distinguere la lettura diretta da un import @ all'interno di CLAUDE.md. In tal caso, aggiorna alla versione 2.1.280 o successiva e controlla /memory.

Come verificare che AGENTS.md sia stato caricato#

Ci sono altre due differenze rispetto al normale CLAUDE.md: gli hook InstructionsLoaded non vengono attivati per questo tipo di AGENTS.md (funzionano invece per AGENTS.md importato tramite la sintassi @ da CLAUDE.md o collegato tramite un collegamento simbolico CLAUDE.md); le directory aggiunte con il flag --add-dir insieme alla variabile CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD caricano solo il CLAUDE.md di quella directory, senza includere il suo AGENTS.md.

Se devi esaminare il contenuto di un file di istruzioni di progetto molto lungo, leggi l'analisi separata su come configurare CLAUDE.md senza renderlo prolisso. Illustra la struttura delle istruzioni, mentre le condizioni di caricamento di AGENTS.md sono descritte sopra. Per gli appunti di lavoro tra una sessione e l'altra, leggi l'analisi di un secondo cervello in Claude Code, dedicata alla memoria personale stratificata sopra le istruzioni del progetto.

E adesso?#

La funzionalità è stata rilasciata il 18 settembre 2026 nella versione 2.1.277. Anthropic potrebbe chiarire i dettagli delle modalità nelle versioni future; prima di modificare le impostazioni di un progetto importante, confronta quindi questo articolo con le opzioni attuali di /config e con il changelog ufficiale.