Scrivere il miglior CLAUDE.md: guida completa per Claude Code

Il prompt di sistema di Claude Code occupa già circa 50 istruzioni prima che inizi la tua sessione. Le ricerche sugli LLM di frontiera mostrano che la capacità di seguire le istruzioni inizia a degradare intorno alle 150-200 istruzioni totali, il che ti lascia all'incirca 100-150 slot per tutto ciò che vuoi che Claude sappia sul tuo progetto. 

CLAUDE.md è il file che riempie quegli slot. È un file markdown che Claude Code legge all'inizio di ogni sessione, fornendogli un contesto persistente sulla tua codebase senza che tu debba ripeterti. Ma Claude filtra attivamente i contenuti che considera irrilevanti per il compito corrente. Un file gonfio non solo spreca spazio: entra in competizione con le tue regole effettive.

Questo tutorial spiega come costruire un CLAUDE.md in cui ogni riga conta: cosa inserire, cosa lasciare fuori, come strutturarlo per i team e come mantenerlo utile nel tempo.

Ti consiglio anche di dare un'occhiata alle nostre altre guide recenti su Claude Code:

• Claude Code Plan Mode
• Claude Code in Docker
• Come creare plugin per Claude Code
• Uso di Claude Code con modelli locali Ollama

Che cos'è un file CLAUDE.md?

CLAUDE.md è un file markdown che Claude Code carica automaticamente all'inizio di ogni conversazione. Sta nella root del progetto e fornisce a Claude istruzioni permanenti su molti fatti rilevanti: 

• Lo stack tecnologico che usi
• Come eseguire i test
• Quali convenzioni contano
• Cosa non toccare

Senza di esso, ogni sessione parte da zero. Spieghi sempre lo stesso contesto, correggi le stesse assunzioni e guardi Claude ripetere gli stessi errori di ieri. CLAUDE.md risolve il problema codificando una volta sola la conoscenza del tuo progetto.

È uno dei vari sistemi di contesto che usa Claude Code, e ognuno gestisce un tipo di lavoro diverso:

Eseguire /init genera un CLAUDE.md iniziale analizzando la tua codebase, rilevando sistemi di build, framework di test e pattern di codice. Se esiste già un file, propone miglioramenti invece di sovrascriverlo. È un punto di partenza ragionevole, ma il file è troppo importante per lasciarlo in autopilota.

Una cosa importante da sapere è che il contenuto di CLAUDE.md sopravvive anche a /compact. Quando il contesto viene compresso a sessione in corso, Claude rilegge il file dal disco e lo reinietta fresco.

Posizione dei file e precedenza

I file CLAUDE.md possono trovarsi in quattro posizioni, elencate dalla più ampia alla più specifica:

• Policy gestita (a livello di organizzazione): /Library/Application Support/ClaudeCode/CLAUDE.md su macOS. Si applica a tutti gli utenti della macchina e non può essere esclusa da alcuna impostazione. Su Linux/WSL si trova in /etc/claude-code/CLAUDE.md, e su Windows in C:\Program Files\ClaudeCode\CLAUDE.md.

• Livello utente: ~/.claude/CLAUDE.md. Istruzioni personali valide per ogni progetto sulla tua macchina.

• Livello progetto: ./CLAUDE.md o ./.claude/CLAUDE.md nella root del repo. Questo è quello che si committa su git e si condivide con il team.

• Sottodirectory: ./subdir/CLAUDE.md. Limitato a quella directory e caricato su richiesta quando Claude legge file lì, non all'avvio della sessione.

I file più specifici hanno la precedenza su quelli più generali. Se il tuo CLAUDE.md di progetto dice "usa le tab" e il tuo file a livello utente dice "usa gli spazi", vince il file di progetto.

Per preferenze personali che non dovrebbero finire nel controllo di versione, crea un CLAUDE.local.md e aggiungilo a .gitignore. Bizzarrie dell'editor, stili di commit preferiti o override temporanei vanno qui invece di inquinare il file condiviso.

Sapendo dove vive il file e con cosa compete, la prossima domanda è cosa inserire davvero al suo interno.

Cosa includere nel tuo CLAUDE.md

Un CLAUDE.md si articola in tre livelli: 

1. Cos'è il progetto
2. Perché funziona nel modo in cui funziona
3. Come dovrebbe operare Claude al suo interno

Se hai letto le best practice di Claude Code, riconoscerai lo stesso principio applicato a una superficie più ristretta. (Se non l'hai fatto, dagli sicuramente un'occhiata dopo aver letto questo articolo!)

