CLAUDE.md: best practice con esempio annotato completo

CLAUDE.md è il file più costoso del tuo repository. Non in byte. In ripetizione. Qualunque cosa ci metti viene letta nel contesto di Claude all'inizio di ogni sessione e viaggia insieme a ogni singolo messaggio che mandi da lì in poi. Un CLAUDE.md gonfio è una tassa che paghi centinaia di volte al giorno senza accorgertene.

Testare setup di Claude è il nostro lavoro a SkillProof, e ormai abbiamo letto più file CLAUDE.md di quanti vorremmo ammettere. La maggior parte sbaglia nello stesso modo: tratta il file come una discarica per tutto quello che l'autore ha mai voluto far sapere a Claude. Filosofia di coding, preferenze di tono, una style guide completa, tre paragrafi sull'essere prudenti. Tutto caricato, sempre, per ogni richiesta, inclusa quella in cui hai chiesto a Claude di rinominare una variabile.

Questa guida è il nostro tentativo di sistemare le cose. A cosa serve davvero CLAUDE.md, un esempio completo annotato da adattare, cosa spostare nelle skill, e l'aritmetica che spiega perché tutto questo conta.

Cos'è CLAUDE.md e quando viene caricato

CLAUDE.md è il file di memoria di progetto di Claude Code. Quando avvii una sessione in una directory, Claude Code risale dalla tua working directory cercando file CLAUDE.md e carica quello che trova nel contesto di sistema. Anche il tuo file globale in ~/.claude/CLAUDE.md viene caricato, in ogni progetto. I file nelle sottodirectory vengono caricati quando Claude lavora con file in quelle sottodirectory.

La parte che sfugge a molti: non è una lettura una tantum. I modelli linguistici sono stateless, quindi il contesto completo, CLAUDE.md incluso, viene inviato con ogni richiesta della conversazione. Fai quaranta domande in una sessione e il file viene trasmesso quaranta volte. Il prompt caching ammorbidisce il costo in dollari, e arriveremo ai numeri veri, ma niente ammorbidisce il costo in attenzione. Ogni token in CLAUDE.md è un token che compete col tuo codice vero per il focus del modello.

Questo è il prezzo. In cambio ottieni qualcosa di reale: Claude inizia ogni sessione sapendo già i tuoi comandi di build, le stranezze della tua architettura e le mine nel tuo codebase. Nessuno deve incollare "usiamo pnpm, non npm" per la nona volta. La domanda non è mai se avere un CLAUDE.md. È cosa si merita un posto lì dentro.

La regola d'oro: i fatti in CLAUDE.md, i comportamenti nelle skill

Ecco la tesi dell'intero articolo, e il singolo filtro che sistema la maggior parte dei file mal fatti:

CLAUDE.md è per i fatti su questo progetto. Le skill sono per i comportamenti riutilizzabili.

Un fatto su questo progetto: "i prezzi sono salvati come centesimi interi". Claude non può indovinarlo. Nessuna quantità di intelligenza generale lo recupera dal nulla, e sbagliarlo corrompe i dati. Va in CLAUDE.md, caricato in permanenza, perché è rilevante per quasi ogni modifica che tocca i soldi.

Comportamento riutilizzabile: "quando fai review del codice, controlla prima la gestione degli errori, poi la sicurezza, poi il naming". Non è un fatto sul tuo progetto. È una procedura, vale per ogni progetto che toccherai, ed è rilevante solo quando stai davvero facendo una review. Mettila in CLAUDE.md e la paghi durante ogni commit message, ogni ritocco CSS, ogni "cosa fa questa funzione". Mettila in una skill e ti costa una riga di metadati fino al momento in cui una review avviene sul serio, e a quel punto le istruzioni complete si caricano on demand.

La maggior parte delle persone infila tutto in CLAUDE.md perché è il file che conosce. È lì, funziona in modo evidente, e il costo è invisibile perché nessuna fattura dirà mai "hai pagato la tua style guide 4.000 volte questo mese". Ma il costo è reale, e la separazione diventa quasi meccanica una volta che ti fai due domande su qualsiasi istruzione. È vera solo per questo progetto? È rilevante per la maggior parte delle richieste? Due sì: CLAUDE.md. Tutto il resto: una skill, o il cestino.

C'è un secondo motivo per la separazione che non c'entra nulla coi token. Le istruzioni in un file sempre caricato competono tra loro. Abbiamo visto un CLAUDE.md da 2.000 parole in cui la regola davvero importante ("mai lanciare db:push contro staging") stava al paragrafo undici, sotto una predica sul clean code. Claude segue le liste lunghe di istruzioni come le seguono le persone: gli elementi taglienti vengono diluiti dal riempitivo intorno. I file corti vengono rispettati. I file lunghi vengono letti in diagonale.

