Workbranch › Guide

Come scrivere un file CLAUDE.md per Claude Code

Ogni sessione di Claude Code parte con un contesto vuoto, e così finisci per ripetere sempre gli stessi comandi di build e le stesse regole interne. Un file CLAUDE.md risolve il problema. Questa guida spiega dove va messo, cosa contiene e come verificare che Claude lo stia davvero leggendo.

Aggiornato 30 ottobre 2026

Percorsi e comandi qui sotto sono stati verificati sulla documentazione di Claude Code di Anthropic a ottobre 2026. Se nella tua versione manca qualcosa, esegui claude update.

Dove si trovano i file CLAUDE.md

Puoi avere più file, ognuno con una portata diversa. Claude Code li combina tutti invece di lasciare che uno sostituisca l'altro; quelli più specifici vengono letti per ultimi.

I file nella cartella da cui avvii Claude e in tutte le cartelle superiori vengono caricati all'avvio. Un CLAUDE.md dentro una sottocartella viene caricato più tardi, quando Claude legge o modifica un file in quella sottocartella.

Crea il file con /init

1. Apri un terminale nella cartella principale del progetto e avvia claude.
2. Digita /init. Claude esamina il codice e scrive un CLAUDE.md iniziale con i comandi di build, le istruzioni per i test e le convenzioni che trova. Se esiste già un CLAUDE.md, propone dei miglioramenti invece di sovrascriverlo.
3. Leggi la bozza ed elimina tutto ciò che è ovvio o sbagliato.
4. Aggiungi quello che Claude non può ricavare dal codice: decisioni prese, particolarità dell'ambiente, regole del tipo "non fare mai X".
5. Fai il commit del file, così i colleghi ricevono le stesse istruzioni.

Per modificarlo in seguito, esegui /memory. Elenca le posizioni di CLAUDE.md e CLAUDE.local.md per l'ambito utente e progetto, comprese quelle che non esistono ancora, e apre nel tuo editor il file che scegli. Puoi anche dire semplicemente aggiungi questo a CLAUDE.md.

Cosa scriverci

Un test semplice: se hai dovuto dire qualcosa a Claude due volte, va nel file. Momenti tipici per aggiungere una riga: Claude ripete un errore, una code review trova qualcosa che avrebbe dovuto sapere, oppure scrivi la stessa correzione che avevi scritto nella sessione precedente.

• Comandi: come fare build, test, lint ed eseguire il progetto.
• Struttura: dove si trova il codice importante, per esempio gli handler dell'API sono in src/api/handlers/.
• Convenzioni: nomi, formattazione, regole per branch e commit.
• Lezioni imparate a fatica: le cose che metterebbero in difficoltà un nuovo collega.

Scrivi regole verificabili. Esegui npm test prima di ogni commit funziona meglio di testa le tue modifiche. Raggruppa le righe sotto titoli ed elenchi puntati ed elimina le istruzioni che si contraddicono, perché Claude potrebbe seguire l'una o l'altra. Le procedure in più passaggi o le regole che valgono per una sola parte del codice vanno invece in una skill o in una regola limitata a certi percorsi.

Tienilo breve e ordinato

• Dimensione: punta a meno di 200 righe per file. I file più lunghi occupano più contesto e vengono seguiti in modo meno affidabile.
• Import: scrivi @README o @docs/git-instructions.md per includere un altro file. I percorsi sono relativi al CLAUDE.md e gli import si possono annidare fino a quattro livelli. I file importati occupano comunque contesto, quindi questo aiuta l'ordine, non la dimensione. La prima volta che un progetto importa un file da fuori della cartella, Claude Code ti chiede di approvarlo.
• Cartella delle regole: metti file tematici come testing.md in .claude/rules/. Aggiungi in cima un campo paths (per esempio src/api/**/*.ts) e la regola viene caricata solo quando Claude lavora sui file corrispondenti.
• Revisione: nelle versioni recenti, /doctor prompt-audit chiede a Claude di cercare istruzioni superate o in conflitto e di proporre modifiche, senza cambiare nulla finché non sei tu a dirlo.

CLAUDE.md e memoria automatica

Claude Code tiene anche appunti propri, chiamati memoria automatica (auto memory). CLAUDE.md lo scrivi tu; la memoria automatica la scrive Claude a partire dalle tue correzioni e preferenze. Si trova per ogni repository in ~/.claude/projects/<project>/memory/, con un indice MEMORY.md di cui le prime 200 righe (o 25KB) vengono caricate in ogni sessione. Resta sul tuo computer e non viene condivisa tramite git. Quando dici ricordati di usare sempre pnpm, finisce nella memoria automatica; attivi o disattivi la funzione con l'interruttore in /memory. Usa CLAUDE.md per tutto ciò che deve arrivare a tutto il team.

Da sapere

• Claude Code è incluso nei piani Pro e Max, nello stesso abbonamento delle app di Claude; per i membri Team ed Enterprise c'è un articolo di assistenza separato.
• CLAUDE.md orienta il comportamento ma non lo impone. Per bloccare comandi o file usa le regole di permesso nelle impostazioni.
• Il CLAUDE.md nella radice del progetto viene riletto dal disco dopo /compact, quindi le regole scritte lì sopravvivono alle sessioni lunghe, mentre quelle scritte solo in chat possono andare perse. I file delle sottocartelle e le regole limitate a certi percorsi tornano non appena Claude tocca di nuovo i file corrispondenti.
• I file nelle cartelle aggiunte con --add-dir non vengono caricati, a meno che tu non imposti CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Se non funziona

• Claude ignora un'istruzione. Esegui /context e guarda sotto Memory files (file di memoria). Se il file non compare, Claude non lo vede: controlla il nome del file e di aver avviato Claude nella cartella giusta.
• Le regole vengono seguite solo a volte. Rendile più specifiche, elimina i conflitti con altri CLAUDE.md o file di regole e accorcia il file.
• Un import non viene caricato. In un percorso con spazi serve una barra rovesciata prima di ogni spazio, un percorso tra virgolette non viene importato e un percorso tra backtick resta testo letterale. Gli import da fuori del progetto richiedono la tua approvazione una tantum.
• Il CLAUDE.md di una sottocartella sembra mancare. Viene caricato solo dopo che Claude tocca un file in quella sottocartella.

Tieni decisioni e cose da fare fuori dal file

CLAUDE.md serve per le regole durature, non per i compiti aperti di questa settimana. Di quella parte si occupa il plugin Workbranch per Claude Code: esegui /workbranch:save e Claude archivia i compiti, le decisioni e le domande aperte della sessione in un progetto Workbranch, e quando una sessione parte in una cartella collegata a un progetto Workbranch, il plugin mostra cosa è ancora aperto lì. C'è una prova gratuita di 3 giorni su app.workbranch.ai.

Fonti

• How Claude remembers your project (Claude Code Docs, verificato il 2026-10-30)
• Commands (Claude Code Docs, verificato il 2026-10-30)
• Use Claude Code with your Pro or Max plan (Claude Help Center, verificato il 2026-10-30)

Domande frequenti