Passa al contenuto principale

CLAUDE.md e file di memoria

Principiante

Se fai una sola cosa per migliorare Claude Code, fai questa. CLAUDE.md è un file di testo semplice che Claude legge all'inizio di ogni sessione: il briefing permanente del tuo progetto.

What you'll learn
  • Perché CLAUDE.md è l'impostazione di Claude Code con il maggior impatto
  • Come si carica la gerarchia della memoria, dalla policy gestita fino a CLAUDE.local.md
  • In cosa l'auto-memoria è diversa dal CLAUDE.md che scrivi tu
  • Come generare un file di partenza con /init e snellirlo
  • Cosa va in CLAUDE.md e cosa tenerne fuori
  • Come gli @import ti permettono di riferire documenti senza duplicarli

Perché è l'impostazione con il maggior impatto​

Senza di esso, devi rispiegare il tuo progetto a ogni sessione ("usiamo pnpm, i test sono in __tests__, non toccare /generated…"). Con esso, Claude lo sa già. Buone istruzioni qui migliorano ogni interazione futura in un colpo solo.

La gerarchia della memoria​

Claude Code carica la memoria da diverse posizioni e le fonde nell'ordine di caricamento, partendo dall'ambito più ampio: così un'istruzione di progetto entra nel contesto dopo un'istruzione utente.

  • Policy gestita — istruzioni a livello di organizzazione che distribuisce il tuo team IT/DevOps. Il percorso dipende dal sistema operativo: /Library/Application Support/ClaudeCode/CLAUDE.md su macOS, /etc/claude-code/CLAUDE.md su Linux e WSL, C:\Program Files\ClaudeCode\CLAUDE.md su Windows.
  • Istruzioni utente (~/.claude/CLAUDE.md) — le tue preferenze personali su ogni progetto.
  • Istruzioni di progetto (./CLAUDE.md oppure ./.claude/CLAUDE.md, sotto commit) — come funziona questo repo. Condivise con il tuo team. Se il tuo repo usa AGENTS.md, quello può caricarsi al posto di questi file o insieme a essi.
  • Istruzioni locali (./CLAUDE.local.md) — note specifiche del progetto solo per te, come l'URL di un ambiente sandbox. Aggiungilo a .gitignore.

I file nella gerarchia di cartelle sopra la tua directory di lavoro vengono caricati all'avvio; i file nelle sottocartelle vengono caricati su richiesta, quando Claude mette mano a qualcosa in quell'area.