Un esempio di CLAUDE.md annotato per una web app di medie dimensioni

Ecco un esempio completo per uno storefront Next.js fittizio ma realistico. Le annotazioni spiegano perché ogni sezione si guadagna il posto fisso nel contesto. Sono circa 350 parole, più o meno 500 token, e sosterremmo che non c'è niente da tagliare.

# Acme Storefront

Next.js 14 (App Router) + TypeScript. Postgres via Prisma. Deployed on Vercel.
<!-- One line of stack. Claude infers most of this from package.json anyway;
     this just saves it the lookup. Do not write paragraphs here. -->

## Commands
- `pnpm dev` — local server on :3000 (needs `docker compose up db` first)
- `pnpm test` — unit tests (Vitest). Integration: `pnpm test:int` (slow, needs db)
- `pnpm lint && pnpm typecheck` — run both before calling any task done
- Migrations go through `pnpm db:migrate`. NEVER `db:push` outside local.
<!-- Commands earn their place because Claude runs them dozens of times per
     session, and a wrong guess (npm vs pnpm) wastes a round-trip every time.
     The db:push line is here because the failure is irreversible. -->

## Architecture facts you can't guess
- `src/app` is routes only. All logic lives in `src/modules/<domain>`.
- API routes are thin wrappers over `src/modules/*/service.ts`. No logic in routes.
- Auth is Clerk, but `userId` in services is OUR internal id, not Clerk's.
  Map with `getInternalUser()`.
- Prices are integer cents everywhere. Formatting lives in `lib/money.ts`.
- Feature flags come from `flags.ts`, not env vars.
<!-- The test for this section: would a skilled new hire get it wrong on
     day one? The Clerk id mismatch has caused real bugs; that is exactly
     the kind of fact worth paying for on every request. -->

## Conventions that differ from defaults
- Named exports only. Legacy violations exist in `src/legacy`; don't add new ones.
- Server components by default. `"use client"` needs a comment saying why.
- Zod schemas live next to services; infer types from them, never hand-write both.
<!-- Only conventions that DIFFER from what Claude would do anyway.
     "Use TypeScript strict mode" when tsconfig already says so is a wasted line. -->

## Gotchas
- `src/legacy/*` is frozen. Don't refactor it or import from it in new code.
- CI runs Node 20. `pnpm test:int` fails on 22; use `nvm use` first.
<!-- Each line here represents an hour someone actually lost. -->

## Definition of done
Lint, typecheck, and unit tests pass, and you state which of them you ran.
<!-- One sentence. Not a philosophy of quality. -->

Nota cosa manca. Nessun "scrivi codice pulito e manutenibile". Nessuna istruzione di tono. Nessuna spiegazione di cosa sia Next.js. Nessuna regola di lint che il linter già impone meccanicamente. Ogni riga è o un comando che Claude eseguirà, o un fatto che non può dedurre, o un confine il cui attraversamento costa soldi veri o ore vere.

Cosa spostare nelle skill

Se il tuo CLAUDE.md attuale è di 1.500 parole, l'eccesso di solito ricade in pochi bucket riconoscibili, e ogni bucket ha una casa a forma di skill. Qualche esempio dal nostro catalogo, tutte installate e testate su macchine pulite prima della pubblicazione:

Il cerimoniale git. Naming dei branch, formato dei commit message, template per le descrizioni delle PR, quando fare squash. È comportamento, è identico in tutti i tuoi progetti ed è rilevante solo quando stai davvero committando. La skill git-workflow che abbiamo testato copre esattamente questo perimetro, e spostarla fuori da CLAUDE.md fa risparmiare in genere dalle 200 alle 400 parole di testo sempre caricato.

Le checklist di review. Le istruzioni "quando chiedo una review, controlla X e poi Y" sono il classico abusivo di CLAUDE.md. Sono lunghe, sono procedurali e sono dormienti il 95% del tempo. code-review-checklist carica la sua checklist solo quando una review sta avvenendo, che è l'intero senso del formato skill.

La disciplina di debugging. Istruzioni tipo "riproduci prima di fixare, dichiara la tua ipotesi, verifica dopo" descrivono una metodologia, non il tuo progetto. systematic-debugging impacchetta quella metodologia e resta fuori dal contesto mentre fai qualsiasi cosa che non sia inseguire un bug.

La regola generale: se potessi copiare il paragrafo nel CLAUDE.md di un altro progetto senza modificarlo, non è un fatto sul tuo progetto e non deve vivere lì. Estrailo. Scrivere una skill tua richiede una ventina di minuti con la nostra guida, ed è il quarto d'ora a più alta leva disponibile per chiunque abbia un CLAUDE.md più lungo di una schermata.