Panoramica di progetto ad alto contenuto informativo

Inizia con una descrizione del progetto in una o due righe e con il tuo tech stack con numeri di versione. Claude può dedurre molto leggendo il codice, ma non indovinerà che usi Next.js 15 invece di 14, o che hai scelto Drizzle al posto di Prisma.

Includi una mappa della struttura delle directory. Non ogni file, solo il layout di alto livello con brevi descrizioni:

src/
  data/        # Data loading and preprocessing pipelines
  models/      # Model definitions and training loops
  evaluation/  # Metrics, validation, experiment tracking
  api/         # FastAPI endpoints for model serving
  tests/       # Co-located with source, test_*.py

Metti i comandi comuni nei blocchi di codice. Build, test, lint e avvio del server di sviluppo. Un comando dentro una code fence è qualcosa che Claude eseguirà alla lettera. Un comando scritto in una frase è un suggerimento su cui potrebbe improvvisare.

Scopi e vincoli

Le tue decisioni architetturali devono stare nel file, perché altrimenti Claude ne prenderà di proprie. Se hai scelto SQLite invece di Postgres per un motivo, dillo. Se il tuo layer API segue un pattern specifico, spiegane la logica.

La motivazione qui lavora davvero. "Mai fare force push" è un'istruzione piatta che Claude potrebbe ignorare sotto pressione. "Mai fare force push. Questo riscrive la cronologia condivisa ed è irrimediabile per i collaboratori" fornisce a Claude abbastanza contesto per generalizzare. Non eviterà solo git push --force. Esiterà anche prima di git reset --hard su un branch condiviso.

Istruzioni operative per Claude

Qui rientrano le convenzioni che Claude non può apprendere solo leggendo il codice. Se usi Conventional Commits (feat:, fix:, docs:), dillo. Se i branch seguono un pattern di naming come initials/description, scrivilo.

Anche le particolarità e le trappole vanno qui. Ogni codebase le ha: lo script di migrazione che deve girare prima della build, la variabile d'ambiente che richiede un valore specifico perché i test passino, il modulo che si rompe se importato fuori ordine. Claude è un nuovo membro del team a ogni sessione, e queste sono le cose su cui inciampa un nuovo assunto il primo giorno.

Cosa puoi saltare: tutto ciò che Claude sa già dal linguaggio stesso. Non serve dirgli di usare async/await nel JavaScript moderno o di preferire pathlib in Python 3. Se una convenzione è il default del linguaggio, scriverla è rumore che soffoca le istruzioni davvero importanti.

Come scrivere un file CLAUDE.md

Azzeccare i contenuti è la metà più facile. La parte più difficile è scrivere istruzioni che Claude seguirà davvero e sapere cosa tagliare.

Scrivere istruzioni efficaci

La specificità batte l'intento ogni volta. "Formatta correttamente il codice" non dice nulla a Claude. "Usa indentazione a 2 spazi, niente punti e virgola, apici singoli" gli dice esattamente cosa fare e gli dà qualcosa di verificabile.

Applica questo test a ogni riga: "Se la rimuovessi, Claude commetterebbe errori?" Se la risposta è no, la riga va tolta. La raccomandazione ufficiale è sotto le 200 righe per file, e alcuni team esperti lavorano con meno di 60. Non è minimalismo fine a sé stesso: un file più corto significa che ne viene letto di più.

Limita i livelli di heading a massimo tre. Usa i nomi delle sezioni che gli agenti riconoscono dalle convenzioni dei README: Commands, Structure, Conventions, Testing. Fare i creativi con i nomi delle sezioni introduce attrito, perché Claude ha visto milioni di README e ha aspettative forti su cosa vive dove.

Quando una regola continua a essere ignorata nonostante sia nel file, non aggiungere più parole intorno. Anteponi IMPORTANT: o YOU MUST. Ma usali con parsimonia, perché l'enfasi scala male. Se ogni regola è marcata come importante, l'enfasi diventa invisibile.

Cosa lasciare fuori

L'enforcement dello stile di codice è la trappola più grande. Formattazione, indentazione, ordinamento degli import: sono problemi deterministici con soluzioni deterministiche. Linters e formatter come Biome, ESLint o Ruff li gestiscono più velocemente, a costo minore e con il 100% di coerenza. Spendere budget di istruzioni su regole di stile è zavorra: lo stesso lavoro che un pre-commit hook fa gratis.

