CLAUDE.md: Come Scrivere Istruzioni che Cambiano il Comportamento di Claude

Aggiornato: aprile 2026, Gaetano Castaldo, consulente AI e digital transformation, certificato Salesforce Architect.

Se stai spiegando le stesse cose a Claude ogni volta che apri una nuova sessione, stai sprecando tempo. La soluzione si chiama CLAUDE.md, e la maggior parte di chi usa Claude Code non lo sfrutta al 10% di quello che può fare.

CLAUDE.md è un file di testo che Claude legge automaticamente ogni volta che apri una nuova sessione. Contiene le istruzioni permanenti del tuo progetto: come funziona, cosa non toccare mai, come si lavora, qual è il tono di voce, quali strumenti usare. Tutto ciò che non vuoi rispiegare ogni volta.

Non è documentazione. Non è un manuale. È la memoria del progetto, scritta in un formato che l'AI capisce nativamente.

In questa guida ti mostro come strutturarla, cosa metterci, cosa evitare, con esempi reali dal mio workflow quotidiano.

Il Problema che CLAUDE.md Risolve

Ogni sessione Claude Code parte da zero. Il modello non ricorda le conversazioni precedenti. Non sa come preferisci lavorare, non sa quali file non si toccano mai, non sa come funziona il tuo processo di approvazione o quali sono le regole del tuo brand.

La risposta istintiva è riscrivere queste istruzioni ogni volta. O peggio: non scriverle, e trovarsi con Claude che fa scelte sbagliate perché non conosce i vincoli del progetto.

Per me la svolta è arrivata quando ho capito davvero il problema del context rot, il degrado progressivo delle risposte che si manifesta quando una sessione va avanti a lungo. Claude inizia a essere meno preciso, perde il filo, ripete cose già dette. La soluzione obbligata era aprire una nuova sessione e ricominciare. Ma ricominciare significava rispiegare tutto: come funziona il progetto, le convenzioni, i vincoli, le preferenze. Ogni volta da capo.

Quando ho scoperto i comandi per creare, configurare e revisionare il CLAUDE.md: ho visto che Claude leggeva quelle istruzioni automaticamente all'inizio di ogni nuova sessione: è stata una piccola rivoluzione. Smettevo di perdere tempo a ricostruire il contesto. Aprivo una nuova sessione, e Claude sapeva già dove si trovava.

Il CLAUDE.md risolve esattamente questo. E il valore non è solo personale: il file si condivide con il team. Ogni collaboratore che entra nel progetto parte dalla stessa base di contesto, senza sessioni di allineamento, senza spiegazioni ripetute.

Come Funziona il CLAUDE.md: Tre Livelli di Caricamento

Claude gestisce i file CLAUDE.md in ordine di specificità, dal generale al particolare:

Le tue preferenze personali vivono in un file globale sulla tua macchina. Lingua di risposta, stile di comunicazione, strumenti che hai installato, cose che non vuoi mai vedere nelle risposte. Queste istruzioni valgono su tutti i tuoi progetti e sono visibili solo a te.

Le regole del progetto vivono nella cartella principale del progetto stesso. Stack tecnologico, file critici, workflow, convenzioni di naming, tono di voce del brand. Queste si condividono con il team: chiunque lavori su quel progetto ottiene lo stesso contesto.

Le regole di sezione vivono in sottocartelle specifiche. Convenzioni di codice per una certa area, formato per la documentazione, istruzioni particolari per una parte del progetto. Si caricano solo quando sei in quella sezione.

Il risultato pratico: puoi avere istruzioni personali e istruzioni di progetto, senza conflitti e senza ripetizioni.

Cosa Mettere in un CLAUDE.md Efficace

Non esiste un template universale: ogni progetto è diverso. Ma ci sono sezioni che fanno quasi sempre la differenza.

Presentazione del Progetto

Due-tre righe che inquadrano il contesto. Claude sa già in quale cartella si trova, ma non sa cosa stai costruendo, per chi, con quale approccio. Questa sezione evita suggerimenti incompatibili con la tua situazione.

Per esempio: cos'è il progetto, che tecnologia usa, come viene distribuito, qual è l'obiettivo principale. Bastano tre righe, scritte come se le stessi spiegando a un nuovo collaboratore nel primo giorno di lavoro.

I File (o le Aree) Intoccabili

La sezione più importante dopo la presentazione. Ogni progetto ha elementi che non si modificano direttamente: file generati automaticamente, configurazioni critiche, dati sensibili. Elencarli con il motivo evita errori costosi.

