CLAUDE.md: configurare le istruzioni di Claude Code con un esempio

Claude Code sa leggere il tuo codice, ma alcune regole di lavoro lì non si vedono: perché l'ambiente di test non deve mandare email ai clienti, quali cartelle vengono generate, quale controllo conferma che una correzione funziona. Se ti ritrovi a spiegarle a ogni nuovo compito, scrivile in CLAUDE.md.

CLAUDE.md è un file Markdown con istruzioni persistenti per Claude Code. Ci vanno i comandi del progetto, i vincoli importanti e i criteri di verifica. Per cominciare basta un file nella radice del repository. La documentazione di Anthropic spiega dove possono stare questi file e come vengono caricati.

• documentazione Anthropic

L'esempio qui sotto è un piccolo progetto web. Sostituisci percorsi e comandi con i tuoi: è un modello per imparare, e nessuno l'ha verificato sulla tua applicazione.

Quali regole scrivere

Immagina di dover aggiungere il campo «Azienda» a un modulo di richiesta. Sapere che il progetto usa TypeScript all'agente serve a poco. Deve trovare il modulo, capire dove finiscono i dati e provare l'invio senza che la richiesta arrivi al vero reparto commerciale.

Una buona regola aiuta a prendere una decisione concreta:

La colonna di destra non va bene per qualsiasi repository. È utile perché corrisponde a questo progetto. Se da te TextField non esiste, riscrivi la regola, altrimenti sarà l'istruzione stessa a provocare errori.

Ripensa alle osservazioni che hai fatto di recente all'agente. Quali serviranno ancora? Un requisito su un singolo pulsante resta nel compito. Una convenzione che vale per tutti i moduli va nelle regole del progetto.

Dove creare CLAUDE.md

Le regole condivise dal team vanno in `CLAUDE.md`, nella radice del progetto. Le preferenze personali, valide per tutti i progetti, possono stare in `~/.claude/CLAUDE.md`. I file nelle sottocartelle vengono caricati quando Claude legge file in quelle cartelle.

• Guida al contesto

Per partire basta una struttura semplice:

project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/

Se il file esiste già, per prima cosa leggilo. Due serie di regole simili si mantengono male: il comando di test viene aggiornato in una e dimenticato nell'altra.

Controlla anche il nome esatto del file. Un editor che nasconde le estensioni può lasciarti un `CLAUDE.md.txt` senza che tu te ne accorga.

Ottenere una prima bozza

Esegui `/init` in una sessione aperta di Claude Code. Il comando prepara un primo CLAUDE.md a partire dal progetto. Rivedi il risultato: i comandi devono esistere, i percorsi essere aggiornati e i vincoli corrispondere al tuo modo di lavorare. Vedi le raccomandazioni di Anthropic.

• raccomandazioni Anthropic

Per vedere una proposta prima di toccare qualsiasi file, chiedi:

Esamina README, script di package.json e struttura delle cartelle. Proponi CLAUDE.md con comandi di avvio e verifica, limiti importanti e particolarità non deducibili con certezza dal codice. Trasforma le incognite in domande. Per ora non creare o modificare file.

Avrai un testo da confrontare con il repository. Non accettarlo solo perché è ben scritto. `npm test` è inutile se nel progetto quello script non esiste.

Esempio per un progetto web

Questo modello l'abbiamo scritto per la guida. Descrive un sito di servizi ipotetico con npm, TypeScript, dizionari di traduzione e test del modulo configurati a parte. I nomi di comandi e cartelle servono solo a mostrare la struttura: sostituiscili con quelli reali.

# Progetto

Sito di servizi con modulo di contatto, in russo e inglese.
Percorso principale: scegliere un servizio e inviare una richiesta.

## Dove trovare il codice
- src/components/forms/ — campi e moduli.
- src/server/leads/ — elaborazione delle richieste.
- src/i18n/ — dizionari dell'interfaccia.
- tests/leads/ — test di elaborazione.

## Comandi
- npm run dev — avvio locale.
- npm run typecheck — verifica dei tipi.
- npm run test:leads — test delle richieste.
- npm run build — compilazione.

## Regole di modifica
- Riusa componenti dei moduli e gestori degli errori esistenti.
- Conserva i testi nei dizionari di entrambe le lingue.
- Non aggiungere dipendenze se bastano gli strumenti del progetto.
- Conserva le modifiche non concluse di altre persone.

## Verifica
- Per le richieste controlla campi obbligatori, email non valida
  e invio riuscito a un destinatario di test.