Anti-pattern che continuiamo a vedere

Esaminiamo un sacco di setup, e gli stessi cinque fallimenti tornano a ripetizione.

Il romanzo. Un CLAUDE.md da 3.000 parole che sembra un manuale di ingegneria. Qualcuno ha avuto una brutta esperienza, ha aggiunto un paragrafo, ne ha avuta un'altra, ne ha aggiunto un altro, e non ha mai cancellato niente. Il file cresce e basta. Oltre al costo in token, file così seppelliscono le due regole che contano davvero sotto venti che non contano, e la compliance di Claude con tutte quante cala insieme.

I comandi stantii. Il file dice npm run test:unit, lo script è stato rinominato in pnpm test otto mesi fa, e ora Claude esegue con sicurezza un comando che fallisce, legge l'errore, fruga in package.json e si riprende. Ogni sessione. Stai pagando per la documentazione sbagliata e poi paghi di nuovo perché Claude ci giri intorno. Un CLAUDE.md sbagliato è peggio di nessun CLAUDE.md, perché Claude si fida.

Le regole di lint duplicate. "Usa apici singoli. Niente variabili inutilizzate. Lunghezza massima riga 100." La tua config ESLint lo impone già meccanicamente, con una copertura migliore di quanta l'attenzione di un LLM potrà mai avere. Ripetere in prosa regole già imposte dalle macchine è puro spreco. L'unica eccezione: le regole che il tooling non può intercettare, tipo "non importare da src/legacy", che vanno davvero scritte.

La sezione "sii utile". "Scrivi codice pulito. Pensa bene prima di fare modifiche. Sii accurato ma conciso." Ne vediamo una variante in circa metà dei file che esaminiamo, e non fa nulla. Claude ci sta già provando. Le istruzioni a base di vibes senza contenuto testabile sono la prima cosa da cancellare, e il loro unico effetto misurabile sono i token che bruciano.

L'autobiografia. Lunghe descrizioni di cosa fa il prodotto, chi sono gli utenti, la mission aziendale. Ogni tanto un singolo fatto di prodotto conta per le decisioni di codice ("i nostri utenti hanno connessioni rurali lente, la bundle size è un vincolo reale"). Tieni quella frase. Taglia il pitch deck.

La matematica dei token

Facciamo il conto che la gente salta, perché sono i numeri ad averci trasformati in minimalisti.

Un CLAUDE.md da 3.000 parole è circa 4.000 token. Viaggia con ogni richiesta, quindi una sessione di lavoro da 40 messaggi lo trasmette 40 volte: 160.000 token di input in una sessione che sono il tuo file di memoria, non il tuo codice né la tua conversazione. Lavora cinque sessioni al giorno e stai spostando 800.000 token di CLAUDE.md al giorno. Su un mese di 22 giorni lavorativi, circa 17,6 milioni.

Il prompt caching salva la maggior parte del costo in dollari, e va detto onestamente. L'input in cache su Sonnet costa un decimo del prezzo base, quindi quei 17,6M di token costano un paio di dollari al mese se la cache resta calda, più sui 50$ se non lo resta. Fastidioso, non rovinoso.

Il costo che il caching non salva è il contesto. La context window di Claude Code è finita, e le sessioni lunghe finiscono già in compattazione, dove la conversazione viene riassunta e il dettaglio si perde. Un residente permanente da 4.000 token significa che raggiungi la compattazione prima, in ogni sessione, per sempre. E degrada l'attenzione ben prima di qualsiasi limite rigido: i modelli seguono dimostrabilmente meglio le istruzioni quando ce ne sono meno in competizione. La differenza tra un file da 500 token e uno da 4.000 non sono 3.500 token. È se il modello tiene ancora alla tua regola "mai toccare staging" al messaggio 35.

Rifai gli stessi conti sull'esempio asciugato qui sopra: 500 token, 40 messaggi, cinque sessioni, 22 giorni. Circa 2,2M di token al mese, un ottavo della versione gonfia, con le regole importanti in piedi in una stanza non affollata. Abbiamo scritto il playbook completo per tagliare i costi nella nostra guida ai costi in token, e la dieta di CLAUDE.md è costantemente la vittoria più economica che contiene.

Progetto vs globale: la divisione con ~/.claude/CLAUDE.md

Hai due file, e le cose vanno male quando il contenuto finisce in quello sbagliato.

