Come Scrivere un CLAUDE.md che Funziona Davvero

Ogni volta che avvii Claude Code, la prima cosa che fa è leggere un file: CLAUDE.md.

È un file Markdown che viene iniettato nel system prompt di ogni conversazione. Contiene le istruzioni del tuo progetto: stack tecnologico, comandi, convenzioni, architettura, cose da non fare. È la differenza tra un agente che capisce il tuo progetto e uno che lavora alla cieca.

Il problema è che la maggior parte dei CLAUDE.md là fuori è o troppo lunga, o troppo generica, o piena di cose che Claude sa già. E un CLAUDE.md scritto male non è neutro — è attivamente dannoso, perché consuma context window senza dare valore.

Questa guida ti spiega come scriverne uno che funziona.

La Gerarchia: 6 Livelli di Istruzioni

Claude Code non legge un solo CLAUDE.md. Ne legge diversi, a livelli, dal più generico al più specifico:

Le istruzioni più specifiche hanno precedenza su quelle più generiche. I file nelle directory figlie vengono caricati on demand — solo quando Claude lavora su file in quelle cartelle.

Il CLAUDE.local.md viene aggiunto automaticamente al .gitignore — è il posto giusto per le tue preferenze personali che non vuoi condividere col team.

La regola pratica

• User Memory (~/.claude/CLAUDE.md): preferenze che valgono per TUTTI i tuoi progetti (es: "usa git bash su Windows", "non fare commit senza chiedere")
• Project Memory (./CLAUDE.md): tutto ciò che il team deve sapere (stack, comandi, architettura)
• Rules (.claude/rules/): regole specifiche per area (frontend, backend, testing)
• Local (./CLAUDE.local.md): le tue abitudini personali su quel progetto

Cosa Metterci

Il principio guida lo dà Anthropic stessa:

"Per ogni riga del CLAUDE.md, chiediti: rimuovere questa istruzione causerebbe errori a Claude? Se la risposta è no, eliminala."

Il framework: COSA-PERCHÉ-COME

COSA — Il progetto, lo stack, la struttura. PERCHÉ — Le decisioni architetturali e il motivo dietro le scelte. COME — I comandi, il workflow, le regole operative.

Cosa ha senso includere

Esempio concreto

Ecco un CLAUDE.md reale per un progetto Nuxt:

# Agent Coding Italia

Blog statico su AI e coding.

## Stack
- Nuxt 4.3.0 + @nuxt/content v3 + TailwindCSS
- SSG: `nuxt generate` (NON SSR)
- Deploy: `python deploy.py` (FTP su Windows Server/IIS)

## Comandi
- `npm run dev -- --port 3002` — dev server
- `npm run generate` — build statico
- `python deploy.py` — build + deploy FTP

## Architettura contenuti
- Collezioni: articles, guides, tools, videos, lives, teoria, news
- Definite in `content.config.ts`
- API: `queryCollection('collectionName').all()` (v3 syntax)
- File con `_` prefix sono draft (es: `_articolo-bozza.md`)

## Convenzioni
- useContentData composable per tutte le query (MAI getCachedData: () => null)
- Immagini: `/public/images/{sezione}/{slug}.webp` (1536x1024)
- Ogni articolo ha frontmatter: title, description, publishedAt, author, image, category, tags, readingTime

## Cose da NON fare
- NON usare getCachedData: () => null in useAsyncData (causa contenuti vuoti)
- NON caricare su IIS file con nomi troppo lunghi (>40 caratteri)

60 righe. Zero fuffa. Tutto quello che serve a Claude per lavorare correttamente su questo progetto.

Cosa NON Metterci

Questo è il punto dove la maggior parte dei CLAUDE.md fallisce.

1. Cose che Claude sa già

❌ "Scrivi codice pulito e ben organizzato"
❌ "Usa nomi di variabili significativi"
❌ "Gestisci gli errori correttamente"

Claude lo fa già. Stai sprecando token per dirgli di fare il suo lavoro.