- Esegui npm run typecheck per modifiche TypeScript.
- Esegui npm run test:leads per modifiche all'elaborazione.
- Controlla nel browser la schermata coinvolta da modifiche all'interfaccia.
- Se un controllo non è disponibile, indica motivo e incertezza residua.

## Ambiente
- Usa solo il destinatario di test per verificare gli invii.
- I nomi delle variabili necessarie sono in .env.example.
- Non inserire segreti in codice, rapporti o documentazione.

## Resoconto
Descrivi brevemente modifiche, verifiche e problemi rimasti.
Distingui risultati dei test e ipotesi sul funzionamento.

Controlla prima i comandi. Poi assicurati che le verifiche richieste si possano fare davvero. Un'istruzione non fa comparire un destinatario di test che non c'è: prepara l'ambiente di test o descrivi un'alternativa disponibile.

Non ti servono tutte le sezioni. Per una libreria contano di più l'API pubblica e la compatibilità. Per un sito di articoli, la struttura dei contenuti, i metadati e i link interni.

Verificare se le istruzioni aiutano

Qui le domande sono due: il file è stato caricato? E il comportamento dell'agente è cambiato?

Esegui `/context` e cerca il tuo file sotto Memory files. Poi assegna un piccolo compito dall'esito chiaro. Anthropic raccomanda espressamente questo modo di verificare il caricamento.

• Configurazione

Per il sito dell'esempio:

Aggiungi il campo facoltativo «Azienda». Prima trova componente esistente e gestore dell'invio. Dopo verifica l'invio con e senza azienda. Elenca soltanto i controlli realmente eseguiti.

Poi guarda tre cose:

1. Sono stati usati componente e dizionari previsti?
2. L'invio senza campo facoltativo funziona ancora?
3. Gli esiti dichiarati corrispondono all'output degli strumenti?

Se una delle tre non torna, cerca il motivo. La regola può essere ambigua. Nel codice può esserci un secondo gestore simile. I test possono non coprire lo scenario. Aggiungi un divieto solo dopo aver capito che cosa è andato storto.

Per annotare le osservazioni basta una piccola tabella: compito, azione attesa, risultato ottenuto, regola rivista. È un metodo che proponiamo noi; qui non riferiamo di un esperimento. Una prova riuscita non dimostra che la regola verrà sempre seguita.

Se Claude ignora CLAUDE.md

Per prima cosa conferma che il file giusto sia stato caricato. Poi cerca istruzioni sullo stesso argomento in altri file del progetto. Secondo la documentazione, tutti i CLAUDE.md individuati vengono combinati nel contesto, quindi un file annidato non annulla automaticamente le regole poste più in alto.

• Ordine di caricamento

Guarda poi la formulazione. «Verifica con cura» lascia all'agente troppe scelte. «Esegui questo comando dopo aver modificato il gestore delle richieste» indica un'azione di cui si vede il risultato.

Può anche darsi che l'istruzione sia semplicemente vecchia. Quando i test vengono spostati o la struttura delle cartelle cambia, rivedi le regole collegate. Un agente se ne fa poco di un documento che descrive un progetto che non esiste più.

Infine togli ripetizioni e desideri generici. Anthropic suggerisce istruzioni concise, specifiche del progetto, da rivedere man mano. Nessuna lunghezza del file garantisce che vengano rispettate.

• Consigli sui contenuti

Quando usare rules e Skills

Quando il progetto cresce, dividi le istruzioni per scopo. `.claude/rules/` ospita regole tematiche, comprese quelle legate a percorsi specifici. Gli skill servono per procedure ripetibili che occorrono solo in certe situazioni.

• Regole
• Skills

Così le istruzioni si mantengono meglio: se cambia la procedura di release, non devi riscrivere ogni scenario. Dividere in file, però, non rende le regole più precise. Le contraddizioni vanno risolte nel merito.

CLAUDE.md non sostituisce i permessi

«Non scrivere a clienti reali» descrive bene un modo di lavorare. I limiti tecnici di accesso si configurano a parte. Claude Code ha `/permissions` e le regole allow, ask e deny, e niente di ciò che scrivi in CLAUDE.md le modifica.

• Gestione dei permessi

Nell'esempio del modulo, configura l'ambiente di test in modo che gli invii vadano fisicamente a un destinatario di test. A quel punto il destinatario giusto non dipende più da come l'agente interpreta un paragrafo.