Pro tip
  • Un solo file non ti basta più? Spezza le istruzioni in .claude/rules/*.md, un argomento per file, scoperti ricorsivamente. Le regole senza frontmatter paths si caricano all'avvio con la stessa priorità di .claude/CLAUDE.md; aggiungi il frontmatter paths per caricare una regola solo quando Claude lavora su file corrispondenti, e risparmi contesto.
Conosci i tuoi livelli di memoria
Premi Invio o Spazio per girare la carta. Usa le frecce sinistra e destra per spostarti tra le carte.Termine mostrato.
1 / 6

L'altra metà: l'auto-memoria​

CLAUDE.md è la metà della memoria che scrivi tu. Claude Code tiene anche un'auto-memoria: note che Claude scrive da sé partendo dalle tue correzioni e preferenze, salvate per repository e caricate in ogni sessione insieme ai tuoi file CLAUDE.md.

File CLAUDE.mdAuto-memoria
Chi la scriveTuClaude
Cosa contieneIstruzioni e regoleApprendimenti e pattern
AmbitoProgetto, utente od organizzazionePer repository, condivisa tra i worktree

Entrambe sono contesto, non imposizione: Claude le tratta come indicazioni da soppesare, non come configurazione a cui deve obbedire. Per bloccare in modo assoluto un'azione, a prescindere da ciò che Claude decide, usa invece un hook PreToolUse.

Watch out
  • L'auto-memoria carica solo le prime 200 righe o 25 KB: un MEMORY.md gonfio viene troncato silenziosamente. Vedi Audit del budget di contesto per il dettaglio completo dei costi di avvio.

Genera un punto di partenza​

Guided walkthrough1 of 3
  1. Claude ispeziona il codice e redige un CLAUDE.md per te in automatico.

Genera una bozza di CLAUDE.md

/init

Recupera uno starter già pronto da Template CLAUDE.md.

Cosa metterci dentro​

  • Cos'è il progetto, in due frasi.
  • Lo stack tecnologico e come eseguire / testare / fare il lint.
  • Convenzioni che Claude non può dedurre (nomenclatura, struttura, stile dei commit).
  • Protezioni: "esegui i test prima di dichiarare concluso", "non modificare mai /vendor", "non committare mai segreti".

Cosa NON metterci dentro​

Watch out
  • Claude segue CLAUDE.md alla lettera: istruzioni obsolete, vaghe o velleitarie fanno attivamente danni.
  • Descrivi come il progetto funziona realmente oggi; breve e veritiero batte lungo e ambizioso.
  • Evita documenti incollati giganteschi (usa invece gli @import), i segreti e le regole che in realtà non segui.
  • Rivedilo periodicamente in modo che resti accurato man mano che il progetto evolve.

Import​

Includi i documenti esistenti invece di duplicarli: ad esempio, riferisci la tua guida di stile con un import @path/to/file così da avere un'unica fonte autorevole. Funzionano sia i percorsi relativi sia quelli assoluti; i percorsi relativi si risolvono rispetto al file che contiene l'import, non rispetto alla tua directory di lavoro. I file importati possono importarne altri, fino a una profondità massima di quattro passaggi.

Due trappole di sintassi da conoscere prima che ti mordano:

  • Gli spazi vogliono il backslash. @Design\ Docs/api-conventions.md funziona; senza il backslash il percorso si ferma al primo spazio. Racchiuderlo tra virgolette non importa il file per niente.
  • I backtick escludono l'import. L'analisi degli import salta i code span e i blocchi di codice, quindi `@README` resta testo letterale mentre @README da solo importa il file. È così che menzioni un percorso senza caricarlo.

Vedi la documentazione ufficiale sulla memoria per il riferimento completo.

Pro tip
  • Un'unica fonte autorevole: riferisci un file con gli @import invece di incollarne il contenuto in CLAUDE.md.
  • Se un documento esiste già, collegalo: non copiarlo. Le copie si disallineano col tempo.

Mettiti alla prova​

Mettiti alla prova

0/6
  1. Quale file legge Claude Code all'inizio di ogni sessione come briefing permanente del tuo progetto?
  2. Cosa fa l'esecuzione di /init in un progetto?
  3. Qual è il modo consigliato per includere un documento esistente di grandi dimensioni come una guida di stile?
  4. Dove vanno le note personali specifiche del progetto, quelle che non vuoi mettere sotto commit?
  5. Chi scrive l'auto-memoria?
  6. Un CLAUDE.md in una sottocartella si carica quando?
Key takeaways
  • CLAUDE.md è l'impostazione con il maggior impatto: migliora ogni sessione futura in un colpo solo.
  • La memoria si carica dall'ambito più ampio al più stretto: policy gestita, poi utente (~/.claude/CLAUDE.md), progetto (./CLAUDE.md oppure ./.claude/CLAUDE.md), poi locale (./CLAUDE.local.md). I file nelle sottocartelle si caricano su richiesta.
  • L'auto-memoria è l'altra metà: le note che Claude scrive da sé, per repository, caricate a ogni sessione. Entrambe sono contesto, non imposizione: per bloccare qualcosa in modo assoluto usa un hook.
  • Un solo file non ti basta più? Spezzalo in .claude/rules/*.md e delimita le regole con il frontmatter paths.
  • Inizia con /init, poi snellisci la bozza fino a ciò che è davvero vero.
  • Tienilo breve e veritiero: usa gli @import (massimo quattro passaggi) per i documenti grandi e non committare mai segreti.

Avanti​