CLAUDE.md Best Practice: 9 Regole che Fanno Sì che Claude Ti Ascolti (2026)

CLAUDE.md Best Practice: 9 Regole che Fanno Sì che Claude Ti Ascolti (2026)

La maggior parte degli articoli sulle best practice di CLAUDE.md ti danno un template e la storia finisce lì — ma il file che hai scritto la settimana scorsa probabilmente viene già ignorato, e non lo sai. La soluzione è raramente "aggiungi altre regole." Di solito è l'opposto. Abbiamo integrato Claude Code in ogni progetto cliente recente, e queste 9 regole sono quelle che fanno davvero la differenza: una gerarchia che corrisponde a come Claude carica i file, un budget istruzioni che non puoi sforare, la decisione su AGENTS.md, e i sei motivi per cui Claude abbandona silenziosamente il tuo file a metà sessione.

Punti Chiave

• CLAUDE.md è la memoria di progetto caricata nel contesto di Claude Code — mantienilo sotto 200 righe o le regole iniziano a cadere.
• I file si caricano dall'alto verso il basso: globale, root del progetto, sottodirectory (lazy), e CLAUDE.local.md (personale, in gitignore).
• Usa AGENTS.md se usi anche Cursor o Copilot; crea un symlink da CLAUDE.md a AGENTS.md per coprire entrambi gli strumenti.
• Se Claude ignora il tuo file, nel 90% dei casi è per lunghezza, vaghezza o una "ragione" mancante.

Cos'è CLAUDE.md e Perché Conta

In breve: CLAUDE.md è un file markdown che Claude Code legge come memoria di progetto all'inizio di ogni sessione. Non è un system prompt, un hook o una skill — è un contesto consultivo che orienta Claude verso le convenzioni del tuo team. Pensalo meno come documentazione e più come un file di configurazione che il tuo pair programmer AI legge davvero.

Molti team scrivono CLAUDE.md come se fosse un README. Questo è il primo errore. Un README spiega il progetto a persone che possono scansionarlo e saltare parti. CLAUDE.md viene consumato per intero da Claude Code all'avvio della sessione, ogni riga ha un costo in token e in adesione alle regole. È molto più vicino a un file di configurazione o a un set di fixture di test che a della documentazione.

Non è nemmeno l'unico modo per guidare Claude. Gli hook eseguono azioni deterministiche (formattazione, blocco di commit). Le skill raggruppano workflow riutilizzabili. CLAUDE.md si trova nel mezzo come contesto consultivo — Claude lo valuta, a volte lo ignora, e di certo dimentica parti di esso se scrivi troppo. Questa distinzione è la base di tutto ciò che segue, ed è il motivo per cui CLAUDE.md è uno strumento nell'ambito più ampio dell'ingegneria del contesto, non una soluzione magica.

Regola n.1: Trattalo come codice, non come documentazione. Versionalo. Revisionalo nelle PR. Sfoltiscilo come faresti con un modulo gonfio. Secondo la guida CLAUDE.md di Anthropic, il file viene caricato con la stessa priorità di qualsiasi istruzione di sistema — il che significa che una regola obsoleta di sei mesi fa sta ancora attivamente influenzando ogni risposta oggi.

Come si Carica CLAUDE.md: La Gerarchia a 4 Livelli

In breve: Claude Code carica CLAUDE.md da quattro livelli: globale (~/.claude/CLAUDE.md), root del progetto, CLAUDE.local.md per override personali, e file in sottodirectory che si caricano in lazy-load solo quando Claude legge file in quella directory. Le sottodirectory adiacenti non vedono mai i rispettivi CLAUDE.md, il che mantiene la memoria di Claude Code ben circoscritta.

La gerarchia è la parte più fraintesa di CLAUDE.md, ed è dove nessuno dei primi 5 risultati SERP va in profondità. Ecco cosa succede davvero sotto il cofano:

Due termini da tenere bene a mente: lazy loading e isolamento tra sibling.

