Come Claude ricorda il tuo progetto

Fornisci a Claude istruzioni persistenti con file CLAUDE.md o AGENTS.md e lascia che Claude accumuli apprendimenti automaticamente con la memoria automatica.

Ogni sessione di Claude Code inizia con una finestra di contesto nuova. Due meccanismi trasportano la conoscenza tra le sessioni:

• File CLAUDE.md: istruzioni che scrivi per dare a Claude un contesto persistente. Claude può anche leggere i file AGENTS.md di un repository, da soli o insieme a CLAUDE.md
• Memoria automatica: note che Claude scrive da solo in base alle tue correzioni e preferenze

Questa pagina spiega come:

• Scrivere e organizzare file CLAUDE.md
• Utilizzare un file AGENTS.md esistente come istruzioni del tuo progetto, da solo o insieme a CLAUDE.md
• Limitare le regole a tipi di file specifici con .claude/rules/
• Configurare la memoria automatica in modo che Claude prenda note automaticamente
• Risolvere i problemi quando le istruzioni non vengono seguite

CLAUDE.md vs memoria automatica

Claude Code ha due sistemi di memoria complementari. Entrambi vengono caricati all'inizio di ogni conversazione. Claude li tratta come contesto, non come configurazione forzata. Per bloccare un'azione indipendentemente da ciò che Claude decide, utilizza un hook PreToolUse invece. Più specifiche e concise sono le tue istruzioni, più coerentemente Claude le segue.

Usa file CLAUDE.md quando vuoi guidare il comportamento di Claude. La memoria automatica consente a Claude di imparare dalle tue correzioni senza sforzo manuale.

I subagents possono anche mantenere la propria memoria automatica. Vedi configurazione subagent per i dettagli.

File CLAUDE.md

I file CLAUDE.md sono file markdown che forniscono a Claude istruzioni persistenti per un progetto, il vostro flusso di lavoro personale o l'intera organizzazione. Scrivete questi file in testo semplice; Claude li legge all'inizio di ogni sessione. Se il vostro repository utilizza AGENTS.md invece, consultate AGENTS.md.

Quando aggiungere a CLAUDE.md

Trattate CLAUDE.md come il luogo in cui scrivete ciò che altrimenti dovreste rispiegare. Aggiungete a esso quando:

• Claude commette lo stesso errore una seconda volta
• Una revisione del codice rileva qualcosa che Claude avrebbe dovuto sapere su questo codebase
• Digitate la stessa correzione o chiarimento nella chat che avete digitato nella sessione precedente
• Un nuovo membro del team avrebbe bisogno dello stesso contesto per essere produttivo

Mantenetelo limitato ai fatti che Claude dovrebbe ricordare in ogni sessione: comandi di build, convenzioni, layout del progetto, regole "fai sempre X". Se una voce è una procedura multi-step o riguarda solo una parte del codebase, spostatela in una skill o in una regola con ambito di percorso invece. La panoramica dell'estensione copre quando utilizzare ogni meccanismo.

Scegliete dove posizionare i file CLAUDE.md

I file CLAUDE.md possono trovarsi in diversi percorsi, ognuno con un ambito diverso. La tabella seguente li elenca in ordine di caricamento, dall'ambito più ampio al più specifico, quindi un'istruzione di progetto appare in contesto dopo un'istruzione utente.

I file CLAUDE.md e CLAUDE.local.md nella gerarchia di directory sopra la directory di lavoro vengono caricati all'avvio. I file nelle sottodirectory si caricano su richiesta quando Claude legge i file in quelle directory. Consultate Come si caricano i file CLAUDE.md per l'ordine di risoluzione completo.

Per i progetti di grandi dimensioni, potete suddividere le istruzioni in file specifici per argomento utilizzando regole di progetto. Le regole vi permettono di limitare le istruzioni a tipi di file specifici o sottodirectory.

Configurate un CLAUDE.md di progetto

Un CLAUDE.md di progetto può essere archiviato in ./CLAUDE.md o ./.claude/CLAUDE.md. Create questo file e aggiungete istruzioni che si applicano a chiunque lavori sul progetto: comandi di build e test, standard di codifica, decisioni architettoniche, convenzioni di denominazione e flussi di lavoro comuni. Queste istruzioni sono condivise con il vostro team tramite controllo del codice sorgente, quindi concentratevi su standard a livello di progetto piuttosto che su preferenze personali. Per confermare che il file è stato caricato, eseguite /context in una sessione e controllate l'elenco sotto Memory files.

Scrivete istruzioni efficaci

I file CLAUDE.md vengono caricati nella finestra di contesto all'inizio di ogni sessione, consumando token insieme alla vostra conversazione. La visualizzazione della finestra di contesto mostra dove CLAUDE.md si carica rispetto al resto del contesto di avvio. Poiché sono contesto piuttosto che configurazione applicata, il modo in cui scrivete le istruzioni influisce su quanto affidabilmente Claude le segue. Le istruzioni specifiche, concise e ben strutturate funzionano meglio.