La forma migliore è una tabella: elemento, regola, perché. Il "perché" è fondamentale: una regola senza motivazione viene ignorata o aggirata, anche involontariamente.

Le Regole Operative

Come si lavora su quel progetto: convenzioni di naming, formato dei commit, processo di approvazione, strumenti preferiti. Non serve essere esaustivi. Serve documentare le cose non ovvie, quelle che un nuovo collaboratore (umano o AI) non potrebbe indovinare da solo.

I Comandi Ricorrenti

Le operazioni che fai ogni giorno, con il comando esatto. Build, deploy, anteprima locale, test. Non le spiegazioni, i comandi: pronti da copiare e usare senza cercare nella documentazione.

Cosa Non Fare

Questa sezione vale quanto le altre messe insieme. Claude tende a essere ottimista: completa il task nel modo più efficiente senza chiedersi se ci sono vincoli impliciti. Renderli espliciti cambia radicalmente il comportamento.

Esempi pratici: non modificare certi file, non aggiungere commenti al codice che non viene cambiato, non fare ottimizzazioni non richieste, non usare certi strumenti indisponibili nell'ambiente. Ogni voce di questa lista nasce da un problema reale.

C'è però una trappola in cui sono caduto subito: scrivere un CLAUDE.md troppo denso.

Un file sovraccarico non risolve il context rot, lo anticipa. Più istruzioni carichi all'inizio della sessione, prima lo spazio di lavoro si esaurisce. E riaprire una nuova sessione ogni venti minuti, oltre a interrompere il flusso, è semplicemente noioso.

La soluzione che ho trovato: invece di mettere tutto in un unico file, ho iniziato a distribuire la memoria su file separati per area. Requisiti tecnici in uno, infrastruttura in un altro, requisiti funzionali in un terzo, brand identity in un quarto. Il CLAUDE.md principale diventa un indice di tre o quattro righe, e ogni file si carica solo quando è rilevante. Sessioni più lunghe, meno interruzioni, meno ripetizioni.

Riferimenti ad Altri Documenti

Se hai già documentazione su certi aspetti del progetto, non copiarla nel CLAUDE.md. Metti un riferimento al file. Il contenuto viene letto quando serve, il file principale rimane leggero, e le informazioni sono sempre aggiornate all'ultima versione.

File Personale e File di Progetto: cosa va dove

Capire questa distinzione ti fa risparmiare molto tempo.

Il file personale contiene le tue preferenze come utente: in che lingua vuoi le risposte, che tono preferisci, quali strumenti hai disponibile sul tuo computer, abitudini di lavoro che non cambiano da un progetto all'altro. Vive sulla tua macchina, non si condivide.

Il file di progetto contiene le regole del progetto specifico: come funziona, cosa non toccare, come si lavora, il brand. Si condivide con il team e con Claude in ogni sessione su quel progetto.

Regola semplice: se vale solo per te, va nel file personale. Se vale per chiunque lavori su quel progetto, va nel file di progetto.

Il progetto su cui ho spinto questa struttura più in profondità è stato il sito di Castaldo Solutions, il più complesso che avevo sotto mano. Un caso ideale per testare i limiti di un file unico monolitico.

Dopo settimane di iterazioni, ho capito come modularizzarlo: identità di brand separata dalla configurazione tecnica, infrastruttura separata dal funzionamento dell'applicativo, convenzioni visive separate dalla struttura dei contenuti. Il file principale è rimasto a tre righe. Ognuno dei file satellite si carica solo quando serve.

Quella struttura mi ha cambiato il modo di lavorare, e la porto su ogni nuovo progetto che avvio con i clienti.

Stima dal campo: un team che parte con CLAUDE.md modulare da giorno uno dimezza i tempi di onboarding (nessuna sessione di allineamento verbale) e riduce del 60-70% le sessioni interrotte per context rot rispetto a chi lavora senza contesto strutturato.

Un team che parte con questa architettura da giorno uno non perde mai il contesto, non duplica le istruzioni, non degrada le sessioni prematuramente.

Come Mantenerlo Vivo: la Skill claude-md-management

Il rischio principale con il CLAUDE.md è che invecchi. Il progetto evolve, le convenzioni cambiano, si aggiungono strumenti nuovi, ma le istruzioni rimangono ferme alla versione iniziale.

La soluzione è trattarlo come il progetto stesso: aggiornarlo in modo incrementale, preferibilmente alla fine di ogni sessione di lavoro in cui hai imparato qualcosa di nuovo.

La skill claude-md-management automatizza questo processo. Ha due funzioni:

