CLAUDE.md spiegato: insegna il tuo progetto a Claude Code una volta sola

Ogni nuova sessione di Claude Code parte con la testa vuota. Gli dici di usare pnpm, non npm. Gli dici dove stanno i test. Gli dici di non toccare la cartella generata. Domani gli dirai di nuovo tutto questo.

È un semplice file di testo in Markdown. Claude Code lo legge all'inizio di ogni sessione, quindi ciò che contiene è già noto prima del tuo primo prompt. Questa guida mostra dove metterlo, come scriverne uno che Claude segua e cosa tenerne fuori.

Cos'è CLAUDE.md e cosa non è

Ogni sessione di Claude Code inizia con una finestra di contesto nuova. Due meccanismi portano la conoscenza da una sessione alla successiva:

Entrambi vengono caricati come contesto. Questa parola conta: Claude legge CLAUDE.md e cerca di seguirlo, ma non è un'impostazione imposta con la forza. Una riga vaga o contraddittoria può essere ignorata. Ci torniamo nella sezione sulla risoluzione dei problemi, perché da questo dipende come devi scrivere il file.

Dove va il file

I posti sono quattro, e si sovrappongono. Claude li carica dall'ambito più ampio al più specifico, quindi ciò che è più vicino al tuo progetto viene letto per ultimo.

I due che userai sono il file di progetto e il file utente.

• File di progetto. Metti CLAUDE.md nella radice del progetto, o in una cartella .claude nella radice. Fai il commit, così chiunque lavori al progetto riceve le stesse istruzioni. Scrivi ciò che vale per chiunque: comandi di build, convenzioni, struttura del progetto.
• File utente. ~/.claude/CLAUDE.md ti segue in ogni progetto. Usalo per le abitudini personali, per esempio come preferisci che vengano formulate le spiegazioni.
• File locale. CLAUDE.local.md serve per appunti tuoi e specifici di un progetto, come l'URL di un ambiente di prova. Aggiungilo al .gitignore così non finisce nel commit.

Claude cerca anche nella cartella da cui l'hai avviato e in tutte quelle sopra. Se parti da foo/bar/, carica foo/bar/CLAUDE.md e foo/CLAUDE.md. I file nelle cartelle sotto di te vengono caricati dopo, su richiesta, la prima volta che Claude legge o modifica un file in quella sottocartella.

Inizia con /init

Non devi scrivere a mano la prima versione. Dentro una sessione, esegui:

> /initAnalisi del codice in corso...Creato CLAUDE.md con i comandi di build, le istruzioni sui test e le convenzioni trovate.

Claude Code legge il tuo progetto e scrive un CLAUDE.md con i comandi di build e test e le convenzioni che scopre. Se esiste già un CLAUDE.md, /init suggerisce miglioramenti invece di sovrascriverlo. Considera il risultato una prima bozza. Il tuo compito è aggiungere ciò che Claude non poteva scoprire da solo.

Per confermare che il file sia stato caricato, esegui /context in una sessione e guarda sotto Memory files.

Cosa va nel file

Un buon test, prima di scrivere qualsiasi riga, ha due domande:

Se entrambe le risposte sono sì, lascia fuori la riga. Resta l'informazione che non è mai stata nel codice, o che costa tempo vero riscoprire:

Aggiungi una riga quando Claude fa lo stesso errore per la seconda volta, quando una revisione del codice individua qualcosa che avrebbe dovuto sapere, o quando scrivi la stessa correzione della sessione scorsa. È il segnale che quel fatto appartiene al file.

Un esempio da copiare

Ecco un breve file di progetto. Nota come ogni riga sia qualcosa che potresti verificare, e quanto poco descriva l'architettura.

# Project notes

## Commands
- Install: pnpm install (never npm or yarn)
- Dev server: pnpm dev (port 3000)
- Tests: pnpm test -- --run, run before every commit
- Typecheck: pnpm typecheck, must pass before a pull request

## Conventions
- 2-space indentation, double quotes
- API handlers live in src/api/handlers/
- Do not edit anything in src/gen/, it is generated by pnpm codegen

## Gotchas
- Integration tests need a local Redis: docker compose up redis
- Dates are stored in UTC, formatted only in the UI layer

Sono 15 righe, e ognuna si è guadagnata il suo posto.

Come scrivere righe che Claude segue

Poiché CLAUDE.md è contesto e non configurazione, il modo in cui formuli una riga decide se verrà seguita. Scrivi istruzioni abbastanza concrete da poter essere verificate.

Poi mantieni il file in forma:

• Breve. Punta a meno di 200 righe per file. I file più lunghi usano più contesto e Claude li segue con meno affidabilità.
• Organizzato. Raggruppa le righe correlate sotto titoli ed elenchi Markdown. Claude segue meglio la struttura che i paragrafi densi.
• Coerente. Se due righe sono in disaccordo, Claude può sceglierne una a caso. Rileggi i tuoi file ogni tanto, anche quelli nelle sottocartelle, e cancella ciò che è superato.

Per far controllare a Claude i tuoi file di istruzioni alla ricerca di righe superate o in conflitto, esegui /doctor prompt-audit. Riporta i risultati e propone modifiche, senza cambiare nulla finché non lo chiedi. Richiede Claude Code 2.1.283 o successivo.

Importare altri file

CLAUDE.md può includere altri file con una @ davanti al percorso. Il file importato viene caricato insieme al CLAUDE.md che lo cita.

See @README for the project overview and @package.json for the npm commands.

# Additional instructions
- git workflow: @docs/git-instructions.md