2. Regole di stile che un linter fa meglio

❌ "Usa 2 spazi per l'indentazione"
❌ "Metti sempre il punto e virgola"
❌ "Ordina gli import alfabeticamente"

Come dice il team di HumanLayer: "Never send an LLM to do a linter's job." Se hai ESLint o Prettier configurato, usa gli hooks per eseguirli automaticamente dopo ogni modifica. È deterministico, veloce e non consuma context.

3. Documentazione lunga

❌ "La nostra API REST segue questi pattern: [300 righe di documentazione]"

Usa invece un puntatore:

✅ "Per i pattern API, vedi docs/api-patterns.md"

Claude leggerà il file quando ne avrà bisogno. Non serve caricarlo in ogni sessione.

4. Credenziali e segreti

Il CLAUDE.md va in git. Mai metterci API key, password o token. Usa il CLAUDE.local.md (che è in .gitignore) per riferimenti a variabili d'ambiente locali.

5. Un CLAUDE.md troppo lungo

La ricerca mostra che la qualità con cui i modelli seguono le istruzioni degrada linearmente con il numero di istruzioni. Con un CLAUDE.md da 500+ righe, le regole importanti si perdono nel rumore.

La community concorda: sotto le 200 righe è l'ideale. HumanLayer tiene il suo sotto le 60.

Il Sistema @imports

Non serve mettere tutto in un file. CLAUDE.md supporta gli import:

# Progetto

Vedi @README.md per overview del progetto
Convenzioni API: @docs/api-conventions.md
Workflow git: @docs/git-workflow.md

I path sono relativi al file che contiene l'import. Supporta fino a 5 livelli di profondità. Al primo utilizzo, Claude Code chiede conferma.

Questo è il pattern giusto per progetti grandi: un CLAUDE.md snello con puntatori a documenti di dettaglio.

Rules Directory: Regole Modulari

Per progetti con più aree (frontend, backend, infra), le regole modulari in .claude/rules/ sono più efficaci di un unico CLAUDE.md monolitico.

.claude/rules/
  frontend.md
  backend.md
  testing.md
  security.md

Il vantaggio: puoi usare path-specific targeting con frontmatter YAML:

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# Regole API
- Tutti gli endpoint includono validazione input
- Usa il formato standard per le risposte errore
- I test vanno in `__tests__/` accanto al file sorgente

Le regole senza frontmatter paths si applicano a tutti i file. Quelle con paths si caricano solo quando Claude lavora su file corrispondenti. Supporta glob patterns: **/*.ts, src/**/*, *.{ts,tsx}.

Risultato: meno token consumati perché le regole si caricano on demand, e più precisione perché le regole sono specifiche per il contesto.

Hooks vs CLAUDE.md: Quando Usare Cosa

La regola: se un'azione deve succedere il 100% delle volte (linting, formatting, validazione), usa un hook. Se è una preferenza o una convenzione che richiede giudizio, mettila nel CLAUDE.md.

Un hook tipico per linting:

{
  "hooks": {
    "postEdit": {
      "command": "npx eslint --fix $FILE"
    }
  }
}

Nessun token speso. Nessuna possibilità che Claude "dimentichi".

Confronto: CLAUDE.md vs .cursorrules vs AGENTS.md

Ogni tool ha il suo sistema di configurazione. Ecco come si confrontano:

AGENTS.md: lo standard aperto

AGENTS.md è uno standard aperto sotto la Linux Foundation, adottato da 60.000+ progetti open source. Lo supportano Codex, Cursor, Amp, Google Jules, Zed, Warp e molti altri.