Anche le convenzioni standard del linguaggio vanno nella lista di esclusione, dato che Claude conosce già i pattern di TypeScript e le espressioni idiomatiche di Python. La documentazione API completa andrebbe linkata, non incollata. Le istruzioni specifiche per task che si applicano solo a certi flussi di lavoro appartengono alle skills, dove si caricano su richiesta invece di occupare spazio in ogni sessione.

Un pattern che vale la pena evidenziare: vincoli solo per negazione. "Non usare mai --legacy-peer-deps" lascia Claude bloccato quando incontra un conflitto di dipendenze. Abbina a ogni divieto una direzione: "Non usare mai --legacy-peer-deps; risolvi i conflitti aggiornando il pacchetto a una versione compatibile." Se hai lavorato con le Cursor Rules o file di configurazione AI simili, vedrai che questo principio vale ovunque.

Prima e dopo: un esempio reale minimale

Ecco come appare la differenza nella pratica. A sinistra, una tipica sezione CLAUDE.md generata automaticamente, piena di consigli generici che Claude già conosce. A destra, la stessa sezione dopo aver applicato il test di specificità: sopravvivono solo i fatti specifici del progetto.

La seconda versione è più corta e dice a Claude cose che non può inferire dalla codebase.

Costruire il file da zero

Esegui /init nella root del progetto per ottenere un punto di partenza generato. Leggi ogni riga, taglia ciò che è ovvio e aggiungi ciò che manca rispetto a come lavora davvero il tuo team. Partire dall'output di /init è più veloce che partire da un file vuoto, ma i contenuti generati automaticamente non dovrebbero mai essere pubblicati senza revisione.

Se preferisci scrivere da zero, inizia con cinque sezioni: 

1. Panoramica del progetto
2. Mappa delle directory
3. Comandi
4. Convenzioni
5. Particolarità

Potrai sempre ampliare il file in seguito, e partire in modo minimale significa che ogni riga che aggiungi deriva da un errore reale e non da supposizioni.

Due segnali ti dicono che il file necessita di manutenzione: 

• Claude si scusa per aver perso un'istruzione che è già lì: La formulazione è ambigua, quindi riscrivi l'istruzione.
• La stessa regola viene violata in più sessioni: Il file è troppo lungo e Claude lo sta filtrando, quindi accorcialo.

Entrambi puntano alla stessa soluzione: meno parole, struttura più chiara.

Scalare i file CLAUDE.md per i team

Un file per un singolo sviluppatore può restare così snello a tempo indeterminato. Quando entra in gioco un team, il file ha bisogno di una struttura diversa.

Controllo versione e proprietà condivisa

Il tuo CLAUDE.md a livello di progetto appartiene a git. È documentazione condivisa che migliora man mano che i compagni di squadra contribuiscono con regole nate dai propri errori. Tratta le modifiche come fai con le PR di codice: rivedile, chiediti se ogni nuova riga si merita il suo posto.

Quando le convenzioni si accumulano oltre ciò che entra in un singolo file, spostale in .claude/rules/. Ogni file Markdown copre un argomento con nomi descrittivi: testing.md, api-design.md, database-migrations.md. Claude individua questi file ricorsivamente e li carica con la stessa priorità del CLAUDE.md principale.

Le regole con ambito di percorso lo rendono ancora più mirato. Aggiungi lo YAML frontmatter, e la regola si carica solo quando Claude lavora con file corrispondenti:

---
paths:
  - "src/api/**/*.ts"
---
# API conventions go here

Le tue convenzioni frontend non consumeranno budget di istruzioni durante il lavoro backend, e viceversa.

Nei monorepo in cui i team hanno convenzioni in conflitto, claudeMdExcludes blocca il caricamento di file specifici:

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}

Mettilo in .claude/settings.local.json per tenerlo fuori dal controllo di versione.

Divulgazione progressiva e modularizzazione

Scalare un CLAUDE.md tipicamente fa venire voglia di centralizzare: un unico grande file con tutto. È la direzione sbagliata. Suddividere il CLAUDE.md di un monorepo in file a livello di servizio può ridurre il conteggio parole totale dell'80% migliorando al contempo l'aderenza di Claude alle regole; meno da leggere per sessione significa meno da filtrare.

