Ogni sessione di Claude Code inizia leggendo un file: CLAUDE.md. Prima del tuo primo prompt, prima di qualsiasi codice, prima che succeda qualsiasi cosa, Claude legge questo file e lo tratta come verità assoluta per l’intera sessione.
La maggior parte delle persone o non ce l’ha, oppure il loro è un mattone di 300 righe di istruzioni sulla personalità.
La differenza tra un buon CLAUDE.md e uno pessimo? È come la differenza tra fare onboarding a un senior engineer con un brief chiaro e buttare un nuovo assunto nel codice senza documentazione.
Perché la maggior parte dei file CLAUDE.md non funziona
Tre motivi:
Troppo lunghi. I modelli possono seguire in modo affidabile circa 150-200 istruzioni. Il prompt di sistema di Claude Code ne contiene già circa 50. Questo significa che il tuo CLAUDE.md ha forse 100-150 istruzioni prima che Claude inizi a perdere pezzi. Se il tuo file è di 200+ righe, Claude non sta ignorando le tue regole apposta – semplicemente non ce la fa.
Contenuto sbagliato. La maggior parte riempie CLAUDE.md con cose che Claude può capire da solo. Istruzioni di personalità tipo “sii un senior engineer” o “pensa passo dopo passo”. Consigli generali che non cambiano il comportamento di Claude. Ogni riga che non previene un errore specifico è un’istruzione sprecata.
Nessuna gerarchia. CLAUDE.md non è l’unico posto dove mettere le istruzioni. Ci sono tre livelli e la maggior parte butta tutto in uno:
~/.claude/CLAUDE.md→ Globale (ogni progetto).claude/CLAUDE.md→ Progetto (condiviso con il team, in git)./CLAUDE.local.md→ Locale (override personali, gitignored)
Globale è per regole che ripeteresti in ogni progetto. Progetto è per contesto specifico dello stack di cui il team ha bisogno. Locale è per le tue idiosincrasie personali.
Usare tutti e tre mantiene ogni file corto e focalizzato.
Le 5 sezioni che contano davvero
Dopo aver passato al setaccio dozzine di file CLAUDE.md di produzione da progetti open-source, i docs ufficiali di Anthropic e repo di best practices della community, ogni file efficace copre queste 5 cose:
1. Comandi critici
Claude non sa come buildare, testare o fare il lint del tuo progetto = diglielo.
## Commands - Build: `npm run build` - Dev: `npm run dev` - Test single file: `npm test -- path/to/file` - Lint + fix: `npm run lint:fix` - Type check: `npx tsc --noEmit`
Corto e specifico. Claude esegue questi invece di indovinare. Senza questa sezione, Claude proverà npm test quando il tuo progetto usa pnpm vitest e sprecherà 3 turni a debuggare un comando che non avrebbe mai funzionato.
2. Mappa dell’architettura
Claude inizia ogni sessione con zero conoscenza della tua codebase. Dagli una mappa.
## Architecture - src/lib/services/ → tutta la business logic - src/components/ → solo componenti UI stateless - src/lib/store/ → stato globale (Zustand) - src/app/api/ → route API, niente business logic qui - Accesso database solo tramite Server Actions o route API
Non serve un listing completo delle directory. Giusto abbastanza perché Claude sappia dove vivono le cose e cosa va dove.
3. Regole ferree (le cose che Claude sbaglia senza di te)
Questa è la sezione più importante. Ogni regola qui dovrebbe rispondere a: “Rimuovere questa riga causerebbe un errore di Claude?”
## Rules - MAI committare file .env o secrets - Tutte le chiamate async devono usare try/catch - Usa solo componenti funzionali, no class components - Prefisso commits: feat:, fix:, docs:, refactor: - Tutte le PR devono passare `npm run verify` prima del merge - Solo export statico, no SSR (deployed su S3) - IMPORTANTE: esegui type check dopo ogni modifica al codice
Due cose da notare:
- Le regole negative sono importanti quanto quelle positive (“mai committare .env”)
- I marcatori di enfasi come IMPORTANTE funzionano davvero
I docs ufficiali di Anthropic confermano che aggiungere “IMPORTANT” o “YOU MUST” migliora l’aderenza.
Mantieni questa sezione sotto le 15 regole.
4. Preferenze di workflow
Come vuoi che Claude lavori? Questo previene il problema “Claude riscrive l’intero file quando gli hai chiesto un fix di una riga”.
## Workflow - Fai domande chiarificatrici prima di iniziare task complessi - Fai modifiche minime, non refactorizzare codice non correlato - Esegui test dopo ogni modifica, fixa i fallimenti prima di andare avanti - Crea commit separati per ogni modifica logica, non un commit gigante - Quando sei incerto tra due approcci, spiega entrambi e fammi scegliere
5. Cosa NON includere
Altrettanto importante è cosa lasci fuori:
- Istruzioni di personalità (“sii un senior engineer”)
- Regole di formattazione del codice che il tuo linter già gestisce
- @-imports che embeddano interi docs in ogni sessione
- Regole duplicate (se global dice “esegui test”, project non lo ripete)
- Qualsiasi cosa Claude imparerà da solo via auto memory
Auto memory è sottovalutato qui. Claude mantiene le sue note in ~/.claude/projects/<project>/memory/. Esegui /memory per vedere cosa Claude ha già imparato sul tuo progetto.
Non sprecare righe di CLAUDE.md su cose che Claude ha capito dopo una sessione.
Il template completo (copia questo)
Ecco un CLAUDE.md production-ready che puoi copiare e adattare. Sotto le 60 righe. Copre tutto ciò di cui Claude ha bisogno, niente che non serve.
# CLAUDE.md ## Project [Una riga: cosa fa questo progetto e chi lo usa] ## Stack [Framework, linguaggio, database, deployment target] ## Commands - Dev: `[command]` - Build: `[command]` - Test single: `[command] -- [path]` - Test all: `[command]` - Lint: `[command]` - Type check: `[command]` ## Architecture - [folder] → [cosa vive qui] - [folder] → [cosa vive qui] - [folder] → [cosa vive qui] - [file] → [cosa fa questo file] ## Rules - [Regola che previene un errore specifico] - [Regola che previene un errore specifico] - [Regola che previene un errore specifico] - IMPORTANTE: [L'unica regola che Claude continua a rompere] ## Workflow - [Come vuoi che Claude approcci i task] - [Convenzioni di commit] - [Aspettative di testing] - [Quando chiedere vs quando agire] ## Out of scope - [Cose che Claude non dovrebbe toccare] - [File mantenuti manualmente] - [Integrazioni che Claude non dovrebbe modificare]
Elimina le sezioni che non si applicano.
Le regole che cambiano tutto
Dopo aver testato dozzine di configurazioni CLAUDE.md, queste sono le righe che hanno fatto la differenza più grande nella qualità dell’output:
- IMPORTANTE: esegui type check dopo ogni modifica al codice (previene che Claude spedisca tipi rotti)
- Fai modifiche minime, non refactorizzare codice non correlato (previene che Claude riscriva l’intero file)
- Crea commit separati per ogni modifica logica (previene il commit mostro da 47 file)
- Quando incerto, spiega entrambi gli approcci e fammi scegliere (previene che Claude prenda decisioni architetturali per te)
- Solo export statico, no SSR (previene che Claude aggiunga codice server-side a un sito statico)
Ognuna di queste previene un errore specifico e comune.
Questo è il test per ogni riga nel tuo CLAUDE.md: rimuoverla causa che Claude faccia la cosa sbagliata?
L’errore che fanno tutti
La gente tratta CLAUDE.md come una wish list.
Il tuo CLAUDE.md dovrebbe essere un brief tecnico, non un discorso motivazionale. Stack, comandi, architettura, regole, workflow. Tutto il resto è rumore che compete per l’attenzione con le istruzioni che contano davvero.
Mantienilo sotto le 80 righe. Rivedilo quando Claude sbaglia qualcosa.
Il file si accumula nel tempo. Un buon CLAUDE.md al primo mese ti risparmia di ripeterti. Al sesto mese ha catturato ogni errore che Claude abbia mai fatto nel tuo progetto e li previene tutti automaticamente.