Claude Code non supporta AGENTS.md nativamente (c'è una feature request aperta su GitHub). Il workaround: crea un AGENTS.md come source of truth e importalo nel CLAUDE.md:

# CLAUDE.md
@AGENTS.md

Se usi più tool

Se alterni tra Claude Code e Cursor (o altri), il consiglio è:

1. Mantieni un AGENTS.md come documentazione universale del progetto
2. Crea file tool-specific (CLAUDE.md, .cursorrules) che importano AGENTS.md e aggiungono solo le istruzioni specifiche per quel tool

In questo modo non duplichi informazioni e ogni tool ha le sue regole specifiche.

L'Impatto sulla Context Window

Ogni riga del CLAUDE.md viene caricata in ogni sessione. Su una context window di 200K token, il budget è limitato:

• System prompt: ~5-15K token
• CLAUDE.md + rules: ~1-10K token
• MCP tools schema: ~5-20K token
• Spazio per lavorare: ~140-150K token

Un CLAUDE.md da 300 righe consuma circa 2-5K token. Non sembra molto, ma sommato a rules, MCP tools e system prompt, il contesto disponibile si riduce velocemente.

Strategie

• Prompt caching: Anthropic applica automaticamente il caching per il CLAUDE.md — le parti statiche costano meno nelle richieste successive
• Rules con path targeting: si caricano solo quando servono
• @imports: Claude legge i file referenziati solo quando ne ha bisogno
• /clear tra task non correlati: resetta il contesto accumulato

Tips dai Power User

Boris Cherny (creatore di Claude Code)

Il suo setup è "sorprendentemente vanilla":

• Un singolo CLAUDE.md condiviso col team, committato in git
• Il team lo aggiorna più volte a settimana: "Anytime we see Claude do something incorrectly we add it to the CLAUDE.md, so Claude knows not to do it next time"
• Usa Plan Mode prima di tutto, poi auto-accept
• La cosa più importante: dare a Claude un modo per verificare il suo lavoro — questo da solo raddoppia la qualità

Pattern ricorrenti della community

Tratta il CLAUDE.md come codice. Fai review quando qualcosa va storto, pruna le regole che non servono più, testa le modifiche.

Enfasi per istruzioni critiche. "IMPORTANT" o "MAI" migliorano l'aderenza. Ma usali con parsimonia — se tutto è importante, niente lo è.

Il tasto #. Premendo # all'inizio di un messaggio in Claude Code, puoi aggiungere rapidamente una nota al CLAUDE.md senza aprire il file. Utile quando Claude fa un errore e vuoi che non lo ripeta.

Compaction personalizzata. Quando il contesto si riempie, Claude riassume la conversazione. Puoi guidare cosa preservare:

## Compaction
Quando comprimi il contesto, preserva SEMPRE la lista completa dei file modificati.

Checklist Finale

Prima di committare il tuo CLAUDE.md, verifica:

• Sotto le 200 righe? Se no, probabilmente stai includendo cose inutili
• Ogni riga è necessaria? Se la togli, Claude farebbe errori?
• Zero credenziali? API key, password, token devono stare altrove
• Niente ovvietà? "Scrivi codice pulito" non serve a nessuno
• Niente regole da linter? Usa hooks per formatting e linting
• Comandi specifici? Dev server, test runner, deploy — tutto ciò che Claude non può indovinare
• Gotcha documentati? Comportamenti non ovvi, bug noti, cose che rompono

Se il tuo CLAUDE.md supera questo filtro, hai un file che funziona davvero — non uno che occupa spazio nel contesto sperando che Claude lo legga.

Fonti e approfondimenti:

• Anthropic - Using CLAUDE.md Files — Guida ufficiale
• Claude Code - Best Practices — Documentazione ufficiale
• Claude Code - Memory Management — Gerarchia completa dei file
• HumanLayer - Writing a Good CLAUDE.md — Anti-pattern e framework WHAT-WHY-HOW
• Builder.io - How to Write a Good CLAUDE.md — Guida pratica con esempi
• Boris Cherny - How I Use Claude Code — Setup del creatore di Claude Code
• AGENTS.md - Standard Aperto — Lo standard Linux Foundation
• awesome-claude-md (GitHub) — Collezione di CLAUDE.md da progetti open source