Il lazy loading significa che un CLAUDE.md in sottodirectory non entra nel contesto di Claude finché Claude non apre effettivamente un file in quella directory. Se chiedi "risolvi il bug di login" e Claude tocca solo backend/, il tuo frontend/CLAUDE.md non viene mai caricato. È un bene — mantiene la finestra di contesto pulita — ma può sorprendere i team che mettono regole critiche nelle sottodirectory aspettandosi che si applichino sempre.

L'isolamento tra sibling è il corollario: frontend/CLAUDE.md e backend/CLAUDE.md non si vedono mai. Condividono solo quello che è nel file root del progetto. Se le tue regole frontend contraddicono quelle backend, va bene. Se devono condividere una convenzione, promuovila al file root.

CLAUDE.local.md è la valvola di sfogo. Viene caricato ma non committato, perfetto per override del tipo "io preferisco pnpm ma il team ha standardizzato su npm". Il problema: non viene aggiunto automaticamente al gitignore. Devi farlo tu. Se te ne dimentichi, committi le tue regole personali nel repository del team.

Regola n.4: Abbina le istruzioni a dove Claude le legge davvero. Le regole di stile per i componenti React appartengono a frontend/CLAUDE.md, non al root. Le regole per le migrazioni del database appartengono a backend/. La documentazione Memory di Anthropic (aggiornata a novembre 2025) lo conferma — il comportamento di lazy-load è intenzionale e fondamentale.

Cosa Mettere Dentro CLAUDE.md (E Cosa Lasciare Fuori)

In breve: In CLAUDE.md va tutto ciò che Claude non può inferire dal tuo codice: comandi di build, convenzioni di nomenclatura, anti-pattern che il team ha già bruciato, e il perché dietro ogni regola. Fuori va tutto ciò che è nel README, nel package.json, e qualsiasi regola che cambia ogni settimana. Le istruzioni di Claude Code devono essere verificabili e specifiche.

Ecco un CLAUDE.md minimale che lavora davvero:

# Project: techsy-app

