Il 95% delle persone usa Claude Code senza questo file. Ecco cosa si perdono.

Ho testato decine di configurazioni di Claude Code.

L'unica cosa che ha davvero cambiato i miei risultati: un file di 60 righe chiamato CLAUDE.md.

Tieni traccia di questa guida 🔖

Ecco esattamente come funziona, perché la maggior parte delle persone lo ignora completamente, e il template completo che puoi copiare oggi:

Quello che nessuno ti dice su Claude Code

Prima del tuo primo prompt. Prima di una singola riga di codice. Prima che accada qualsiasi cosa nella tua sessione.

Claude legge un solo file. Uno soltanto.

CLAUDE.md.

E lo considera la verità assoluta per l'intera sessione. Non come un suggerimento. Non come contesto tra gli altri. Ma come il brief definitivo che inquadra ogni decisione che prenderà.

Ecco perché questo file è la variabile più sottovalutata nell'intero stack di Claude Code.

La maggior parte delle persone non ce l'ha affatto. E quelli che ce l'hanno hanno commesso uno di due errori: o il file è privo di sostanza, o è lungo 300 righe del tipo "sii un ingegnere senior esperto che pensa passo dopo passo."

Entrambi sono inutili. Per ragioni diverse.

Perché la maggior parte dei file CLAUDE.md non funziona: i 3 veri motivi

Motivo 1: Troppo lungo

Claude può seguire in modo affidabile circa 150-200 istruzioni per sessione. Questo è un vincolo strutturale, non una questione di buona volontà.

Problema: Il prompt di sistema interno di Claude Code contiene già circa 50 istruzioni. Ciò significa che il tuo CLAUDE.md ha effettivamente da 100 a 150 slot di istruzioni prima che Claude inizi a perderle.

Se il tuo file è lungo 200 righe, Claude non ignora le tue regole di proposito. Le dimentica meccanicamente. Non hai un problema di conformità. Hai un problema di budget attentivo.

Motivo 2: Contenuto scadente

La maggior parte dei file CLAUDE.md è piena di cose che Claude può dedurre da solo o che non cambiano il suo comportamento in modo misurabile.

• "Comportati come un ingegnere senior." → Claude sa già cosa significa e non ancora nessun comportamento specifico.
• "Pensa passo dopo passo." → Questo è già nel suo addestramento. Stai sprecando una riga.
• "Scrivi codice pulito e manutenibile." → Nessun criterio concreto. Claude non sa cosa significhi "pulito" nel tuo contesto specifico.

Ogni riga che non previene un errore specifico e concreto è una riga rubata a istruzioni che contano davvero. Il test è semplice: se elimini questa riga, Claude sbaglierà qualcosa di specifico? Se la risposta è no, la riga non dovrebbe essere lì.

Motivo 3: Zero gerarchia

La maggior parte delle persone ignora che ci sono tre livelli di istruzioni in Claude Code, e infilano tutto nello stesso posto.

• ~/.claude/CLAUDE.md → Globale (si applica a tutti i tuoi progetti)
• .claude/CLAUDE.md → Progetto (condiviso con il team, in git)
• ./CLAUDE.local.md → Locale (override personali, gitignorati)

Il livello globale è per le regole che ripeteresti in ogni progetto. Il livello progetto è per il contesto specifico del tuo stack e del tuo team. Il livello locale è per le tue preferenze personali che non devono essere condivise.

Usare correttamente i tre livelli è ciò che mantiene ogni file corto, focalizzato e veramente efficace. Mettere tutto in un unico file è come costruire un imbuto per annegare le tue regole importanti nel rumore.

Le 5 sezioni che compongono un CLAUDE.md efficace

Dopo aver setacciato dozzine di file CLAUDE.md in produzione—progetti open-source, documenti ufficiali di Anthropic, repository di best practice della community—ecco le 5 sezioni che tutti i file efficaci hanno in comune:

Sezione 1: Comandi critici