Il principio: punta, non incorporare. Invece di @path/to/big-doc.md (che carica l'intero file in ogni sessione), scrivi "Per le procedure di migrazione, vedi docs/migrations.md." Claude lo leggerà quando ne avrà bisogno. La sintassi di import @ funziona per file piccoli, ma tutto ciò che è sostanzioso è meglio referenziarlo che incorporarlo.

I file CLAUDE.md nelle sottodirectory completano questo schema. Un frontend/CLAUDE.md con le convenzioni React si carica solo quando Claude tocca file in quella directory. Le regole del backend restano fuori dai piedi durante il lavoro frontend.

Manutenzione del tuo file CLAUDE.md

Scalare la struttura è perlopiù un problema risolto una volta che conosci le primitive. Ma i progetti cambiano e le convenzioni evolvono. Regole sensate sei mesi fa diventano rumore che soffoca quelle importanti ora. La sfida continua è mantenere il file onesto nel tempo.

Mantenere il file aggiornato

Aggiungi regole più lentamente di quanto pensi dovresti. Una nuova riga appartiene al file solo quando Claude commette un errore reale che quella riga avrebbe prevenuto. Ogni regola dovrebbe risalire a un incidente reale, non a un'ipotesi.

La direzione opposta conta altrettanto: se Claude già segue una convenzione senza che gli venga detto, quella regola è zavorra. Rimuovila e libera budget di istruzioni per regole che cambiano il comportamento.

Un'abitudine di manutenzione a basso sforzo è dire a Claude, "Rivedi questo CLAUDE.md e suggerisci miglioramenti" ogni poche settimane. Individua contraddizioni tra regole, segnala sovrapposizioni e identifica formulazioni che potrebbero essere più asciutte. 

Puoi anche aggiungere un'istruzione permanente nel file stesso: "Quando incontri un'assunzione sbagliata durante una sessione, suggerisci una correzione al CLAUDE.md". Questo crea un ciclo di feedback in cui il file migliora tramite l'uso normale.

Anti-pattern da evitare

La modalità di fallimento più comune è l'accumulo. Le regole si accumulano dopo ogni sessione frustrante, nessuno rimuove quelle che non servono più e alla fine il file diventa così lungo che Claude ne filtra metà. Quando Claude continua a ignorare una regola, aggiungere enfasi sopra un file gonfio non la risolverà. Serve potare.

Se stai usando gli import @ per file grandi, è il secondo problema da verificare. Un documento di architettura di 500 righe importato con @ incorpora l'intero documento in ogni sessione, bruciando il tuo budget di istruzioni prima che Claude processi la prima regola effettiva. Referenzialo invece.

Generare automaticamente con /init e non curarne mai l'output è un modo sicuro per ottenere comportamenti errati a tutto campo. Un'istruzione sbagliata in CLAUDE.md non influenza solo una risposta. Modella la ricerca, la pianificazione e l'implementazione di Claude in ogni sessione finché qualcuno non se ne accorge.

Regole contraddittorie tra più file causano comportamenti imprevedibili. Quando due regole confliggono, Claude ne sceglie una senza dirti quale. Questo peggiora nei progetti che combinano un CLAUDE.md root con diversi file in .claude/rules/. L'unica prevenzione è una revisione periodica di tutti i file di istruzioni.

Non ogni errore merita una nuova regola. Alcuni fallimenti sono casi isolati. Una regola aggiunta per ogni edge case crea un file pieno di istruzioni condizionali che aiutano in situazioni limitate e danneggiano nella maggior parte delle sessioni. L'obiettivo, da sempre, è lo stesso: un file corto in cui ogni riga cambia il comportamento.

Conclusione

CLAUDE.md è probabilmente il file più portante in un progetto Claude Code. Modella ogni sessione prima ancora che venga digitato un prompt, e uno ben mantenuto produce benefici composti nel corso di settimane di lavoro.

Se non ne hai ancora uno, esegui /init, leggi ciò che esce e taglia ogni riga che non impedirebbe un errore reale. Se ce l'hai, aprilo ora e applica lo stesso test. Se il tuo CLAUDE.md deve essere enorme per spiegare il progetto, è un segnale che il tooling del progetto è troppo complesso, non che ti serva un file più grande.

Il passo giusto: esamina il repo e redigi oggi stesso una base. Parti con cinque sezioni, tienilo sotto le 60 righe e lascia che siano gli errori reali a guidare ogni aggiunta.

Se vuoi creare strumenti che usano l'API di Anthropic, il nostro corso Introduction to Claude Models copre l'intera famiglia di modelli e ti insegna a usarli in modo efficace.