CLAUDE.md: configurare le istruzioni di Claude Code con un esempio
Neaptide · 20 settembre 2026 · 8 min di lettura
Crea un CLAUDE.md utile con comandi, verifiche e un modello adattabile. Controlla il caricamento e le istruzioni ignorate.
In questo articolo
Claude Code può esplorare il codice, ma alcune regole non sono visibili: perché i test non devono inviare email ai clienti, quali cartelle sono generate o quale controllo conferma una correzione. Se ripeti queste spiegazioni a ogni incarico, scrivile in CLAUDE.md.
CLAUDE.md è un file Markdown con istruzioni persistenti per Claude Code. Può contenere comandi, vincoli importanti e criteri di verifica. Parti da un file nella radice del repository. La documentazione Anthropic spiega posizioni e caricamento.
L'esempio riguarda un piccolo progetto web. Adatta percorsi e comandi: è un modello didattico, non una configurazione verificata sulla tua applicazione.
Quali regole scrivere
Immagina di aggiungere il campo «Azienda» a un modulo. Sapere che il progetto usa TypeScript non basta: servono posizione del modulo, destinazione dei dati e modalità di prova senza contattare il reparto commerciale.
Una buona regola aiuta una decisione concreta:
| Troppo generico | Applicabile |
|---|---|
| Scrivi codice di qualità | Controlla input vuoto, email non valida e invio riuscito |
| Rispetta il design | Usa TextField e i suoi stati di errore esistenti |
| Non rompere il progetto | Dopo il gestore, esegui i suoi test e verifica i tipi |
| Considera le lingue | Metti etichette ed errori nei dizionari |
| Verifica il risultato | Distingui controlli eseguiti e non disponibili |
La seconda colonna non è universale. Se TextField non esiste, modifica la regola o sarà essa stessa a provocare errori.
Rivedi le ultime osservazioni all'agente. Quali serviranno ancora? Un requisito su un pulsante resta nel compito; una convenzione per tutti i moduli va nelle regole del progetto.
Dove creare CLAUDE.md
Le regole condivise vanno in `CLAUDE.md` nella radice. Le preferenze personali generali possono stare in `~/.claude/CLAUDE.md`. I file nelle sottocartelle vengono caricati quando Claude legge file al loro interno. Guida al contesto.
Struttura iniziale:
project/
├── CLAUDE.md
├── README.md
├── package.json
└── src/Se il file esiste, leggilo prima. Duplicare le regole complica la manutenzione: un comando può essere aggiornato in un punto e dimenticato altrove.
Controlla anche il nome. Un editor che nasconde le estensioni può creare per errore `CLAUDE.md.txt`.
Ottenere una prima bozza
Esegui `/init` in Claude Code. Aiuta a preparare il file dal progetto. Verifica comandi, percorsi e vincoli: il testo generato richiede revisione. Vedi le raccomandazioni Anthropic.
Per una proposta senza modifiche:
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. Una forma curata non ne dimostra l'esattezza: `npm test` è inutile se lo script non esiste.
Esempio per un progetto web
Questo modello didattico originale descrive un sito ipotetico con npm, TypeScript, dizionari e test del modulo configurati separatamente. I nomi illustrano 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 la fattibilità delle verifiche. Un'istruzione non crea un destinatario di test mancante: prepara l'ambiente o descrivi un'alternativa disponibile.
Non servono tutte le sezioni. Per una libreria contano API pubbliche e compatibilità; per un sito editoriale, contenuti, metadati e collegamenti interni.
Verificare se le istruzioni aiutano
Distingui caricamento del file ed effetto sul comportamento.
Esegui `/context` e controlla Memory files. Assegna poi un piccolo compito dall'esito chiaro. Anthropic raccomanda questa verifica del caricamento. Configurazione.
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.
Controlla tre punti:
- Sono stati usati componente e dizionari previsti?
- L'invio senza campo facoltativo funziona ancora?
- Gli esiti dichiarati corrispondono all'output degli strumenti?
Se qualcosa manca, cerca la causa: regola ambigua, altro gestore simile o test incompleti. Aggiungi un divieto dopo aver capito il problema.
Una tabella con compito, azione attesa, risultato e revisione basta per annotare le osservazioni. È un metodo proposto, non un esperimento già svolto. Un successo non garantisce i successivi.
Se Claude ignora CLAUDE.md
Conferma il caricamento e cerca istruzioni sullo stesso argomento altrove. I file individuati si combinano nel contesto; quello annidato non annulla automaticamente tutti i precedenti. Ordine di caricamento.
Rivedi la formulazione. «Verifica con cura» lascia molte scelte; indicare un comando dopo la modifica del gestore definisce un'azione osservabile.
L'istruzione può essere obsoleta. Dopo spostamenti di test o cartelle, aggiorna le regole collegate. È difficile seguire un documento che descrive un progetto non più esistente.
Elimina ripetizioni e desideri generici. Anthropic suggerisce istruzioni concise e specifiche, riviste nel tempo. Non esiste una lunghezza che garantisca il rispetto. Consigli sui contenuti.
Quando usare rules e Skills
Dividi le istruzioni per scopo. `.claude/rules/` ospita regole tematiche, anche legate a percorsi. Gli Skills servono per procedure ripetibili necessarie in certe situazioni. Regole, Skills.
| Contenuto | Posizione |
|---|---|
| Comandi principali e verifica generale | CLAUDE.md |
| Validazione comune ai moduli | Regola tematica |
| Preparazione di una release | Skill |
| Aggiungere oggi il campo Azienda | Compito attuale |
La manutenzione diventa più semplice. Cambiare una procedura di release non impone di riscrivere ogni scenario. Separare i file non risolve da solo le contraddizioni.
CLAUDE.md non sostituisce i permessi
«Non scrivere a clienti reali» è una regola utile, ma i limiti tecnici si impostano altrove. Claude Code offre `/permissions` e regole allow, ask, deny; CLAUDE.md non le modifica. Gestione dei permessi.
Configura l'ambiente affinché gli invii raggiungano il destinatario di test. La destinazione corretta non dipenderà soltanto dall'interpretazione di un paragrafo.