Come scrivere un file CLAUDE.md che guida davvero Claude Code

Il file CLAUDE.md raccoglie le istruzioni che Claude Code legge all'inizio di ogni sessione. Se lo scrivi bene, Claude smette di tirare a indovinare il comando di build, le convenzioni e la struttura del progetto. Se lo gonfi, Claude ignora in silenzio proprio le regole che avevi scritto per governarlo. Alla fine di questa guida hai un CLAUDE.md snello che Claude segue al primo colpo, e un metodo per farlo crescere senza trasformarlo in una documentazione che nessuno legge.

Cos'è davvero CLAUDE.md, e cosa non è

CLAUDE.md è un file Markdown che entra nella finestra di contesto in automatico all'avvio di Claude Code. Non è documentazione e non è un wiki. È un file di iniezione di contesto: ogni riga si contende l'attenzione del modello con il lavoro che ha davanti.

Claude Code risale dalla cartella di lavoro fino alla radice del repository e carica ogni CLAUDE.md che incontra, quindi i file si sommano per ambito. La documentazione ufficiale sulla memoria fissa l'ordine di precedenza: prima la policy aziendale, poi la memoria di progetto (./CLAUDE.md), poi la memoria utente (~/.claude/CLAUDE.md), infine le eccezioni locali (./CLAUDE.local.md). I file nelle sottocartelle sotto la cartella di lavoro non si caricano all'avvio: entrano nel contesto solo quando Claude legge un file di quella sottocartella durante la sessione.

La cosa conta perché il contesto è limitato. Man mano che le istruzioni aumentano, la qualità con cui Claude le segue cala su tutto il fronte, non solo sulle regole nuove. Un file che vuole dire tutto finisce per far rispettare niente.

Cosa ti serve prima di iniziare

• Claude Code installato e un progetto aperto nel terminale.
• Una breve lista dei comandi che usi di più: build, test, lint, controllo dei tipi.
• Le tre o quattro convenzioni che un nuovo sviluppatore sbaglierebbe il primo giorno.
• Dieci minuti. Un buon CLAUDE.md è corto per scelta.

Passo 1: genera una base con /init

Non scrivere il file da zero. Lancia /init nella radice del progetto. Claude esplora il codice con un subagente, colma i vuoti con qualche domanda e propone un CLAUDE.md che rivedi prima che scriva qualsiasi cosa. Tratta il risultato come una prima stesura. Include di proposito più del necessario, e il tuo compito nel passo dopo è tagliare.

Passo 2: togli tutto ciò che Claude può dedurre

Leggi ogni riga generata e applica un solo test: se la cancello, Claude sbaglia? Se la risposta è no, cancellala. Claude legge da solo il tuo package.json, i nomi delle cartelle e gli import. Non gli serve un paragrafo che spiega che usi React o che i componenti stanno in src/components. Tieni solo i fatti che cambiano le decisioni e che non si deducono dal codice: lo step di build non ovvio, la convenzione che contraddice il default del framework, la cartella che sembra sicura da modificare ma è generata.

La lunghezza è l'indicatore indiretto. Il CLAUDE.md di radice di HumanLayer, un team che lavora molto con Claude Code, sta sotto le sessanta righe. Una regola pratica diffusa tiene un file ad alto segnale tra le 80 e le 120 righe. Oltre le 200 circa, Claude non riesce a reggere ogni istruzione mentre lavora.

Passo 3: scrivi regole positive e universali

Due regole di formulazione spostano l'aderenza più di qualsiasi ritocco alla struttura. Primo: scrivi cosa fare, non cosa evitare. "Usa le utility del design system per le spaziature" batte "non scrivere i margini a mano": Claude segue le istruzioni positive meglio delle negazioni. Secondo: tieni ogni regola universale. CLAUDE.md entra in ogni sessione, quindi una regola su come costruire una singola tabella del database è rumore nelle sessioni che toccano altro. Sposta le indicazioni situazionali nei file a cui si riferiscono e lascia nel file di radice solo le regole valide ovunque.