~/.claude/CLAUDE.md è globale. Si carica in ogni progetto, quindi deve contenere solo cose vere ovunque: "uso pnpm su tutti i progetti personali", "rispondi in inglese anche se i miei prompt a volte sono in russo", "mai committare senza che te lo chieda". Tienilo sotto le dieci righe. Ogni riga qui viene moltiplicata su tutto il tuo lavoro, quindi il suo budget dev'essere il più stretto di tutti.

<project>/CLAUDE.md è il file di progetto, versionato in git, condiviso con colleghi e CI. Fatti su questo codebase, nella forma dell'esempio sopra. Siccome è condiviso, le preferenze personali non ci vanno; per quelle esistono CLAUDE.local.md o il file globale.

I file CLAUDE.md nelle sottodirectory sono il livello intermedio sottovalutato. Un packages/api/CLAUDE.md con fatti specifici delle API si carica solo quando Claude tocca quel package. Se il file root del tuo monorepo ha sezioni che valgono per un solo workspace, spingerle un livello più in basso è risparmio di token gratis a perdita d'informazione zero.

Un'idea sbagliata da uccidere: mettere una cosa in più di uno di questi file non fa sì che Claude la segua più forte. Rende solo il file più lungo. Scegli una casa per ogni fatto.

Tenerlo fresco

CLAUDE.md marcisce più in fretta della documentazione normale perché niente si rompe in modo visibile quando è sbagliato. I test falliscono rumorosamente. Un file di memoria stantio si limita a sviare in silenzio il modello, che in silenzio si riprende, e tu in silenzio paghi entrambe le cose.

Il nostro rituale è noioso e richiede dieci minuti al mese. Apri il file. Per ogni comando, eseguilo davvero. Per ogni fatto dichiarato, chiediti se è ancora vero e se Claude ha sbagliato qualcosa questo mese per colpa sua. Cancella almeno una riga; c'è sempre una riga, e se non la trovi, i tuoi standard per "meritarsi il posto" si sono allentati. Poi controlla la lunghezza: una schermata è il target, due schermate il tetto, e oltre quello non stai più editando, stai estraendo in skill.

Il miglior trigger per gli aggiornamenti però non è il calendario. È il momento in cui Claude sbaglia qualcosa perché il file l'ha ingannato. Sistema il file nello stesso respiro del codice. Tratta i bug di CLAUDE.md come bug, perché hanno lo stesso comportamento recidivo: se non li fixi, si ripresentano alla prossima sessione.

FAQ

Quanto dev'essere lungo un CLAUDE.md?

Sotto le 500 parole per la maggior parte dei progetti, sotto le 1.000 per un monorepo davvero complicato. Il nostro test operativo: se non sta in una schermata, qualcosa lì dentro è comportamento travestito da fatto, e quel qualcosa appartiene a una skill. L'esempio in questo articolo è di circa 350 parole e copre una vera app di medie dimensioni.

Qual è la differenza tra CLAUDE.md e una skill?

Il modo in cui si caricano. CLAUDE.md viene caricato per intero, sempre, per ogni richiesta. Una skill espone solo una description di una riga finché un task non le corrisponde, poi si carica on demand. Quindi CLAUDE.md deve contenere i fatti che ti servono costantemente, e le skill le procedure che ti servono ogni tanto. La nostra guida alle skill copre i meccanismi.

Devo committare CLAUDE.md su git?

Sì. È documentazione condivisa, e le sessioni Claude dei tuoi colleghi beneficiano degli stessi fatti delle tue. Tieni le preferenze personali in CLAUDE.local.md (in gitignore) o nel file globale invece di imporle al team.

Posso usare file CLAUDE.md annidati nelle sottodirectory?

Sì, e nei monorepo dovresti. Claude Code carica il file di una sottodirectory quando lavora con i file lì dentro. Il file root prende i fatti validi per tutto il repo, packages/api/CLAUDE.md prende i fatti delle API, e i progetti a package singolo possono saltare del tutto l'annidamento.

Asciugare CLAUDE.md cambia davvero il comportamento di Claude, o solo i costi?

Entrambi, e il comportamento è la vittoria più grande. Il rispetto delle istruzioni degrada al crescere del loro numero; un file corto con cinque regole taglienti viene rispettato più affidabilmente di uno lungo con trenta. Il risparmio di token è la parte misurabile, e le nostre classifiche di efficienza tracciano quali skill aiutano di più lì, ma il miglioramento di compliance è quello che noterai per primo.

Un'ultima opinione: i migliori CLAUDE.md che abbiamo visto sono stati tutti editati per sottrazione. Nessuno ne scrive uno ottimo il primo giorno. Ne scrivi uno mediocre, guardi dove Claude inciampa, aggiungi il fatto che l'avrebbe evitato e tagli una riga di riempitivo per pagarlo. Sei settimane così battono qualsiasi template, incluso il nostro.