I percorsi relativi si risolvono a partire dal file che contiene l'importazione. Le importazioni possono a loro volta importare altri file, fino a quattro livelli di profondità. La @ viene letta solo fuori dagli spazi di codice, quindi racchiudi un percorso tra apici inversi se vuoi citarlo senza importarlo.

Le importazioni servono a organizzare, ma non riducono il contesto: i file importati vengono comunque caricati per intero. Per istruzioni personali che vuoi in più copie dello stesso repository, importa un file dalla tua cartella home, come @~/.claude/my-project-instructions.md. La prima volta che un progetto importa un file da fuori la directory di lavoro, Claude Code chiede la tua approvazione.

Quando un file diventa troppo lungo

A un certo punto il file cresce oltre ciò che serve a ogni sessione. Hai quattro strumenti, ciascuno per un compito diverso.

Regole circoscritte a certi file

Metti un file Markdown per argomento in .claude/rules/, come testing.md o api-design.md. Per far valere una regola solo per certi file, aggiungi un campo paths in cima:

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

# API rules

- Every endpoint validates its input
- Use the standard error response format

Una regola senza paths si carica a ogni sessione. Una circoscritta si carica quando Claude legge o modifica un file corrispondente, il che toglie le istruzioni di mezzo nel resto del tempo.

Se un blocco di CLAUDE.md è una procedura in più passaggi, come preparare un rilascio, spostalo in una competenza (skill). Le competenze si caricano solo quando vengono usate.

Memoria automatica: gli appunti che Claude tiene per sé

Oltre al file che scrivi tu, Claude Code può tenere appunti per conto suo. La memoria automatica è attiva per impostazione predefinita nelle sessioni locali. Mentre lavora, Claude salva quattro tipi di appunti: su di te (ruolo e preferenze), sui riscontri (correzioni e approcci che hai confermato), sul progetto (decisioni e scadenze non visibili nel codice) e sui riferimenti (dove trovare cose fuori dal progetto).

Non salva ciò che può leggere dal codice, né ciò che il tuo CLAUDE.md già dice. Vedrai messaggi come "Saved 2 memories" nella sessione. Gli appunti sono semplice Markdown sotto ~/.claude/projects/, e le prime 200 righe o 25 KB del file indice vengono caricate all'inizio di ogni sessione.

Esegui /memory per vedere ogni file di istruzioni e la cartella della memoria automatica, aprirli nel tuo editor e attivare o disattivare la memoria automatica. Se dici a Claude "always use pnpm, not npm", lo salva nella memoria automatica. Per metterlo invece in CLAUDE.md, dillo: "add this to CLAUDE.md".

Dentro Claude Tutorial

Scrivere ciò che altrimenti ripeteresti

Trasformare la stessa correzione in un'istruzione permanente è un'abitudine che rende in qualsiasi lavoro con Claude, non solo nel codice, ed è una che l'app insegna passo dopo passo.

In arrivo

Scarica suApp Store

DISPONIBILE SUGoogle Play

Quando Claude non lo segue

Procedi in quest'ordine. Risolvono la maggior parte dei casi.

Vale la pena conoscere altri due casi. Dopo un /compact, il CLAUDE.md nella radice del progetto viene riletto dal disco, quindi sopravvive. Un'istruzione data solo in conversazione non sopravvive, quindi spostala nel file. E quando un CLAUDE.md in una sottocartella è molto lungo (oltre circa 40.000 caratteri in una finestra di contesto più piccola), Claude ne riceve solo l'inizio, quindi tienili brevi.

Domande frequenti

Dove metto CLAUDE.md?

Nella radice del progetto (./CLAUDE.md) o in ./.claude/CLAUDE.md. Metti le preferenze personali per tutti i progetti in ~/.claude/CLAUDE.md. Usa ./CLAUDE.local.md, aggiunto al .gitignore, per appunti privati su un progetto.

Quanto deve essere lungo un CLAUDE.md?

Punta a meno di 200 righe. Se le superi, Claude Code mostra un avviso all'avvio e in /status. Sposta le parti specifiche di un'area in regole circoscritte e taglia ciò che Claude può leggere dal codice.

CLAUDE.md è la stessa cosa di un prompt di sistema?

No. CLAUDE.md viene consegnato come messaggio dopo il prompt di sistema. Claude cerca di seguirlo, ma non c'è garanzia di rispetto rigoroso. Per istruzioni che devono valere ogni volta, usa un hook o una regola di permessi.

Devo fare il commit di CLAUDE.md in git?

Sì per il file di progetto, così lo condivide tutto il team e migliora a ogni correzione. No per CLAUDE.local.md, che è personale.

Claude legge CLAUDE.md nelle sottocartelle?

Sì, su richiesta. Carica il file di una sottocartella la prima volta che Claude legge o modifica un file in quella cartella, e mostra una riga Loaded con il percorso.

Che differenza c'è tra CLAUDE.md e una competenza?

CLAUDE.md è per i fatti necessari in ogni sessione. Una competenza (skill) è una procedura o un manuale che si carica solo quando viene invocata o è pertinente, quindi non occupa spazio nel resto del tempo.

La tua checklist per CLAUDE.md

Continua a leggere

• Claude Code per principianti: installa, accedi ed esegui il tuo primo compito se non hai ancora avviato una sessione.
• Buone pratiche per Claude Code: abitudini che migliorano i risultati per prompt, controlli e gestione del contesto.
• Le modalità di permessi di Claude Code e la modalità Plan, spiegate per decidere cosa Claude può fare senza chiedere.
• Progetti di Claude: il contesto che resta per la stessa idea nell'app Claude: istruzioni permanenti conservate in un progetto.