Dimensione: mirate a meno di 200 righe per file CLAUDE.md. I file più lunghi consumano più contesto e riducono l'aderenza. Se le vostre istruzioni stanno crescendo molto, utilizzate regole con ambito di percorso in modo che le istruzioni si carichino solo quando Claude lavora con file corrispondenti. Potete anche dividere il contenuto in importazioni per l'organizzazione, anche se i file importati si caricano comunque e entrano nella finestra di contesto all'avvio.

Struttura: utilizzate intestazioni markdown e punti elenco per raggruppare le istruzioni correlate. Claude scansiona la struttura nello stesso modo in cui lo fanno i lettori: le sezioni organizzate sono più facili da seguire rispetto ai paragrafi densi.

Specificità: scrivete istruzioni abbastanza concrete da poter verificare. Ad esempio:

• "Utilizzate l'indentazione a 2 spazi" invece di "Formattate il codice correttamente"
• "Eseguite npm test prima di eseguire il commit" invece di "Testate i vostri cambiamenti"
• "I gestori API si trovano in src/api/handlers/" invece di "Mantenete i file organizzati"

Coerenza: se due regole si contraddicono a vicenda, Claude potrebbe sceglierne una arbitrariamente. Rivedete periodicamente i vostri file CLAUDE.md, i file CLAUDE.md annidati nelle sottodirectory e .claude/rules/ per rimuovere istruzioni obsolete o conflittuali. Nei monorepo, utilizzate claudeMdExcludes per saltare i file CLAUDE.md di altri team che non sono rilevanti per il vostro lavoro.

Importate file aggiuntivi

I file CLAUDE.md possono importare file aggiuntivi utilizzando la sintassi @path/to/import. I file importati vengono espansi e caricati in contesto all'avvio insieme al CLAUDE.md che li riferisce.

Sono consentiti sia i percorsi relativi che assoluti. I percorsi relativi si risolvono rispetto al file che contiene l'importazione, non alla directory di lavoro. I file importati possono importare ricorsivamente altri file, con una profondità massima di quattro hop.

L'analisi dell'importazione salta gli intervalli di codice Markdown e i blocchi di codice recintati. Per menzionare un percorso nel vostro CLAUDE.md senza importarlo, avvolgetelo in backtick: scrivere `@README` mantiene il testo letterale, mentre @README al di fuori dei backtick importa il file.

Per includere un README, package.json e una guida al flusso di lavoro, fate riferimento a essi con la sintassi @ in qualsiasi punto del vostro CLAUDE.md:

Consultate @README per la panoramica del progetto e @package.json per i comandi npm disponibili per questo progetto.

# Istruzioni aggiuntive
- flusso di lavoro git @docs/git-instructions.md

Per le preferenze personali per progetto privato che non dovrebbero essere archiviate nel controllo del codice sorgente, create un CLAUDE.local.md nella radice del progetto. Si carica insieme a CLAUDE.md e viene trattato allo stesso modo. Aggiungete CLAUDE.local.md al vostro .gitignore in modo che non venga eseguito il commit. Con CLAUDE_CODE_NEW_INIT=1 impostato, l'esecuzione di /init e la scelta dell'opzione personale lo fa per voi.

Se lavorate su più git worktrees dello stesso repository, un CLAUDE.local.md ignorato da git esiste solo nel worktree in cui lo avete creato. Per condividere istruzioni personali tra worktrees, importate invece un file dalla vostra home directory:

# Preferenze individuali
- @~/.claude/my-project-instructions.md

Come si caricano i file CLAUDE.md

Claude Code carica CLAUDE.md e CLAUDE.local.md dalla vostra directory di lavoro corrente e da ogni directory sopra di essa. Eseguite Claude Code in foo/bar/ e carica le istruzioni da foo/bar/CLAUDE.md, foo/CLAUDE.md e da qualsiasi file CLAUDE.local.md accanto a essi.

Tutti i file scoperti vengono concatenati in contesto piuttosto che sovrascriversi a vicenda. Nell'albero delle directory, il contenuto è ordinato dalla radice del filesystem fino alla vostra directory di lavoro. Per l'esempio foo/bar/, foo/CLAUDE.md appare in contesto prima di foo/bar/CLAUDE.md, quindi le istruzioni più vicine a dove avete lanciato Claude vengono lette per ultime. All'interno di ogni directory, CLAUDE.local.md viene aggiunto dopo CLAUDE.md, quindi le vostre note personali sono l'ultima cosa che Claude legge a quel livello.

Claude scopre anche i file CLAUDE.md e CLAUDE.local.md nelle sottodirectory sotto la vostra directory di lavoro corrente. Invece di caricarli all'avvio, vengono inclusi quando Claude legge i file in quelle sottodirectory.

Se lavorate in un grande monorepo in cui i file CLAUDE.md di altri team vengono raccolti, utilizzate claudeMdExcludes per saltarli. Per il layout completo dei file CLAUDE.md e delle regole a livello di radice e per directory, consultate Monorepo e repository di grandi dimensioni.

I commenti HTML a livello di blocco (<!-- maintainer notes -->) nei file CLAUDE.md vengono rimossi prima che il contenuto venga iniettato nel contesto di Claude. Utilizzateli per lasciare note per i manutentori umani senza spendere token di contesto su di essi. I commenti all'interno dei blocchi di codice vengono preservati. Quando aprite un file CLAUDE.md direttamente con lo strumento Read, i commenti rimangono visibili.