Claude inizia ogni sessione senza sapere come compilare il tuo progetto, eseguire i tuoi test o correggere errori di lint. Indovinerà. E le sue ipotesi ti costeranno turni.

Digli esattamente cosa scrivere:

1## Comandi
2
3- Build: `npm run build`
4- Dev: `npm run dev`
5- Test singolo file: `npm test -- percorso/del/file`
6- Test completo: `npm test`
7- Lint + correzione: `npm run lint:fix`
8- Type check: `npx tsc --noEmit`

Corto. Preciso. Direttamente utilizzabile.

Senza questa sezione, Claude proverà npm test quando il tuo progetto funziona con pnpm vitest. Spenderà tre turni a fare debug di un problema di comando che non avrebbe mai funzionato. Tre turni che avresti potuto usare per lavoro vero.

Sezione 2: Mappa dell'architettura

Claude inizia ogni sessione con una conoscenza zero del tuo codebase. Zero. Non sa dove vive la tua logica di business. Non sa se i tuoi componenti dovrebbero essere senza stato. Non sa che le tue route API non dovrebbero contenere logica di business.

Dagli una mappa:

1## Architettura
2
3- src/lib/services/ → tutta la logica di business
4- src/components/ → solo componenti UI senza stato
5- src/lib/store/ → stato globale (Zustand)
6- src/app/api/ → route API, nessuna logica di business qui
7- Accesso al DB solo tramite Server Actions o route API

Non un elenco esaustivo della tua struttura ad albero. Abbastanza perché Claude sappia dove stanno le cose e, cosa più importante, dove NON dovrebbero andare.

Questa distinzione... dove va vs. dove non va... è ciò che previene gli errori architetturali più frequenti.

Sezione 3: Regole rigide

Questa è la sezione più importante dell'intero file. Senza eccezioni.

Ogni regola qui deve rispondere a una singola domanda: "Se elimino questa riga, Claude commetterà un errore concreto?"

Se sì → la regola resta. Se no → non ha ragione di essere lì.

Esempio di regole ad alto valore:

1## Regole
2
3- NON commettere MAI file .env o segreti
4- Tutte le chiamate asincrone devono essere racchiuse in un try/catch
5- Solo componenti funzionali, zero componenti classe
6- Prefissi di commit obbligatori: feat:, fix:, docs:, refactor:
7- Ogni PR deve superare `npm run verify` prima del merge
8- Solo esportazione statica, niente SSR (distribuito su S3)
9- IMPORTANTE: esegui il type check dopo ogni modifica del codice

Due cose da notare su questo elenco.

In primo luogo, le regole negative sono importanti quanto quelle positive. "Non commettere MAI file .env" è una regola che sembra ovvia solo fino al giorno in cui Claude lo fa. Inseriscila.

In secondo luogo, i marcatori di enfasi come IMPORTANTE o DEVI ASSOLUTAMENTE funzionano davvero.

Questo non è aneddotico. Anthropic lo conferma nella propria documentazione: aggiungere IMPORTANTE o DEVI ASSOLUTAMENTE prima di una regola migliora misurabilmente l'aderenza di Claude a quella regola.

Usali con parsimonia: riservali per le regole che hanno le conseguenze più gravi se ignorate.

Rimani sotto le 15 regole in questa sezione. Oltre, diluisci l'attenzione su quelle che contano.

Sezione 4: Preferenze del flusso di lavoro

Ti è già successo. Chiedi a Claude di correggere una riga. Lui riscrive tre file, rinomina le tue funzioni e rifattorizza una classe che non c'entrava nulla con la tua richiesta.

Questa sezione lo previene:

1## Flusso di lavoro
2
3- Fai domande di chiarimento prima di iniziare compiti complessi
4- Apporta modifiche minime, non rifattorizzare codice non correlato
5- Esegui i test dopo ogni modifica, correggi gli errori prima di continuare
6- Crea commit separati per ogni modifica logica, non un unico commit gigante
7- In caso di incertezza tra due approcci, spiega entrambi e lasciami scegliere

