Come scrivere un CLAUDE.md utile per il progetto

La terza volta che scrivi «non modificare i file generati» hai già pagato due volte la stessa correzione. Quella frase può diventare un'istruzione di progetto. Ma se nel file aggiungi anche la storia del repository, la guida completa alle API e il resoconto dell'ultimo errore, la regola importante finisce in mezzo al rumore.

Un buon CLAUDE.md contiene ciò che Claude Code deve sapere ogni volta che lavora in quel progetto e che non può ricavare con sicurezza dai file. Comandi di verifica, convenzioni particolari, confini e comportamenti che hanno già causato un errore. Poco altro.

Anthropic descrive CLAUDE.md come un file di istruzioni persistenti caricato nel contesto delle sessioni. Non è però un archivio universale e non applica da solo un divieto tecnico. La documentazione sulla memoria di Claude Code distingue infatti le istruzioni scritte dall'utente dai controlli che bloccano davvero un'azione.

La seconda correzione merita una regola

Non registrare ogni preferenza appena compare. Aspetta un segnale osservabile: la stessa correzione è servita in due incarichi, una revisione ha trovato un errore che il progetto poteva prevenire oppure una persona nuova avrebbe bisogno della stessa informazione per non partire male.

Il test è semplice:

1. l'istruzione vale in più sessioni;

2. riguarda questo progetto o il tuo modo di lavorare;

3. puoi capire se è stata rispettata;

4. non è già evidente leggendo il repository;

5. resta vera abbastanza a lungo da meritare spazio nel contesto.

Se manca il primo punto, tieni la nota nell'incarico corrente. Se manca il terzo, riscrivila. «Fai attenzione» non dice quale comportamento osservare. Se manca il quinto, collega una fonte aggiornata invece di copiare un fatto destinato a scadere.

Che cosa fa davvero CLAUDE.md

Ogni nuova sessione parte con una finestra di contesto nuova. Claude Code cerca i file di istruzioni previsti per l'ambiente e li aggiunge al contesto. La documentazione ufficiale distingue più livelli: istruzioni personali, di progetto, locali e legate a sottocartelle. Anthropic spiega anche l'ordine di caricamento.

Questo consente di separare una preferenza valida ovunque da una regola del team. Per esempio, «usa sempre italiano nei documenti pubblici» può appartenere al progetto; un URL locale di prova appartiene invece a un file personale escluso dal controllo di versione. Una convenzione che vale solo sotto fatture/ può stare più vicino a quella cartella.

La distinzione evita due errori. Il primo è consegnare a tutto il team una configurazione personale. Il secondo è caricare in ogni incarico regole che riguardano un solo modulo.

Scegli cosa merita di restare

Cinque categorie reggono bene in un file di progetto:

Scrivi il minimo che cambia una decisione. Una descrizione file per file invecchia appena il progetto si muove. Un principio come «usa il client in src/http/ e non chiamare fetch dai componenti» resta verificabile anche quando aumentano i componenti.

Che cosa tenere fuori

Una procedura di dodici passaggi non deve occupare il contesto di ogni sessione se serve una volta al mese. Trasformala in una Skill o in un runbook richiamabile. La SOP di un workflow AI può definire input, passaggi, controlli e stop; CLAUDE.md deve al massimo dire quando usarla.

Tieni fuori anche:

• documentazione che Claude può trovare leggendo il codice;

• elenchi completi di file e cartelle;

• incidenti già chiusi senza una lezione riutilizzabile;

• dati che cambiano spesso, come versioni correnti o ambienti temporanei;

• segreti, token e dati personali;

• tutorial lunghi su strumenti standard.

La lunghezza non è il solo problema. Conta la densità. Una pagina con trenta frasi vaghe pesa più di due pagine con comandi, percorsi e stop precisi.

Dividi per permanenza e perimetro

Prima di aggiungere una riga, incrociane frequenza e forza:

Questa tabella impedisce di usare il testo come serratura. Scrivere «non leggere .env» indica il comportamento atteso, ma un controllo applicato dal client è il livello adatto quando l'accesso deve essere negato. La documentazione Anthropic chiarisce che CLAUDE.md è contesto, mentre le regole di permesso vengono applicate dal sistema.