• /revise-claude-md: analizza la sessione appena conclusa e aggiorna il file con i nuovi apprendimenti. Se hai scoperto che qualcosa non andava documentato, la skill lo aggiunge.
• claude-md-improver: audita il file esistente e segnala sezioni incomplete, istruzioni contraddittorie, informazioni obsolete.

Il workflow che uso: a fine sessione lancio /revise-claude-md e salvo il file aggiornato insieme alle altre modifiche. In sei mesi, il CLAUDE.md di un progetto diventa una documentazione operativa di qualità superiore a qualsiasi wiki scritto a mano.

Un Esempio Reale

Per dare concretezza, ecco la struttura del CLAUDE.md del sito che stai leggendo ora:

# CLAUDE.md - Castaldo Solutions

## Brand Identity
@brand/castaldo-solutions-brand-identity.md

## Architettura Tecnica
@.claude/tech.md

## Infrastruttura VPS
@vps/README.md

Tre righe, tre riferimenti. Tutto il dettaglio (stack, file critici, workflow, palette colori, tono di voce, accessi server) vive nei file referenziati, aggiornati indipendentemente, leggibili anche senza aprire il file principale.

Il risultato: Claude, all'inizio di ogni sessione, sa già tutto ciò che serve, senza che io abbia mai scritto un documento monolitico da 500 righe difficile da mantenere.

Gli Errori più Comuni

Scrivere troppo. Un CLAUDE.md sovraccarico peggiora le sessioni invece di migliorarle. Se una sezione non ha mai cambiato il comportamento di Claude in modo misurabile, eliminala.

Scriverlo per l'AI, non per le persone. Il CLAUDE.md migliore è quello che un nuovo collaboratore leggerebbe volentieri come documentazione operativa. Se stai scrivendo "Sei un esperto di..." stai usando il pattern sbagliato: quello è un prompt, non un file di configurazione.

Tenerlo solo sulla propria macchina. La parte più potente è la condivisione: ogni sessione su quel progetto, tua, di un collega, di un agente automatizzato, parte dallo stesso contesto.

Non spiegare i motivi. Le regole senza motivazione vengono ignorate. "Non modificare questo file" è debole. "Non modificare questo file perché viene rigenerato automaticamente a ogni build e le modifiche manuali vengono sovrascritte" è inattaccabile.

Non aggiornarlo. Un CLAUDE.md vecchio di sei mesi su un progetto che è cambiato è peggio di nessun CLAUDE.md: genera aspettative sbagliate.

CLAUDE.md, README e Prompt: le Differenze

Tre strumenti che spesso si sovrappongono nella mente di chi inizia.

Un CLAUDE.md non sostituisce il README: lo completa. Il README spiega cosa è il progetto. Il CLAUDE.md dice come ci si lavora ogni giorno.

Domande Frequenti

Quanto deve essere lungo? Non c'è una lunghezza ideale, ma esiste una soglia oltre la quale il ritorno diminuisce. Quando il file principale supera le 200-300 righe, è il momento di spostare parti del contenuto in file separati per area.

Sostituisce la documentazione del progetto? No, sono strumenti diversi. La documentazione spiega il progetto a chi non lo conosce. Il CLAUDE.md contiene le istruzioni operative per chi ci lavora ogni giorno, incluso Claude.

Posso avere istruzioni diverse per aree diverse del progetto? Si. Un file nella cartella principale per le regole generali, file specifici nelle sottocartelle per aree particolari. Claude li combina automaticamente senza conflitti.

Come capisco se funziona? Apri una nuova sessione senza dare nessuna istruzione aggiuntiva e lancia un task che richiede rispettare le convenzioni del progetto. Se l'output è corretto al primo tentativo, funziona. Se devi correggere qualcosa, quella correzione va nel CLAUDE.md.

Inizia con Tre Righe

Non serve aspettare di avere tutto strutturato. Apri il tuo progetto, crea un file CLAUDE.md, scrivi tre cose: cos'è il progetto, cosa non si tocca mai, come si distribuisce.

Da li, ogni sessione ti insegna cosa aggiungere. In un mese hai un file (con i satellite per area) che vale piu di qualsiasi documentazione scritta a freddo.

Stai gia usando Claude Code ma le sessioni degradano troppo in fretta? Il tuo team perde tempo a rispiegare il contesto ogni volta che apre una nuova sessione?

E esattamente il problema che risolviamo durante un pre-assessment gratuito: analizziamo come stai usando Claude Code oggi, costruiamo insieme la struttura modulare per il tuo progetto, e ti mostriamo quanto tempo recuperi gia nella prima settimana.