CLAUDE.md fatto bene: le istruzioni che contano davvero (e quelle inutili)

Claude Code parte ogni sessione con il contesto vuoto. Il CLAUDE.md è il file che l'agente legge all'avvio, quindi ogni riga che contiene si paga a ogni task, che serva o no. Il problema più comune è un file lungo che descrive il codice (che l'agente sa leggere da solo) e si porta dietro uno storico delle modifiche che nessuno consulta.

Il CLAUDE.md di questo sito è di 45 righe. Qui spiego cosa c'è dentro, perché ogni riga resta, e cosa ho spostato altrove o cancellato. Gli esempi sono in inglese perché il file lo è: lo legge un agente, e serve a chiunque lavori sulla repo.

Cosa fa Claude Code con il file CLAUDE.md?

All'avvio della sessione Claude Code carica i file CLAUDE.md nel contesto. La documentazione ufficiale sulla memoria ne descrive quattro livelli: una policy gestita a livello di organizzazione, un file utente in ~/.claude/CLAUDE.md valido per tutti i progetti, un file di progetto ./CLAUDE.md condiviso tramite git, e un CLAUDE.local.md per le note personali da tenere fuori dal versionamento. I file nelle cartelle superiori si caricano subito, quelli nelle sottocartelle solo quando l'agente tocca un file lì dentro. Vengono concatenati: nessuno sovrascrive l'altro, si sommano.

Due frasi della documentazione guidano il modo in cui lo scrivo. Claude tratta questi file come contesto e non come configurazione vincolante ("context, not enforced configuration"): per bloccare un'azione in ogni caso serve un hook PreToolUse. E più le istruzioni sono specifiche e concise, più Claude le segue con costanza. Il limite suggerito è sotto le 200 righe per file, perché un file più lungo consuma contesto e riduce l'aderenza.

Quali istruzioni vanno messe nel CLAUDE.md?

Una riga merita il CLAUDE.md se l'agente non può ricavarla dal codice e sbagliarla costa qualcosa. Comandi di build, package manager, il comando di test che conta, regole di consegna, convenzioni che vanno contro il default del framework. La documentazione suggerisce di partire dall'output di /init e di aggiungere le istruzioni che Claude non scoprirebbe da solo.

Questo è il cuore del CLAUDE.md di progetto di questo sito, con qualche riga in meno:

# CLAUDE.md

Bilingual (en/it) portfolio: Next.js 16 App Router, React 19, Tailwind v4,
deployed on Vercel from `main`. `AGENTS.md` points here.

## Rules

- **TDD, non-negotiable.** Failing test first, then the code. Skills `tdd` + `testing`.
- **Code** follows CODING_STANDARDS.md; `/ship` reviews every diff against it.
- **Docs = current state only.** When behavior changes, update or delete the
  old text in the same diff. No history (git has it).
- **Map is part of the diff**: update affected cards in the same session (map/CLAUDE.md).
- **Never open PRs**: `/ship` merges into `main` and pushes.
- **pnpm only**: never npm/yarn.
- **Type errors don't fail the build** (`ignoreBuildErrors`): run `pnpm typecheck`.
- **New translatable string**: add the key to both `en.json` and `it.json`.

## Where to find things

| You need...                 | Open                        |
| --------------------------- | --------------------------- |
| why a choice was made       | docs/adr/                   |
| how code must be written    | CODING_STANDARDS.md         |
| what a change hits          | map/CLAUDE.md               |
| tests: layer, how to run    | `testing` skill             |
| shipping config             | .agents/ship.md             |

Conviene prendere le regole una per una e chiedersi se l'agente ci arriverebbe da solo. "pnpm only" si intuisce dal lockfile, ma un agente che lancia npm install per abitudine crea un secondo lockfile, quindi la riga resta. "Type errors don't fail the build" va contro quello che chiunque si aspetta da un progetto Next.js, perché next.config imposta ignoreBuildErrors: senza quella riga una build verde sembra la prova che i tipi siano a posto. "Never open PRs" è una scelta di processo che sta nella mia testa e in una configurazione di rilascio, non nel codice sorgente. Nessuna di queste regole uscirebbe dalla lettura del codice.

Lo stile è all'imperativo e breve. Una regola per punto, il motivo al massimo in un inciso, e in grassetto la parola che l'agente deve ricordare.

Perché nel CLAUDE.md conviene linkare invece di scrivere tutto?

La seconda metà del file è una tabella, "Where to find things", che associa un bisogno a un file: perché è stata presa una decisione (le ADR), come va scritto il codice (CODING_STANDARDS.md), cosa tocca una modifica (la mappa del sistema), come si eseguono i test (una skill). Ogni rimando costa una riga di contesto, e l'agente apre il file di destinazione solo quando il task lo richiede.

CODING_STANDARDS.md ha 48 righe di regole, come niente commenti nel codice sorgente e niente segreti in log o traceback, ognuna con un breve "Why". Non sta nel CLAUDE.md perché serve solo quando si scrive codice, e lo step di review controlla comunque ogni diff contro quel file. La mappa del sistema ha un suo map/CLAUDE.md di 25 righe, che Claude Code carica solo quando l'agente lavora dentro map/. AGENTS.md nella root è una frase sola: tutte le istruzioni sono nel CLAUDE.md, non duplicare le regole qui.

Come scrivi il rimando decide quando l'agente lo segue. "Map is part of the diff: update affected cards in the same session" funziona molto meglio di un generico "vedi map/", perché dice quando (a ogni modifica) e cosa fare (aggiornare le schede).

Come si dividono il lavoro CLAUDE.md di progetto, file globale e skill?

Uso tre livelli. Per decidere dove va un'istruzione mi chiedo a chi serve e quanto spesso.

Il file globale in ~/.claude/CLAUDE.md contiene il modo in cui lavoro su qualsiasi repo. Il mio è corto e parla quasi solo di errori che ho visto fare a un agente più di una volta. Una regola dice di aprire un git worktree prima di modificare una repository e di restituirlo alla fine, perché più agenti in parallelo sulla stessa cartella si sovrascrivono il lavoro. Un'altra riguarda un ciclo di attesa che non termina mai:

# Global

## Isolated / parallel work
If you need to edit files in a repo, open a git worktree first and work only there.
Never leave worktrees behind: return them when done.

## Local tools
My CLI tools are listed in a separate file. Read it before reinventing one.

## Waiting on processes
Never wait with `until ! pgrep -f "X"` inside a Bash command: the pattern matches
the shell running the loop, and it never ends. Run the job in the background and
wait for the notification, or use `wait <pid>`.

La regola descrive il guasto con precisione: pgrep -f trova anche la shell che lo esegue, quindi il ciclo non esce. Un generico "fai attenzione quando aspetti un processo" non cambierebbe nulla.

Il CLAUDE.md di progetto contiene quello che vale per questa repo e per chiunque ci lavori. Le skill contengono le procedure. Qui ci sono skill di progetto in .claude/skills/ per TDD, test, rilascio, triage e scrittura degli articoli del blog. Claude Code carica il corpo di una skill solo quando viene invocata o ritenuta pertinente, quindi una procedura di 120 righe per scrivere un articolo non costa nulla mentre sistemo un bug di CSS. La documentazione dice lo stesso: procedure in più passi e istruzioni che valgono per una sola parte del codice vanno in una skill o in una regola con percorso in .claude/rules/.

Cosa significa "docs = current state only" per un agente?

Una regola del CLAUDE.md di questa repo dice che documentazione, PRD, piani e mappa descrivono cosa fa il codice oggi: quando il comportamento cambia, il testo vecchio si aggiorna o si cancella nello stesso diff, e lo storico resta in git. Con gli agenti questa regola conta più che con le persone. Uno sviluppatore legge "prima facevamo X, ora Y" e salta la prima metà. Un agente può prendere entrambe come istruzioni, o seguire quella vecchia perché arriva prima.

Per questo nel CLAUDE.md non compaiono mai "in precedenza" o "dopo la migrazione". Quando una regola cambia, la riga vecchia sparisce nello stesso commit della modifica al codice. La mappa segue la stessa disciplina, scritta in map/CLAUDE.md: gli aggiornamenti sono proporzionati alla modifica e il testo si riscrive solo se cambia il comportamento.

Cosa non bisogna mettere nel CLAUDE.md?

Tutto quello che l'agente ricava leggendo la repo: alberi delle cartelle, elenchi dei componenti, le convenzioni standard del framework, un riassunto del package.json. Costa token a ogni sessione e diventa falso la prima volta che qualcuno rinomina una cartella. Via anche lo storico: changelog, racconti del tipo "abbiamo provato X e non andava" senza una regola che ne derivi, e consigli generici come "scrivi codice pulito". La documentazione dà un buon esempio: meglio "gli handler delle API stanno in src/api/handlers/" che "tieni i file organizzati".

Le preferenze personali restano fuori dal file condiviso. Abitudini dell'editor, URL di test, account di prova vanno in CLAUDE.local.md o nel file globale, non in un documento che leggono gli agenti di tutto il team. Se nel CLAUDE.md di progetto finiscono credenziali o dati di clienti, il problema è anche di GDPR, oltre che di ordine: quel file finisce in git e nel contesto di ogni sessione.

Quali sono gli errori più comuni con il CLAUDE.md?

Lanciare /init e committare il risultato così com'è. /init produce una prima bozza sensata analizzando il codice, quindi è piena di cose che il codice dice già. Tieni i comandi, cancella la descrizione.

Usare il CLAUDE.md come blocco. Se l'agente non deve mai fare push su main o toccare un file di segreti, una frase in un file di contesto resta una richiesta. Permessi e hook sono il meccanismo che blocca davvero.

Scrivere regole senza il guasto che prevengono. "Attenzione ai processi" non dà all'agente niente su cui agire. "pgrep -f trova la sua stessa shell, usa wait <pid>" sì.

Duplicare le regole tra CLAUDE.md, AGENTS.md, README e wiki aziendale. Le copie divergono e l'agente si ritrova due versioni tra cui scegliere. Una fonte sola, le altre rimandano lì.

Non potare mai. Una regola scritta per un bug risolto da tempo continua a costare contesto a ogni esecuzione. Quando rileggi il file, cancella con la stessa facilità con cui aggiungi.

Se invece di configurare un assistente di coding stai costruendo agenti per la tua azienda, gli stessi principi valgono per prompt di sistema e descrizioni dei tool. È il lavoro che faccio nel servizio di sviluppo di agenti AI.