Scrivi istruzioni che si possono verificare

«Mantieni alta la qualità» non produce un controllo. «Esegui npm run lint e il test del modulo modificato prima di consegnare» sì. La prima frase richiede un'interpretazione; la seconda nomina un'azione e un'evidenza.

Trasforma ogni regola con tre campi:

Quando: dopo una modifica ai file TypeScript.
Fai: esegui il lint e i test del modulo toccato.
Prova: riporta comando, esito e file rimasti modificati.

Per un divieto aggiungi l'alternativa:

Non modificare: public/generated/**.
Motivo: i file sono prodotti dal comando di build.
Alternativa: modifica la sorgente sotto src/content/** e rigenera.

Il motivo serve quando distingue due percorsi plausibili. Non deve diventare un saggio. Una riga basta.

Costruisci una prima versione minima

Una base utile può stare in poche sezioni:

# Progetto

## Comandi
- Test mirato: `npm test -- <file>`
- Controllo tipi: `npm run typecheck`

## Confini
- Non modificare `public/generated/**`; cambia le sorgenti e rigenera.
- Non creare o aggiornare `.env`.

## Convenzioni
- I nuovi file Markdown usano nomi kebab-case.
- Conserva le API pubbliche salvo richiesta esplicita.

## Consegna
- Riporta file modificati, prove eseguite e limiti rimasti.

Non copiare questo modello alla cieca. Sostituisci ogni riga con un fatto del tuo progetto. Se non sai quale comando prova una modifica, il problema non si risolve aggiungendo più istruzioni: devi prima definire la prova.

Provala su tre incarichi

Apri tre sessioni con compiti diversi: una correzione piccola, una modifica che attraversa più file e una richiesta soltanto esplorativa. Usa /context per controllare che il file sia stato caricato, come suggeriscono le best practice di Claude Code.

Per ogni prova registra:

• quale riga avrebbe dovuto cambiare il comportamento;

• che cosa Claude ha fatto;

• quale evidenza ha lasciato;

• se l'istruzione era ambigua, invisibile o semplicemente inutile.

Taglia ciò che non incide. Riscrivi le frasi interpretate in due modi. Se una regola continua a essere ignorata perché compete con altre dieci, cerca il conflitto prima di aggiungere enfasi.

Il file migliora quando diventa più corto dopo una prova, non quando cresce per inerzia.

Manutenzione e conflitti

Tratta CLAUDE.md come un pezzo del progetto. Ogni nuova regola deve avere una causa; ogni regola vecchia deve poter essere rimossa. Controlla soprattutto duplicati e contraddizioni tra livello personale, progetto e sottocartelle.

Un controllo trimestrale può rispondere a quattro domande: la regola è ancora vera, viene applicata, appartiene ancora a questo scope, esiste ora un controllo più affidabile? Se una convenzione è diventata visibile nel formatter o nei test, puoi ridurre la spiegazione. Se una procedura è cresciuta, spostala in una Skill.

Applica lo stesso principio del controllo delle modifiche nei workflow AI: modifica una regola per volta, osserva il comportamento e conserva il motivo della decisione.

Quando serve un controllo tecnico

CLAUDE.md non è la sede giusta per garantire che un comando distruttivo non parta o che una cartella sensibile non venga letta. Per questi casi usa permessi, sandbox, hook e policy dell'organizzazione. Il testo può spiegare il confine, ma il blocco deve vivere nel livello che lo applica.

Lo stesso vale per le autorizzazioni esterne. Una frase nel repository non autorizza un invio, una pubblicazione o una modifica a un account. Il progetto deve distinguere ciò che Claude può tecnicamente fare da ciò che una persona ha deciso di permettere in quel caso.

Porta una regola fino alla prova

Prendi la correzione che ripeti più spesso. Scrivila con quando, azione e prova. Poi esegui un incarico piccolo e controlla se ha cambiato davvero il risultato. Se funziona, condividila. Se richiede un blocco, spostala nel livello tecnico corretto.

Nel programma su Claude Cowork e Code di MAIKER HUB puoi costruire istruzioni, procedure e controlli sul lavoro che fai davvero. Il risultato utile non è un CLAUDE.md lungo. È una sessione che parte con i confini giusti senza farti ripetere la stessa correzione.