Caricamento da directory aggiuntive

Il flag --add-dir dà a Claude accesso a directory aggiuntive al di fuori della vostra directory di lavoro principale. Per impostazione predefinita, i file CLAUDE.md da queste directory non vengono caricati.

Per caricare anche i file di memoria da directory aggiuntive, impostate la variabile di ambiente CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

La forma inline imposta la variabile per quel singolo lancio in Bash o Zsh. Per mantenerla attiva per ogni sessione, aggiungetela al blocco env in ~/.claude/settings.json come mostrato in Impostare le variabili di ambiente.

Questo carica CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md e CLAUDE.local.md dalla directory aggiuntiva. CLAUDE.local.md viene saltato se escludete local da --setting-sources.

Organizzate le regole con `.claude/rules/`

Per i progetti più grandi, potete organizzare le istruzioni in più file utilizzando la directory .claude/rules/. Questo mantiene le istruzioni modulari e più facili da mantenere per i team. Le regole possono anche essere limitate a percorsi di file specifici, quindi si caricano in contesto solo quando Claude lavora con file corrispondenti, riducendo il rumore e risparmiando spazio di contesto.

Configurate le regole

Posizionate i file markdown nella directory .claude/rules/ del vostro progetto. Ogni file dovrebbe coprire un argomento, con un nome di file descrittivo come testing.md o api-design.md. Tutti i file .md vengono scoperti ricorsivamente, quindi potete organizzare le regole in sottodirectory come frontend/ o backend/:

your-project/
├── .claude/
│   ├── CLAUDE.md           # Istruzioni principali del progetto
│   └── rules/
│       ├── code-style.md   # Linee guida di stile del codice
│       ├── testing.md      # Convenzioni di test
│       └── security.md     # Requisiti di sicurezza

Le regole senza frontmatter paths vengono caricate all'avvio con la stessa priorità di .claude/CLAUDE.md.

Le regole di progetto vengono saltate se escludete project da --setting-sources. Prima della v2.1.211, le regole che si caricano su richiesta, incluse le regole con ambito di percorso e le regole nelle directory .claude/rules/ annidate, si caricavano anche quando project era escluso.

Regole specifiche del percorso

Le regole possono essere limitate a file specifici utilizzando il frontmatter YAML con il campo paths. Queste regole condizionali si applicano solo quando Claude lavora con file che corrispondono ai modelli specificati.

---
paths:
  - "src/api/**/*.ts"
---

# Regole di sviluppo API

- Tutti gli endpoint API devono includere la convalida dell'input
- Utilizzate il formato di risposta di errore standard
- Includete commenti di documentazione OpenAPI

Le regole senza un campo paths vengono caricate incondizionatamente e si applicano a tutti i file. Le regole con ambito di percorso si attivano quando Claude legge file che corrispondono al modello, non ad ogni utilizzo dello strumento. A partire dalla v2.1.198, la corrispondenza funziona anche quando Claude raggiunge un file attraverso un percorso symlinked alla directory del progetto, ad esempio in un checkout symlinked.

Utilizzate i modelli glob nel campo paths per far corrispondere i file per estensione, directory o qualsiasi combinazione:

Potete specificare più modelli e utilizzare l'espansione tra parentesi graffe per far corrispondere più estensioni in un modello:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Ogni gruppo tra parentesi graffe moltiplica il numero di modelli espansi: src/*.{ts,tsx} si espande a due modelli, e {a,b}/{c,d}/*.{ts,tsx} a otto. Per mantenere l'espansione limitata, l'intero elenco paths di una regola condivide un budget di 1.000 modelli espansi e 4 MiB, e i modelli senza parentesi graffe non contano contro di esso.

Claude Code utilizza qualsiasi modello che supererebbe il budget non espanso, e le sue parentesi graffe letterali non corrispondono a nessun file. Prima della v2.1.217, un valore paths con molti gruppi tra parentesi graffe bloccava o causava l'arresto anomalo della CLI all'avvio.