Ogni riga qui risponde a un punto dolente concreto. Il commit gigante da 47 file. La riscrittura completa non richiesta. La decisione architetturale che Claude prende da solo quando avrebbe dovuto chiederti.

Sezione 5: Cosa NON mettere nel tuo CLAUDE.md

Questa sezione è importante quanto le altre. Forse di più.

1## NON includere:
2
3- Istruzioni sulla personalità ("sii un ingegnere senior")
4- Regole di formattazione gestite già dal tuo linter
5- @ import che tirano interi documenti in ogni sessione
6- Regole duplicate (se il globale dice "esegui i test", il progetto non lo ripete)
7- Qualsiasi cosa che Claude impari da solo tramite auto-memoria

Quest'ultimo punto è ampiamente sottovalutato.

Claude mantiene i propri appunti in ~/.claude/projects/<progetto>/memory/. Esegui /memory nella tua sessione per vedere cosa ha già imparato sul tuo progetto. Dopo alcune sessioni, spesso ti renderai conto che Claude ha già catturato informazioni che stavi per scrivere a mano nel tuo CLAUDE.md.

Non sprecare le tue istruzioni limitate su cose che Claude ha ricordato da solo.

Il template completo in meno di 60 righe, pronto all'uso

Elimina le sezioni che non si applicano al tuo progetto. L'obiettivo non è riempire tutto. L'obiettivo è mantenere solo ciò che cambia il comportamento di Claude in modo misurabile.

Le righe che hanno avuto il maggiore impatto sui miei risultati: risultati concreti

Dopo aver testato dozzine di configurazioni, ecco le cinque righe che hanno fatto la differenza più visibile:

1. IMPORTANTE: esegui il type check dopo ogni modifica del codice → Impedisce a Claude di consegnare codice con tipi rotti che non rileva senza essere esplicitamente invitato a controllare.

1. Apporta modifiche minime, non rifattorizzare codice non correlato → Impedisce la riscrittura completa e non richiesta di interi file.

1. Crea commit separati per ogni modifica logica, non un unico commit gigante → Impedisce il commit mostruoso e illeggibile di 47 file misti.

1. In caso di incertezza tra due approcci, spiega entrambi e lasciami scegliere → Impedisce a Claude di prendere decisioni architetturali da solo che sarebbero dovute spettare a te.

1. Solo esportazione statica, niente SSR → Impedisce a Claude di aggiungere codice server in un progetto distribuito staticamente su S3.

Cosa hanno in comune queste cinque righe: ognuna previene un errore specifico, frequente e costoso in termini di tempo di debug.

Questo è il test definitivo per ogni riga del tuo CLAUDE.md.

L'errore fondamentale e perché è così diffuso

Le persone trattano il loro CLAUDE.md come una lista dei desideri o un prompt di personalità.

"Sii senior." "Sii approfondito." "Pensa come un esperto."

Questo non è un brief. È pensiero magico.

Il tuo CLAUDE.md dovrebbe essere un documento tecnico, non un discorso motivazionale. Stack, comandi, architettura, regole concrete, flusso di lavoro. Tutto il resto è rumore che compete con le istruzioni che contano davvero.

Mantieni il file sotto le 80 righe. Rivedilo ogni volta che Claude commette un errore che avresti potuto prevenire.

E soprattutto: capisci cosa diventa questo file nel tempo.

Un buon CLAUDE.md al primo mese ti fa risparmiare tempo in ogni sessione. Entro il terzo mese, ha catturato le tue convenzioni e il tuo stack in modo sufficientemente preciso che Claude lavora quasi come un membro del team.

Entro il sesto mese, contiene ogni errore che Claude abbia mai commesso su questo progetto e li previene tutti automaticamente.

Il file capitalizza. Migliora con ogni correzione. Diventa progressivamente il miglior brief di onboarding che tu abbia mai scritto.

Non per Claude. Per te.