CLAUDE.md è un semplice file markdown alla radice del tuo progetto. Claude lo legge automaticamente ad ogni sessione. A livello di progetto: ./CLAUDE.md. Globale (tutti i progetti): ~/.claude/CLAUDE.md. Il progetto sovrascrive il globale: il file globale contiene le tue impostazioni predefinite, il file di progetto contiene le specifiche di questo repository.
Pensalo come il documento di onboarding che dai a un contractor altamente qualificato che non sa nulla del tuo progetto. Senza di esso, ogni sessione inizia con Claude che indovina il tuo stack, le tue convenzioni di denominazione e le tue decisioni passate. Le ipotesi diventano codice, il codice diventa bug. CLAUDE.md cortocircuita quella catena. Un file batte un prompt intelligente perché funziona sia che tu te lo ricordi o meno.
Cinque sezioni che si ripagano da sole. Da tre a sei punti elenco ciascuna:
1. Stack: framework, DB, autenticazione, email, con versioni. "Next.js 16, Postgres su Neon, Resend per l'email, Stripe per i pagamenti, Supabase per l'autenticazione."
2. Percorsi: dove si trovano le cose. "App in /app, azioni server in /actions, API sotto /app/api/v2, componenti condivisi in /components/ui."
3. Convenzioni: regole ovvie per te, invisibili a Claude. "Denaro in centesimi (int), date UTC, nomi file kebab-case, ID come UUID v4."
4. Regole di sicurezza: cose che non devono mai accadere. "Non loggare mai le chiavi API. Parametrizzare tutte le query SQL. Limitare la frequenza di tutti gli endpoint pubblici."
5. Non fare questo: trappole in cui sei già caduto. "Non aggiungere dipendenze senza chiedere. Non eseguire migrazioni da locale contro la produzione."
Un modello funzionante. Sostituisci con i dettagli del tuo progetto reale:
# Plinko Grant Tracker
## Stack
- Next.js 16, Postgres (Neon), Resend, Stripe
- Auth: Supabase Auth con Google OAuth
## Routes
- App in /app, actions in /actions, API sotto /app/api/v2
## Conventions
- Denaro in centesimi (int), date UTC, nomi file kebab-case
- ID: UUID v4. Colonne booleane: prefisso is_ o has_
## Security Rules
- Non loggare mai i segreti, parametrizzare SQL
- Limitare la frequenza di tutti gli endpoint POST/PUT/DELETE (10/min per IP)
- Le nuove tabelle Supabase vengono spedite con politiche RLS nello stesso commit
## Don't Do This
- Non aggiungere dipendenze senza chiedere
- Non eseguire migrazioni da locale contro la produzione
- Non usare select(*)Nota la specificità. "10/min per IP" è attuabile. "Usa il rate limiting" non lo è.
L'errore più costoso: regole vaghe che sembrano specifiche.
Debole: "Gestisci il denaro con attenzione." Claude gestirà il denaro nel modo che ritiene migliore, che potrebbe non corrispondere al tuo sistema.
Forte: "Tutti gli importi monetari sono centesimi interi. Mai float. Non visualizzare mai i centesimi grezzi; dividi per 100 e formatta con un simbolo di valuta." Tipo di archiviazione, regola di elaborazione, regola di visualizzazione. Nessuna ambiguità.
Il secondo errore: scrivere aspirazioni invece di vincoli. "Apprezziamo il codice pulito e leggibile" è un'aspirazione. "I file di oltre 200 righe sono divisi in moduli" è un vincolo. Le aspirazioni richiedono giudizio; i vincoli producono un comportamento coerente. Riempi il tuo CLAUDE.md di vincoli.
CLAUDE.md è un documento vivo. Tre segnali che necessita di aggiornamento:
Incolli lo stesso contesto in un prompt per la seconda volta. Se lo stai dicendo di nuovo, appartiene a CLAUDE.md.
Claude commette un errore che una regola avrebbe prevenuto. L'errore è la regola. Scrivila prima della prossima sessione.
Spieghi una convenzione a un collega. Se valeva la pena dirla ad alta voce, vale la pena caricarla automaticamente.
Disciplina della lunghezza: da tre a sei punti elenco per sezione; oltre otto, dividi la sezione. Un CLAUDE.md troppo lungo per essere sfogliato smette di funzionare perché le regole importanti vengono sepolte. Sei righe giuste battono sessanta righe di riempimento.
Scalare oltre circa 300 righe: dividere in file tematici con inclusioni @filename:
# CLAUDE.md (root)
@rules/stack.md
@rules/security.md
@rules/db-migrations.mdOgni file tematico rimane focalizzato; la radice rimane breve.
Esegui il commit di CLAUDE.md nel controllo versione. Le regole diventano revisionabili nelle PR, e un nuovo membro del team clona il repo con Claude già configurato. Aggiungi ogni regola "Non fare questo" nello stesso commit della correzione del bug che l'ha insegnata. Un'avvertenza: generalizza i percorsi specifici della macchina prima di eseguire il commit.
Cosa appartiene a CLAUDE.md rispetto a un prompt? Raggio d'azione. Se una regola previene una classe di errori che costa un'ora o più per essere risolta, va in CLAUDE.md. Le istruzioni specifiche della sessione rimangono nei prompt.
Crea il tuo primo CLAUDE.md in dieci minuti. Dai a Claude questo prompt:
"Sto configurando Claude Code per un progetto con questo stack: [stack]. Convenzioni chiave che un nuovo arrivato non conoscerebbe: [convenzioni]. Regole di sicurezza che non devono mai essere violate: [regole]. Cose che hanno causato bug in precedenza: [trappole]. Bozza un CLAUDE.md con cinque sezioni: Stack, Routes, Conventions, Security Rules, Don't Do This."
La prima bozza ti dà l'80 percento. Affinala con ciò che Claude ha perso; il restante 20 percento è ciò che è specifico della tua esperienza reale con il progetto.
CLAUDE.md alla radice del progetto carica il tuo stack, i percorsi, le convenzioni, le regole di sicurezza e le trappole in ogni sessione. File globale per le impostazioni predefinite tra progetti, file di progetto per le sovrascritture. Vincoli, non aspirazioni. Sei righe giuste battono sessanta. Aggiornalo ogni volta che Claude commette un errore che una regola scritta avrebbe prevenuto.