Raggruppa le regole affini sotto intestazioni Markdown e usa gli elenchi, non la prosa. La gerarchia delle intestazioni non è decorazione: i modelli la sfruttano per trovare il blocco giusto, e i punti imperativi si leggono meglio dei paragrafi.

Passo 4: dividi per ambito e importa il resto

Abitudini personali e standard di squadra non stanno nello stesso file. Metti le preferenze valide su tutta la macchina, come vuoi scritti i messaggi di commit, in ~/.claude/CLAUDE.md, così si caricano in ogni progetto. Metti i fatti specifici del progetto e condivisi dal team nel ./CLAUDE.md versionato. Metti tutto ciò che è privato o sperimentale in ./CLAUDE.local.md, che resta fuori dal controllo di versione.

Quando il file di progetto inizia a dilagare, dividilo. CLAUDE.md supporta la sintassi di import @percorso/al/file, così un file di radice corto richiama @.claude/testing.md o @.claude/api-conventions.md e dà a ogni tema un suo responsabile. Un avvertimento onesto: i file importati si caricano comunque all'avvio e pesano sulla finestra di contesto, quindi gli import comprano leggibilità e ordine, non un contesto più leggero. Tieni snello il totale, comunque tu lo distribuisca.

Passo 5: sposta i controlli fissi negli hook, non nella prosa

Alcune regole devono scattare in un momento preciso: formatta dopo ogni modifica, controlla il lint prima di ogni commit, non scrivere mai in una cartella generata. Una riga di CLAUDE.md che lo chiede prima o poi viene saltata, perché il modello decide a ogni turno se rispettarla. Gli hook non decidono. Girano come comandi di shell in eventi fissi del ciclo di vita, qualunque cosa faccia Claude. Se una regola è meccanica e non negoziabile, va in un hook, non nella prosa. Il modello a eventi lo spieghiamo nella guida agli hook di Claude Code.

Passo 6: fallo crescere per reazione, non per previsione

Il modo più rapido per gonfiare un CLAUDE.md è caricarlo in anticipo di ogni regola che immagini di dover usare. Fai il contrario. Parti minimale e aggiungi una regola solo dopo che Claude ha commesso lo stesso errore due volte. Una regola nata da un errore vero vale la sua riga. Una regola aggiunta per previsione è una tassa di contesto che paghi a ogni sessione per uno sbaglio che magari non arriva mai. Le versioni recenti di Claude Code tengono anche una memoria automatica: Claude scrive da solo appunti su comandi di build e correzioni mentre lavora, e questo riduce quanto devi curare a mano.

Come capisci se il tuo CLAUDE.md funziona

Due prove veloci. Prima: apri una sessione nuova e chiedi a Claude di riassumere le regole di progetto che sta seguendo. Se salta una regola che avevi scritto, o è sepolta o il file è troppo lungo. Seconda: guarda le correzioni che si ripetono. Se ti ritrovi a rispiegare la stessa cosa sessione dopo sessione, quel fatto va nel file. Se invece stai correggendo Claude perché applica una regola alla lettera nel contesto sbagliato, quella regola non era universale e va tolta dalla radice.

Guasti frequenti e rimedi

• Claude ignora regole scritte in chiaro. Il file è troppo lungo. Portalo verso le 120 righe e i superstiti vengono rispettati.
• Una regola funziona in un progetto e sbaglia in un altro. Sta in ~/.claude/CLAUDE.md ma dovrebbe essere di progetto, o il contrario. Spostala nel livello giusto.
• Una regola di formattazione o di lint viene sempre saltata. La prosa non garantisce un'azione a punto fisso. Trasformala in un hook.
• Il file è arrivato a 400 righe e nessuno si fida. Dividi per tema con gli import, cancella tutto ciò che è deducibile e fai rispettare le parti dure con gli hook.

Per andare oltre

Il CLAUDE.md è un pezzo di un setup di Claude Code che funziona. Una volta che il file è snello, le leve successive sono i pattern di lavoro che usi ogni giorno e il capire quando una skill si merita il suo posto e quando è solo peso. Il file guida il comportamento, gli hook lo fanno rispettare, skill e workflow lo scalano.