La sintassi Glob tratta [ come l'inizio di un'espressione tra parentesi quadre come [abc]. Un modello con un [ che non può essere letto come un'espressione tra parentesi quadre, come photos [2024/**, non è valido: non corrisponde a nulla, e gli altri modelli della regola continuano a funzionare. Per far corrispondere un [ letterale in un nome di file, sfuggitelo come photos \[2024/**. Prima della v2.1.207, un modello non valido causava il fallimento dello strumento Read per ogni file su cui la regola veniva valutata, invece di non corrispondere a nulla.

Riferimento frontmatter delle regole

Configurate una regola con il frontmatter YAML tra i marcatori --- all'inizio del file. paths è l'unico campo che Claude Code legge da una regola; qualsiasi altro campo viene ignorato senza errore. Claude Code rimuove il frontmatter prima di caricare la regola in contesto.

Se lo YAML tra i marcatori non viene analizzato, Claude Code ignora il frontmatter e carica la regola come se non avesse paths. Eseguite claude --debug per vedere l'errore di analisi.

Condividete le regole tra i progetti con symlink

La directory .claude/rules/ supporta symlink, quindi potete mantenere un set di regole condivise e collegarle in più progetti. I symlink circolari vengono rilevati e gestiti correttamente.

Claude Code tratta un symlink il cui target è al di fuori della vostra directory di lavoro come un'importazione esterna. Le regole collegate non si caricano finché non approvate le importazioni esterne per il progetto, e dopo di che solo quelle senza un campo paths si caricano. Claude Code chiede quell'approvazione solo quando un file di memoria di progetto importa un file al di fuori della directory di lavoro con @path, non per i symlink da soli. Per caricare le regole condivise senza quell'approvazione, mantenetele in ~/.claude/rules/, dove si applicano a ogni progetto sulla vostra macchina.

Questo esempio collega sia una directory condivisa che un file individuale:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Regole a livello di utente

Le regole personali in ~/.claude/rules/ si applicano a ogni progetto sulla vostra macchina. Utilizzatele per le preferenze che non sono specifiche del progetto:

~/.claude/rules/
├── preferences.md    # Le vostre preferenze di codifica personali
└── workflows.md      # I vostri flussi di lavoro preferiti

Claude Code carica le regole a livello di utente prima delle regole di progetto, quindi una regola di progetto appare più tardi nel contesto di Claude rispetto a una regola utente. Nessuno dei due set sostituisce l'altro: se una regola utente e una regola di progetto si contraddicono, Claude potrebbe seguire l'una o l'altra, quindi mantenete i due coerenti.

Gestite CLAUDE.md per i team di grandi dimensioni

Per le organizzazioni che distribuiscono Claude Code tra i team, potete centralizzare le istruzioni e controllare quali file CLAUDE.md vengono caricati.

Distribuite CLAUDE.md a livello organizzativo

Le organizzazioni possono distribuire un CLAUDE.md gestito centralmente che si applica a tutti gli utenti su una macchina. Questo file non può essere escluso dalle impostazioni individuali.

La chiave claudeMd vi permette di inserire il contenuto CLAUDE.md gestito direttamente all'interno di managed-settings.json invece di distribuire un file separato.

Ambito: ogni sessione di Claude Code sulla macchina, in ogni repository. Per la guida specifica del repository, eseguite il commit di un CLAUDE.md di progetto invece.

Precedenza: uguale a un file CLAUDE.md gestito. Si carica prima di CLAUDE.md utente e progetto.

Dove viene rispettato: solo impostazioni gestite e di politica. L'impostazione di claudeMd nelle impostazioni utente, progetto o locali non ha effetto.

L'esempio seguente aggiunge istruzioni comportamentali direttamente in un file di impostazioni gestite:

{
  "claudeMd": "Eseguite sempre `make lint` prima di eseguire il commit.\nNon eseguite mai il push direttamente su main."
}

Un CLAUDE.md gestito e impostazioni gestite servono a scopi diversi. Utilizzate le impostazioni per l'applicazione tecnica e CLAUDE.md per la guida comportamentale:

Le regole delle impostazioni vengono applicate dal client indipendentemente da ciò che Claude decide di fare. Le istruzioni CLAUDE.md modellano il comportamento di Claude ma non sono un livello di applicazione rigido.

Escludete file CLAUDE.md specifici

Nei grandi monorepo, i file CLAUDE.md antenati possono contenere istruzioni che non sono rilevanti per il vostro lavoro. L'impostazione claudeMdExcludes vi permette di saltare file specifici per percorso o modello glob.

Questo esempio esclude un CLAUDE.md di livello superiore e una directory di regole da una cartella padre. Aggiungitelo a .claude/settings.local.json in modo che l'esclusione rimanga locale alla vostra macchina:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

I modelli vengono confrontati con i percorsi di file assoluti utilizzando la sintassi glob. Potete configurare claudeMdExcludes a qualsiasi livello di impostazioni: utente, progetto, locale o politica gestita. Gli array si uniscono tra i livelli.

Per escludere un file di regole che raggiungete attraverso un symlink, sia che il file o la sua directory sia il link, scrivete il modello rispetto a uno dei due percorsi: il percorso del file sotto .claude/rules/ o il suo target di link. Un modello che corrisponde a uno dei due percorsi esclude il file. Prima della v2.1.239, solo un modello che corrispondeva al target del link escludeva il file.

I file CLAUDE.md della politica gestita non possono essere esclusi. Questo garantisce che le istruzioni a livello organizzativo si applichino sempre indipendentemente dalle impostazioni individuali.

AGENTS.md

Claude Code può leggere AGENTS.md come istruzioni del vostro progetto, quindi un repository già configurato per altri agenti di codifica funziona senza aggiungere un CLAUDE.md, un import o un'impostazione. Questa tabella mostra cosa Claude legge per impostazione predefinita per ogni combinazione di file di istruzioni nel vostro repository:

Per cambiare il valore predefinito, ad esempio per fare in modo che Claude legga sempre entrambi i file, legga solo CLAUDE.md, o legga solo le istruzioni gestite della vostra organizzazione, cambiate l'impostazione Project instructions.

When Claude Code reads AGENTS.md

Per impostazione predefinita, Claude legge AGENTS.md solo quando non avete nessun CLAUDE.md nella vostra directory di lavoro o sopra di essa. Ecco quali dei vostri file contano per quel controllo:

• Contano, quindi Claude li legge invece di AGENTS.md: un CLAUDE.md, .claude/CLAUDE.md, o CLAUDE.local.md nella vostra directory di lavoro o in qualsiasi directory sopra di essa
• Non contano, e continuano a caricarsi insieme a AGENTS.md: il vostro ~/.claude/CLAUDE.md, il CLAUDE.md gestito della vostra organizzazione, e i vostri file .claude/rules/

Quando nessuno conta, ecco cosa Claude legge e come potete dirlo:

• All'inizio della sessione: ogni AGENTS.md e .claude/AGENTS.md nella vostra directory di lavoro e nelle directory sopra di essa. In una sessione interattiva vedete una riga come no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md nella conversazione
• Mentre Claude lavora nelle sottodirectory: un AGENTS.md di una sottodirectory, quando Claude apre un file lì con lo strumento Read e quella sottodirectory non ha nessuno dei tre file CLAUDE.md propri
• All'interno di ogni AGENTS.md: gli import @path sono espansi, i pattern claudeMdExcludes si applicano, e i subagent che saltano le istruzioni del progetto saltano anche questi file
• Non letto: AGENTS.local.md, AGENTS.override.md, o qualsiasi cosa sotto una directory .agents/

Choose which instruction files load

Per cambiare quali file Claude legge, digitate /config in una sessione di Claude Code per aprire il pannello delle impostazioni, quindi impostate Project instructions su uno di questi valori:

Potete anche impostare il valore in un file di impostazioni invece di /config. Aggiungetelo sotto l'ID del plugin agents-md integrato in pluginConfigs, in ~/.claude/settings.json, un file --settings, o managed settings. Claude Code lo ignora nei file di impostazioni del progetto e locale. Questo esempio fa leggere a Claude entrambi i file:

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

Il vostro cambiamento si applica dal prossimo messaggio che inviate e in ogni nuova sessione.

When AGENTS.md support is unavailable

In queste sessioni Claude legge solo i file CLAUDE.md, e Project instructions non appare nel pannello delle impostazioni /config:

• Siete su una versione di Claude Code precedente a v2.1.277
• Voi o la vostra organizzazione avete disabilitato il plugin integrato agents-md in /plugin
• In alcuni casi, è la vostra prima sessione dopo aver aggiornato da v2.1.276 o precedente. Claude legge AGENTS.md dalla vostra prossima sessione

Prima di v2.1.281, alcune sessioni, come quelle su Amazon Bedrock o con telemetria disabilitata, leggevano solo i file CLAUDE.md. Su quelle versioni, aggiornate Claude Code. Per dare a Claude il vostro AGENTS.md in una qualsiasi di queste sessioni, importatelo da un CLAUDE.md.

Where AGENTS.md differs from CLAUDE.md

Un AGENTS.md che Claude legge attraverso l'impostazione Project instructions differisce da un CLAUDE.md in questi posti:

Remove an earlier AGENTS.md workaround

Se avete configurato Claude Code per leggere AGENTS.md prima che lo facesse da solo, ecco cosa fare con ogni configurazione comune:

• Un CLAUDE.md contenente @AGENTS.md: potete lasciarlo. Mantenere l'import non fa mai leggere AGENTS.md due volte a Claude, qualunque valore di Project instructions usiate. Rimuovete il CLAUDE.md se non contiene nient'altro, o mantenetelo se alcune delle vostre sessioni non possono caricare AGENTS.md direttamente.
• Un CLAUDE.md che dice a Claude a parole di leggere AGENTS.md: Claude vede AGENTS.md solo se decide di aprire il file. Eliminate il CLAUDE.md in modo che Claude legga AGENTS.md direttamente, o sostituite la frase con un import @AGENTS.md.
• Un CLAUDE.md con symlink a AGENTS.md: nulla, o eliminate il symlink. In entrambi i casi Claude legge il contenuto una volta.
• Un hook SessionStart che stampa AGENTS.md: rimuovetelo. Una volta che Claude legge AGENTS.md direttamente, l'hook aggiunge una seconda copia al contesto.

Share one file with other coding tools

Quando Claude non legge il vostro AGENTS.md direttamente, potete comunque mantenerlo come l'unico file che ogni strumento condivide mettendo un import @AGENTS.md in un CLAUDE.md accanto ad esso. Fatelo quando il vostro progetto ha anche un CLAUDE.md, quando avete impostato Project instructions su claude-md, o in sessioni che non possono caricare AGENTS.md. Aggiungete qualsiasi istruzione specifica di Claude sotto l'import, e Claude legge il file importato per primo, poi il resto:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Se non avete bisogno di contenuto specifico di Claude, un symlink funziona anche:

ln -s AGENTS.md CLAUDE.md

Il comando non stampa nulla in caso di successo. Prima di scegliere il symlink rispetto all'import, controllate questi vincoli:

• Modifica: Claude legge CLAUDE.md attraverso il link, ma gli strumenti Edit e Write rifiutano di scrivere attraverso un symlink, e il rifiuto dirige Claude a modificare il target del link, AGENTS.md, invece
• Windows: se voi o chiunque cloni il repository lavorate su Windows, usate l'import @AGENTS.md invece. Creare un symlink lì richiede privilegi di amministratore o modalità sviluppatore, e Git controlla un symlink committato come un file di testo semplice a meno che core.symlinks non sia abilitato, il che lascia quel clone con un CLAUDE.md di una riga al posto delle vostre istruzioni

Con entrambi gli approcci, eseguite /context nella vostra prossima sessione e confermate che CLAUDE.md appare sotto Memory files.

Migrate instructions from other tools

L'esecuzione di /init legge i file di istruzioni di altri strumenti e incorpora le parti rilevanti nel CLAUDE.md generato:

• Regole Cursor in .cursor/rules/ o .cursorrules
• Regole Copilot in .github/copilot-instructions.md
• Con CLAUDE_CODE_NEW_INIT=1 impostato: AGENTS.md, .devin/rules/, .windsurf/rules/ o .windsurfrules, e .clinerules

Potete anche eseguire /import per portare la configurazione di un agente di codifica supportato in Claude Code, che aggiunge una copia una tantum di file di istruzioni come AGENTS.md al CLAUDE.md corrispondente e trasporta i server MCP, i comandi, i subagent e le skills. Richiede Claude Code v2.1.213 o successivo.

Memoria automatica

La memoria automatica consente a Claude di accumulare conoscenze tra le sessioni senza che tu scriva nulla. Mentre lavora, Claude salva quattro tipi di note per se stesso. Claude registra il tipo come campo type nel frontmatter del file di memoria:

• user: il tuo ruolo, competenze e preferenze di lavoro
• feedback: correzioni che dai a Claude e approcci che confermi
• project: lavoro in corso, scadenze e decisioni che Claude non può derivare dal codice o dalla cronologia git
• reference: dove trovare informazioni al di fuori del progetto, come un issue tracker o una dashboard

Claude salta qualsiasi cosa possa derivare dalla codebase, come architettura, percorsi di file o correzioni di debug. Salta anche qualsiasi cosa i tuoi file CLAUDE.md dicono già.

Claude non salva qualcosa ogni sessione. Decide cosa vale la pena ricordare in base al fatto che l'informazione sarebbe utile in una conversazione futura.

Abilita o disabilita la memoria automatica

La memoria automatica è attivata per impostazione predefinita. Per attivarla/disattivarla, apri /memory in una sessione e usa l'interruttore di memoria automatica, che salva autoMemoryEnabled nelle impostazioni utente in ~/.claude/settings.json. Per disattivarla per un singolo progetto, imposta autoMemoryEnabled nelle impostazioni di quel progetto:

{
  "autoMemoryEnabled": false
}

Per disabilitare la memoria automatica tramite variabile di ambiente, imposta CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Posizione di archiviazione

Ogni progetto ottiene la propria directory di memoria in ~/.claude/projects/<project>/memory/. Il percorso <project> è derivato dal repository git, quindi tutti i worktrees e le sottodirectory all'interno dello stesso repo condividono una directory di memoria automatica. Al di fuori di un repository git, viene utilizzata la radice del progetto.

Se imposti CLAUDE_CODE_PROJECT_DIR_NAME accanto a CLAUDE_CONFIG_DIR, Claude Code utilizza quel nome come directory <project> sotto <config dir>/projects/ indipendentemente da quale repository avvii, quindi i progetti avviati con quella directory di configurazione condividono una directory di memoria automatica. Richiede Claude Code v2.1.234 o successivo.

Per archiviare la memoria automatica in una posizione diversa, imposta autoMemoryDirectory nel tuo settings.json. Viene letto da qualsiasi ambito di impostazioni: utente, progetto, locale, politica, o --settings.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

Il valore deve essere un percorso assoluto o iniziare con ~/.

Quando lo imposti nel .claude/settings.json o .claude/settings.local.json di un progetto, Claude Code lo rispetta secondo la stessa regola di trust dell'area di lavoro dei hook nei file di impostazioni. Mentre permissions.blockReadsOutsideWorkingDirectories è attivo, Claude Code non carica alcuna memoria automatica da una directory che un file di impostazioni fornito dal repository sceglie e non salva nulla in essa, ovunque si trovi quella directory.

La directory contiene un indice MEMORY.md e un file di argomento per memoria:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Indice, una riga per memoria, caricato in ogni sessione
├── user_role.md        # Una memoria
├── feedback_testing.md # Una memoria
└── ...                 # Qualsiasi altro file di argomento che Claude crea

MEMORY.md funge da indice della directory di memoria. Claude legge e scrive file in questa directory durante la tua sessione, usando MEMORY.md per tenere traccia di ciò che è archiviato dove.

La memoria automatica è locale alla macchina. Tutti i worktrees e le sottodirectory all'interno dello stesso repository git condividono una directory di memoria automatica. I file non vengono condivisi tra macchine o ambienti cloud.

Claude Code elimina i vecchi transcript di sessione dopo il periodo di conservazione cleanupPeriodDays, ma esclude i file di memoria nella directory di memoria da quella scansione di conservazione. MEMORY.md e i file di argomento rimangono fino a quando tu o Claude non li modificate o eliminate.

Come funziona

Le prime 200 righe di MEMORY.md, o i primi 25KB, a seconda di quale viene raggiunto per primo, vengono caricate all'inizio di ogni conversazione. Il contenuto oltre quella soglia non viene caricato all'inizio della sessione. Claude mantiene MEMORY.md conciso spostando le note dettagliate in file di argomento separati.

Dopo che Claude scrive in MEMORY.md, Claude Code misura il file rispetto ai limiti di lettura di 200 righe e 25KB. Se il file è vicino a un limite, Claude Code ricorda a Claude di accorciarlo: mantieni una riga per voce, sposta i dettagli nei file di argomento e unisci o elimina le voci obsolete. Se il file supera un limite, la scrittura ha comunque successo, ma Claude Code restituisce un errore che dice a Claude di riscrivere l'indice, perché tutto ciò che supera il limite viene eliminato al caricamento successivo.

Questo limite si applica solo a MEMORY.md. Claude Code carica un file CLAUDE.md fino a 4 MiB completamente e salta un file più grande. I file più brevi producono una migliore aderenza.

Claude Code non carica i file di argomento come user_role.md o feedback_testing.md all'avvio. Claude li legge su richiesta usando i suoi strumenti di file standard quando ha bisogno delle informazioni.

La memoria automatica della conversazione principale non viene caricata nei subagenti; l'eccezione è un fork, che eredita la conversazione padre e il prompt di sistema. La memoria automatica di un subagente, abilitata con il campo memory del subagente, è una directory separata.

Claude legge e scrive file di memoria durante la tua sessione. Quando vedi messaggi come "Saved 2 memories" o "Recalled 2 memories" nell'interfaccia di Claude Code, Claude sta attivamente aggiornando o leggendo da ~/.claude/projects/<project>/memory/.

Quando Claude scrive un file di memoria che inizia con frontmatter YAML, Claude Code registra l'ora di scrittura in un campo frontmatter modified come timestamp ISO 8601. Il timestamp mostra quanto è attuale il fatto, sia per te che per Claude quando lo legge di nuovo. Qualsiasi file che ha frontmatter ottiene il campo la prossima volta che Claude lo scrive, inclusi i file creati in versioni precedenti; Claude Code non aggiunge mai frontmatter a un file che non ne ha. Il campo modified richiede Claude Code v2.1.214 o successivo.

Controlla e modifica la tua memoria

I file di memoria automatica sono markdown semplice che puoi modificare o eliminare in qualsiasi momento. Esegui /memory per sfogliare e aprire i file di memoria da una sessione.

Visualizza e modifica con `/memory`

Il comando /memory elenca i tuoi file CLAUDE.md, CLAUDE.local.md e altri file di memoria in tutti gli ambiti utente e progetto, incluse le voci CLAUDE.md utente e progetto per i file che non esistono ancora. Ti consente inoltre di attivare o disattivare la memoria automatica e fornisce un'opzione per aprire la cartella di memoria automatica. Seleziona qualsiasi file per aprirlo nel tuo editor; selezionando uno che non esiste ancora lo crea prima. Per verificare quali file CLAUDE.md e file di regole sono stati caricati nella sessione corrente, esegui /context.

Gli editor GUI come VS Code aprono il file in una finestra separata e puoi continuare a utilizzare la sessione mentre è aperta. Prima della v2.1.216, /memory attendeva che chiudessi il file prima di rispondere. Gli editor terminali come Vim prendono il controllo del terminale fino a quando non esci.

Quando chiedi a Claude di ricordare qualcosa, come "usa sempre pnpm, non npm" o "ricorda che i test API richiedono un'istanza Redis locale", Claude lo salva nella memoria automatica. Per aggiungere istruzioni a CLAUDE.md, chiedi direttamente a Claude, come "aggiungi questo a CLAUDE.md", oppure modifica il file tu stesso tramite /memory.

Risolvi i problemi di memoria

Questi sono i problemi più comuni con CLAUDE.md e la memoria automatica, insieme ai passaggi per risolverli.

Claude non sta seguendo il mio CLAUDE.md

Il contenuto di CLAUDE.md viene consegnato come messaggio utente dopo il prompt di sistema, non come parte del prompt di sistema stesso. Claude lo legge e cerca di seguirlo, ma non c'è garanzia di conformità rigorosa, specialmente per istruzioni vaghe o conflittuali.

Per eseguire il debug:

• Esegui /context e controlla l'elenco sotto Memory files per verificare che i tuoi file CLAUDE.md e CLAUDE.local.md siano stati caricati. Se un file CLAUDE.md non è presente lì, Claude non può vederlo. Usa /memory per aprire e modificare i file.
• Verifica che il CLAUDE.md rilevante si trovi in una posizione che viene caricata per la tua sessione (vedi Scegli dove mettere i file CLAUDE.md).
• Rendi le istruzioni più specifiche. "Usa indentazione a 2 spazi" funziona meglio di "formatta il codice bene".
• Cerca istruzioni conflittuali tra i file CLAUDE.md. Se due file danno una guida diversa per lo stesso comportamento, Claude potrebbe sceglierne una arbitrariamente.

Se l'istruzione è qualcosa che deve essere eseguito in un punto specifico, come prima di ogni commit o dopo ogni modifica di file, scrivila come un hook. Gli hook vengono eseguiti come comandi shell in eventi del ciclo di vita fissi e si applicano indipendentemente da ciò che Claude decide di fare.

Per le istruzioni che vuoi a livello di prompt di sistema, usa --append-system-prompt. Questo deve essere passato al lancio, quindi è più adatto a script e automazione che all'uso interattivo. Per come si comporta quando riprendi una conversazione, vedi System prompt flags in resumed conversations.

Il mio AGENTS.md non sta caricando

Se il tuo repository ha un AGENTS.md e Claude non sembra sapere cosa dice, la causa solita è un CLAUDE.md da qualche parte nel percorso del progetto. Per impostazione predefinita Claude legge AGENTS.md solo quando non hai alcun CLAUDE.md o CLAUDE.local.md nella tua directory di lavoro o sopra di essa. Controlla questi in ordine:

1. Cerca un CLAUDE.md, .claude/CLAUDE.md, o CLAUDE.local.md nella tua directory di lavoro o in qualsiasi directory sopra di essa, diversa dal tuo ~/.claude/CLAUDE.md. Se ne trovi uno, Claude lo legge invece di AGENTS.md a meno che tu non imposti Project instructions su claude-md-and-agents-md.
2. Esegui claude --version e conferma v2.1.277 o successivo. Prima della v2.1.281, alcune sessioni, come quelle su Amazon Bedrock o con telemetria disabilitata, non potevano caricare AGENTS.md, quindi su quelle versioni aggiorna a v2.1.281 o successivo.
3. Digita /config nella tua sessione per aprire il pannello delle impostazioni e conferma che Project instructions non è impostato su claude-md o managed-only. Se non vedi affatto l'impostazione lì, la tua sessione è una che non può caricare AGENTS.md.

Per verificare se Claude ha letto il tuo AGENTS.md, esegui /memory e cerca il suo percorso nell'elenco.

Prima della v2.1.280, /memory e /context non elencavano un AGENTS.md che Claude leggeva direttamente. Su quelle versioni, chiedi a Claude quali sono le sue istruzioni di progetto.

Se vuoi mantenere il CLAUDE.md che hai trovato, o la tua sessione non può caricare AGENTS.md, aggiungi un CLAUDE.md accanto al tuo AGENTS.md che lo importa.

Non so cosa ha salvato la memoria automatica

Esegui /memory e seleziona la cartella di memoria automatica per sfogliare ciò che Claude ha salvato. Tutto è markdown semplice che puoi leggere, modificare o eliminare.

Il mio CLAUDE.md è troppo grande

I file con più di 200 righe consumano più contesto e possono ridurre l'aderenza. Claude Code salta un file superiore a 4 MiB. Usa regole con ambito di percorso per caricare istruzioni solo quando Claude lavora con file corrispondenti, oppure riduci il contenuto che non è necessario in ogni sessione. La divisione in importazioni @path aiuta l'organizzazione ma non riduce il contesto, poiché i file importati vengono caricati all'avvio.

Il controllo /doctor propone riduzioni per un CLAUDE.md archiviato: taglia il contenuto che Claude può derivare dalla base di codice, come layout di directory, elenchi di dipendenze e panoramiche dell'architettura, e mantiene i rischi, la logica e le convenzioni che differiscono dai valori predefiniti dello strumento. Il controllo di riduzione richiede Claude Code v2.1.206 o successivo.

Le istruzioni sembrano perse dopo `/compact`

CLAUDE.md di progetto sopravvive alla compattazione: dopo /compact, Claude rilegge il tuo CLAUDE.md dal disco e lo reinetta nella sessione. I file CLAUDE.md annidati nelle sottodirectory e le regole con frontmatter paths: vengono ricaricati quando Claude legge i file a cui si applicano.

Se un'istruzione è scomparsa dopo la compattazione, è stata data solo nella conversazione, si trova in un CLAUDE.md annidato che non è stato ancora ricaricato, oppure è una regola con ambito di percorso che non ha corrisposto a un file da allora. Aggiungi istruzioni solo per conversazione a CLAUDE.md per farle persistere. Vedi Cosa sopravvive alla compattazione per il breakdown completo.

Vedi Scrivi istruzioni efficaci per una guida su dimensione, struttura e specificità.

Risorse correlate

• Esegui il debug della tua configurazione: diagnostica perché CLAUDE.md o le impostazioni non hanno effetto
• Skills: pacchetto di flussi di lavoro ripetibili che si caricano su richiesta
• Impostazioni: configura il comportamento di Claude Code con file di impostazioni
• Memoria subagent: consenti ai subagents di mantenere la propria memoria automatica