## Commands
- Build: `pnpm build` (Turbopack — Webpack flags don't apply)
- Test: `pnpm test --run` (we use Vitest, not Jest)
- Lint: `pnpm lint` (will fail CI on warnings, not just errors)

## Conventions
- Server components by default. Add `'use client'` only when truly needed.
  Why: we hit 8s LCP last quarter from over-clienting.
- Database access only via `lib/db/` helpers — never raw SQL in routes.
  Why: row-level security policies live in those helpers.
- Tests colocate as `*.test.ts` next to the file under test.

## Don'ts
- Don't add a new dependency without opening a PR comment first.
- Don't use `any` — use `unknown` and narrow.

## Where to look
- Schema: `db/schema.ts`
- Auth flow: `lib/auth/README.md`

Ora confrontalo con l'anti-pattern che la maggior parte dei team pubblica:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

Il secondo file non è sbagliato. È semplicemente inutile. Claude vuole già scrivere codice pulito. "Sii coerente" non dice a Claude con quale pattern essere coerente. I pubblici esempi di Boris Cherny, ingegnere di Anthropic, puntano decisamente al primo stile — comandi concreti, strumenti nominati e il perché dietro decisioni non ovvie dal solo codebase.

Regola n.2: Sii specifico, non aspirazionale. "Scrivi codice pulito" è aspirazionale. "Server component di default; aggiungi 'use client' solo quando davvero necessario" è verificabile. La stessa disciplina è alla base di un buon prompt engineering: istruzioni specifiche e verificabili battono le vaghe aspirazioni, che vivano in un prompt o in un CLAUDE.md.

Regola n.3: Spiega il perché di ogni regola. Il "perché" non è un orpello — è il modo in cui Claude gestisce i casi limite. Una regola con una ragione ("abbiamo avuto 8s di LCP per over-clienting") si generalizza a situazioni simili. Una regola senza ragione viene ignorata non appena il contesto cambia. Questo schema è documentato anche nella guida CLAUDE.md di Builder.io.

Perché Claude Sta Ignorando il Tuo CLAUDE.md? Il Budget Istruzioni

In breve: Claude non è malizioso — sta esaurendo l'attenzione. Oltre circa 80 righe noterai regole che cadono; oltre 200 righe, blocchi interi vengono ignorati; oltre 500 parole di regole dense, l'adesione collassa. La soluzione è un budget istruzioni. Tratta ogni riga come un costo sulla memoria di Claude Code e sull'adesione per singola regola.

Ricerche recenti confermano quello che gli utenti in produzione continuano a scoprire: il seguimento delle istruzioni degrada in modo non lineare con il numero di regole. Il paper arxiv 2507.11538 sulla capacità di seguire istruzioni mostra che l'adesione per regola diminuisce man mano che ne accumuli di più — e l'analisi di HumanLayer su CLAUDE.md in produzione conferma la stessa cosa.

In pratica: ogni regola che aggiungi rende ogni altra regola leggermente meno probabile di essere seguita. Un CLAUDE.md di 400 righe non è 4 volte più efficace di uno da 100 righe. Spesso è meno efficace, perché le regole che ti importano davvero si diluiscono con quelle che hai scritto un venerdì tre mesi fa e non hai mai cancellato.

Nei nostri file CLAUDE.md, tutto ciò che supera la riga 150 inizia a perdere visibilmente adesione. Oltre la riga 250 abbiamo visto Claude saltare sezioni intere. Quindi impostiamo un limite.

wc -l CLAUDE.md

Questo è l'intero strumento. Eseguilo. Se sei sopra 200, hai sforato il budget. La regola ferma che consegniamo ai clienti:

Tratta CLAUDE.md come un budget da 200 righe. Ogni riga ha un costo in adesione. Spendilo dove conta.

Regola n.1 rafforzata: Tienilo corto. Sotto 200 righe. Sotto 500 parole di regole dense. Se vuoi aggiungere regole di automazione ("esegui sempre prettier dopo le modifiche"), quelle appartengono probabilmente agli hook di Claude Code — gli hook sono deterministici e non consumano token dal budget istruzioni.

CLAUDE.md, AGENTS.md, .cursorrules o copilot-instructions: Quale Usare?

In breve: Se usi solo Claude Code, CLAUDE.md va bene. Se usi due o più CLI per agenti (Codex, Cursor, Copilot, Sourcegraph), passa a AGENTS.md e crea un symlink da CLAUDE.md a AGENTS.md. AGENTS.md è emerso alla fine del 2025 come standard cross-tool — la maggior parte degli agenti moderni ricade su di esso, quindi un singolo file alimenta ogni ecosistema.

Questa è la domanda a cui nessuno dei primi 5 risultati risponde davvero. Ecco la matrice:

Il trucco del dual-target è una riga:

ln -s AGENTS.md CLAUDE.md

Tutto qui. Ora Claude Code, Codex e qualsiasi strumento che supporta AGENTS.md leggono lo stesso file. Aggiorna una volta, ogni agente lo recepisce. La specifica AGENTS.md è aperta e volutamente minimale — è solo markdown con sezioni convenzionali.

Due complicazioni reali. Prima: se il tuo team ha un power user di Cursor, le .cursorrules di Cursor adottano un approccio diverso — un solo file, nessuna gerarchia, formato più rigido. Alcuni team tengono entrambi: AGENTS.md per le regole condivise, .cursorrules per le peculiarità specifiche di Cursor. Seconda: il .github/copilot-instructions.md di Copilot non ricade su AGENTS.md, quindi i team che usano molto Copilot hanno bisogno di un file separato.

Se stai scegliendo uno stack di agenti da zero, il nostro confronto Claude Code vs Cursor vs Copilot copre i trade-off a livello di harness. In breve: la gerarchia di Claude Code è la più potente per i monorepo, la UX di Cursor vince per il lavoro in solitaria, l'integrazione IDE di Copilot è ancora la più fluida per l'adozione incrementale.

Regola n.9: Usa AGENTS.md se esegui più di una CLI di agenti. Non mantenere due file che dicono la stessa cosa. Scegli il file che la maggior parte del tuo stack legge, crea symlink per il resto.

CLAUDE.md vs Hook vs Skill: Il Triangolo Decisionale

In breve: CLAUDE.md = contesto consultivo. Hook = azioni deterministiche. Skill = capacità raggruppate. Scegli quello sbagliato e brucerai budget istruzioni su qualcosa che dovrebbe gestire un hook, oppure scriverai una regola CLAUDE.md per qualcosa che solo una skill può fare davvero. Il triangolo è il modo più economico per mantenere CLAUDE.md snello.

Tre strumenti, tre lavori. L'errore che vediamo più spesso: mettere "esegui sempre prettier dopo la modifica" in CLAUDE.md. Claude lo legge. Claude a volte esegue prettier. Tu sei frustrato. La soluzione è spostare quella riga fuori da CLAUDE.md e in un hook — perché gli hook si attivano deterministicamente ogni volta, senza margine di discrezionalità.

Se una regola deve sempre scattare, va in un hook. Se è una preferenza stilistica che Claude può valutare in base al contesto, va in CLAUDE.md. Se è un workflow multi-step con asset raggruppati (template, script, prompt), va in una skill.

Regola n.8: Scegli correttamente tra CLAUDE.md, hook e skill — mettere un hook in CLAUDE.md è lo spreco più comune di budget istruzioni. Configura le azioni deterministiche con gli hook di Claude Code e pacchettizza i workflow riutilizzabili come skill di Claude. Il tuo CLAUDE.md diventa più corto, i tuoi guardrail diventano più solidi, e Claude smette di "dimenticare" le regole che contano.

Pattern per Monorepo: CLAUDE.md Annidati, @import e .claude/rules/

In breve: In un monorepo, tieni il CLAUDE.md root minuscolo — solo puntatori e convenzioni condivise. Sposta i dettagli in apps/*/CLAUDE.md in modo che ogni sottoalbero abbia regole circoscritte. Usa gli @import per condividere file di regole modulari tramite .claude/rules/. Questo è il principio della divulgazione progressiva — Claude tira ogni pezzo solo quando è rilevante.

Un tipico albero CLAUDE.md per monorepo:

.
├── CLAUDE.md                        # 30 righe — punta alle subdir e alle regole condivise
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Regole specifiche per Next.js
│   └── api/
│       └── CLAUDE.md                # Regole specifiche per Fastify
└── packages/
    └── shared/
        └── CLAUDE.md                # Regole per gli autori di librerie

La sintassi @import consente al file root di includere frammenti di regole condivise senza riscriverli:

# Root CLAUDE.md

This is a Turborepo. See subdir CLAUDE.md for app-specific rules.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md

## Top-level commands
- `pnpm dev` runs all apps in parallel
- `pnpm test` runs every workspace's test script

Questo è il principio della divulgazione progressiva in pratica. Il file root è un puntatore di 30 righe. Ogni CLAUDE.md di sottodirectory aggiunge 50-80 righe di regole mirate. I file .claude/rules/ contengono frammenti di convenzioni che più sottodirectory possono includere. Nulla viene duplicato, nulla viene tralasciato, e nessun singolo file supera il budget istruzioni.

La regola del lazy-loading menzionata prima conta ancora di più qui: quando Claude lavora su apps/web/Button.tsx, vede il file root più apps/web/CLAUDE.md più i file di regole importati via @import. Non vede apps/api/CLAUDE.md. Questo è l'obiettivo — le convenzioni del backend non inquinano il contesto del frontend, e la finestra di contesto rimane utilizzabile.

Regola n.6: Usa @import per mantenere il file root sotto 200 righe. La guida Best Practices di Anthropic per Claude Code tratta questo come il pattern standard per i monorepo. Anche i subagent ereditano il contesto CLAUDE.md del genitore, cosa utile da sapere se stai annidando workflow — vedi la guida all'ingegneria del contesto per come questo interagisce con il design dei subagent.

6 Motivi per Cui Claude Ignora il Tuo File (E il Fix per Ciascuno)

In breve: Quando Claude ignora CLAUDE.md, quasi sempre è una di queste sei cause: file troppo lungo, formulazione vaga, "perché" mancante, compattazione del contesto, file genitore in conflitto, o nome file errato. Ognuna ha un fix da 60 secondi. Testa in una sessione fresca dopo ogni modifica — questa è la Regola n.7.

1. File troppo lungo (>200 righe / >500 parole)

Esegui wc -l CLAUDE.md. Se supera 200, taglia in modo aggressivo. Sposta le regole di automazione negli hook. Sposta i workflow nelle skill. Dividi i frammenti condivisi in .claude/rules/ e includili con @import. Il motivo più comune per cui Claude "ha smesso di seguire" le tue regole è che il file è diventato troppo lungo nel tempo e l'adesione è collassata silenziosamente.

2. Formulazione vaga ("scrivi codice pulito")

Sostituisci ogni regola aspirazionale con una specifica e verificabile. "Sii coerente" è invisibile a Claude. "Usa server component di default; aggiungi 'use client' solo per form o UI interattiva" è qualcosa che Claude può effettivamente applicare.

3. Manca il "perché"

Le regole senza ragioni non si generalizzano. Claude non può intuire quando piegare la regola perché non sa cosa sta proteggendo. Ogni regola non ovvia riceve una riga: "usiamo unknown invece di any perché abbiamo avuto tre crash a runtime da risposte API tipizzate come any l'ultimo trimestre."

4. La compattazione del contesto l'ha buttato via

Le sessioni lunghe attivano la compattazione — Claude riassume il contesto precedente per adattarsi alla finestra, e il contenuto di CLAUDE.md a volte finisce riassunto fino all'oblio. La soluzione: usa /clear dopo grandi consumi di contesto, oppure riavvia la sessione. È esattamente quello che GitHub Issue #17530 continua a far emergere.

5. CLAUDE.md genitore in conflitto

Il globale dice "usa 4 spazi." Il root del progetto dice "usa 2 spazi." La sottodirectory non dice nulla. Claude ne sceglie uno — a volte quello sbagliato. Controlla ~/.claude/CLAUDE.md e il root del progetto per contraddizioni. Chi è più specifico dovrebbe vincere, ma solo se lo rendi esplicito.

6. Posizione del file o maiuscole nel nome errate

Claude.md e CLAUDE.md sono file diversi su Linux e macOS. Lo stesso vale per claude.md e CLAUDE.md. Verifica che il percorso sia esattamente ./CLAUDE.md (tutto in maiuscolo), e che Claude Code sia avviato dalla directory che lo contiene. GitHub Issue #668 è pieno di casi in cui il file esisteva ma Claude non riusciva a vederlo per problemi di percorso.

Regola n.7: Testa in una sessione fresca. Dopo qualsiasi modifica a CLAUDE.md, apri una nuova sessione e chiedi a Claude di "riassumere le regole in CLAUDE.md." Se il riassunto manca qualcosa, il file non sta facendo il suo lavoro.

Il Tuo Primo CLAUDE.md in 10 Minuti: Un Punto di Partenza in 5 Passi

In breve: Esegui /init per generare una bozza, riducila a 6-10 regole reali con le ragioni, aggiungi 3 comandi che Claude deve conoscere, aggiungi 2 anti-pattern che il tuo team ha già incontrato, poi testa in una sessione fresca chiedendo a Claude di riassumere il file. Tempo totale: circa 10 minuti. La ricetta in 5 passi è quella che usiamo il giorno 1 di ogni nuovo repository.

1. Esegui /init per generare una bozza. Il comando /init di Claude Code scansiona il tuo repository e scrive un CLAUDE.md iniziale. Non pubblicare quello che genera. L'output di /init è un punto di partenza, non un file finito — e, francamente, la maggior parte di quello che produce può andare.

2. Riducilo a 6-10 righe di regole reali con le ragioni. Elimina tutto ciò che è generico. Elimina tutto ciò che è nel README. Tieni solo le regole che Claude non riesce a inferire dal codice stesso.

3. Aggiungi 3 comandi che Claude deve conoscere. Build, test, lint. Includi il comando esatto e i flag non ovvi. Se usi Vitest invece di Jest, dillo esplicitamente.

4. Aggiungi 2 anti-pattern che questo team ha già incontrato. Reali. "Non usare any perché abbiamo avuto tre crash a runtime" batte "usa TypeScript correttamente" ogni volta.

5. Apri una sessione fresca e verifica. Chiedi a Claude di "riassumere le regole in CLAUDE.md." Se manca qualcosa, il file è troppo lungo, troppo vago, o manca un "perché." Correggi e ripeti.

Regola n.5: Non fare affidamento solo su /init per il file finale. /init è un punto di partenza, non un file finito. Gli 8 minuti che passi a sfoltirlo sono quelli in cui il valore si crea.

Domande Frequenti

Cos'è un file CLAUDE.md?

Un file CLAUDE.md è un file markdown che Claude Code legge come memoria di progetto all'inizio di ogni sessione. Dice a Claude le tue convenzioni, i comandi e gli anti-pattern in modo che non debba indovinare. Funziona a quattro livelli: globale, root del progetto, sottodirectory (lazy-loaded) e un CLAUDE.local.md personale che tieni in gitignore.

Quanto deve essere lungo un file CLAUDE.md?

Sotto 200 righe e sotto 500 parole di regole dense. Oltre queste soglie, il seguimento delle istruzioni di Claude degrada — ogni regola che aggiungi rende ogni altra regola leggermente meno probabile di essere seguita. Trattalo come un budget fisso. Se hai bisogno di più, dividi in file CLAUDE.md di sottodirectory e usa @import per i frammenti condivisi.

Dove devo mettere CLAUDE.md?

Il principale va nella root del progetto (./CLAUDE.md) e viene committato. Aggiungi file CLAUDE.md nelle sottodirectory per regole specifiche per app nei monorepo. Metti le preferenze cross-progetto in ~/.claude/CLAUDE.md. Usa CLAUDE.local.md per gli override personali che non vuoi committare — ma ricordati di aggiungerlo al gitignore manualmente.

Perché Claude sta ignorando il mio CLAUDE.md?

Nel 90% dei casi è una di tre cose: il file è troppo lungo (oltre 200 righe), le regole sono vaghe ("scrivi codice pulito"), o le regole mancano di un "perché" che Claude possa usare per applicarle. Esegui wc -l CLAUDE.md, poi controlla la specificità. Testa le modifiche in una sessione fresca chiedendo a Claude di riassumere il file.

Devo usare CLAUDE.md o AGENTS.md?

Se il tuo team usa solo Claude Code, rimani con CLAUDE.md. Se usi due o più CLI di agenti (Codex, Cursor, Sourcegraph), passa a AGENTS.md e crea un symlink da CLAUDE.md: ln -s AGENTS.md CLAUDE.md. La maggior parte delle CLI di agenti moderne ricade su AGENTS.md, quindi un file alimenta ogni strumento.

Devo eseguire /init per generare CLAUDE.md?

Sì — come bozza. No — come file finito. /init scansiona il tuo repository e produce un punto di partenza, ma è prolisso e generico. Sia Anthropic che HumanLayer raccomandano di tagliare in modo aggressivo dopo /init. Gli 8 minuti che passi a tagliare e ad aggiungere le righe del "perché" sono quelli in cui il file diventa davvero utile.

Come funzionano i file CLAUDE.md in un monorepo?

Il CLAUDE.md root rimane minuscolo — solo puntatori e regole condivise. Ogni app ha il proprio apps/*/CLAUDE.md con convenzioni circoscritte. I file di sottodirectory si caricano in lazy-load solo quando Claude legge file in quel sottoalbero, così i sibling restano isolati. Usa @import .claude/rules/style.md per condividere frammenti di regole modulari senza duplicarli tra le app.

Qual è la differenza tra CLAUDE.md, hook e skill?

CLAUDE.md è contesto consultivo — Claude lo legge e di solito lo segue. Gli hook sono azioni deterministiche che si attivano sempre (formattazione, blocco di commit). Le skill sono capacità raggruppate per workflow riutilizzabili con asset. Usa CLAUDE.md per la guida stilistica, gli hook per le regole rigide, e le skill per i lavori multi-step che ripeterai su più progetti.

Come Techsy Approccia Questo

In Techsy, ogni progetto Claude Code che consegniamo ha un CLAUDE.md sotto 150 righe e un symlink AGENTS.md. Trattiamo il file come codice — lo versioniamo, revisioniamo le modifiche nelle PR, e ri-testiamo in sessioni fresche prima del merge. Hai bisogno di aiuto per integrare agenti AI nel tuo workflow di sviluppo? Richiedi una consulenza gratuita.