CLAUDE.md: istruzioni e memoria per lavorare in team

Il vantaggio è dover ripetere meno spesso le stesse istruzioni iniziali. Facciamo un’ipotesi sul tempo dedicato a questa attività: quattro sviluppatori che ripetono tre minuti di configurazione per cinque sessioni ciascuno passano 60 minuti a settimana a rispiegare il contesto. Un file di istruzioni condiviso permette di mantenere queste indicazioni in un unico posto. Confronta il tempo risparmiato sulle ripetizioni con quello necessario ad aggiornare il file: il risparmio non è garantito.

Che cos’è CLAUDE.md?

CLAUDE.md è un file Markdown con le istruzioni che Claude Code legge per il progetto, il tuo modo di lavorare o l’organizzazione. È il riferimento stabile del team. La memoria automatica, invece, è il taccuino che Claude aggiorna mentre lavora. Tu curi le istruzioni; Claude scrive gli appunti. Entrambi forniscono il contesto per le sue decisioni. Guida di Anthropic alla memoria

La distinzione utile riguarda ciò che deve restare valido da una sessione all’altra. Un comando di test obbligatorio va nel file di istruzioni. Il tuo commento su una spiegazione troppo dettagliata può diventare una preferenza appresa. Il compito del momento appartiene alla conversazione.

Questa suddivisione segue la guida ufficiale alla directory. Per iniziare non serve una cartella .claude piena di file. Parti dalle istruzioni di base e aggiungi un altro file solo quando ha una funzione precisa.

Dove mettere CLAUDE.md: progetto, utente e organizzazione

Per un piccolo team, basta versionare un file di progetto nella directory principale del repository. Le preferenze personali vanno nel file utente, così i colleghi non le ereditano per errore.

Sono gli ambiti e i percorsi documentati. I file gestiti dall’organizzazione non si possono escludere tramite le impostazioni individuali, ma il loro contenuto testuale resta una guida.

All’avvio, Claude carica i file di istruzioni dalla directory di lavoro e dalle directory superiori. Le istruzioni nelle sottodirectory vengono caricate quando lavora sui file che contengono. I contenuti si sommano: aggiungere un file più specifico non elimina eventuali istruzioni in conflitto presenti altrove. Mantieni coerenti le indicazioni del file utente e quelle del progetto. Come vengono caricate le istruzioni

Un esempio di CLAUDE.md per un piccolo team di prodotto

Metti per iscritto le decisioni che evitano errori ricorrenti. L’esempio seguente presuppone un prodotto TypeScript che usa pnpm, con gli script lint, typecheck e test già definiti. Prima di aggiungere il file al controllo di versione, sostituisci comandi e percorsi con quelli che hai verificato nel tuo repository.

Ogni sezione spiega in una riga a cosa serve. Sono convenzioni proposte per il team, non impostazioni predefinite di Anthropic.

# Product Team Instructions

## Product Intent
Why: Keep implementation tied to the customer problem.
- Read the task's acceptance criteria before changing code.
- Ask when missing product behavior would change the solution.

## Working Commands
Why: Make verification repeatable across teammates and sessions.
- Use pnpm for this repository; keep pnpm-lock.yaml consistent.
- Run pnpm lint and pnpm typecheck for application changes.
- Run pnpm test for behavior changes; report any checks not run.

## Change Boundaries
Why: Keep reviews small and dependencies deliberate.
- Follow nearby patterns before adding a new abstraction.
- Ask before adding a runtime dependency or changing public APIs.
- Keep unrelated cleanup out of the change.

## Data and Migrations
Why: Make data changes reviewable and reversible where possible.
- Add schema changes through the existing migration workflow.
- Describe compatibility and rollback concerns in the handoff.
- Use synthetic data in examples and tests.

## Quality
Why: Catch user-visible regressions before review.
- Add a focused regression test when fixing a behavior bug.
- Check loading, empty and error states when changing UI flows.
- State remaining uncertainty instead of calling unchecked work done.

## Project References
Why: Point to maintained decisions without copying the whole wiki.
- Read docs/product-decisions.md when product behavior is unclear.
- Read docs/release-checklist.md before preparing a release.

I riferimenti dell’esempio sono semplici istruzioni per consultare i documenti quando servono. Crea quei documenti oppure sostituisci i percorsi. La scelta di non usare import automatici è intenzionale.

Salva il file, avvia una sessione dal repository ed esegui /context per controllare l’elenco delle memorie caricate all’avvio. Usa /memory per aprire e modificare il file di istruzioni. Poi affida a Claude un piccolo compito reale e verifica se i comandi e i limiti indicati sono utili. Come esaminare la memoria

Tieni le regole per tipo di file fuori dalle istruzioni generali

Sposta una regola in .claude/rules/ quando la maggior parte dei compiti non ne ha bisogno. Una modifica al frontend, per esempio, non dovrebbe portarsi dietro tutte le convenzioni per gli handler delle API.

Crea .claude/rules/api.md con un’intestazione paths. Un glob è un pattern per i nomi dei file: src/api/**/*.ts seleziona i file TypeScript in quella directory e nelle sue sottodirectory.

---
paths:
  - "src/api/**/*.ts"
---

# API Rules
- Validate external input before passing it to application logic.
- Use the existing error response format.
- Add a focused test when changing an endpoint's behavior.

Il pattern determina quando l’istruzione entra nel contesto. Senza paths, la regola viene sempre caricata all’avvio. Dividere un lungo file di istruzioni in più file di regole non fa risparmiare contesto, a meno di circoscriverne il caricamento. Regole associate a percorsi specifici

Gli import condividono il testo, ma non ne riducono il peso nel contesto

Un import come @docs/team-conventions.md dentro CLAUDE.md carica quel file nel contesto all’avvio. I percorsi relativi vengono risolti a partire dal file che contiene l’import. Scrivi l’import effettivo fuori dai backtick o dai blocchi di codice Markdown, che lo mantengono come testo letterale. Gli import di progetto che puntano fuori dalla directory di lavoro richiedono approvazione. Sintassi degli import

Importa una breve convenzione già mantenuta da un altro team quando serve in ogni sessione. Per una lunga checklist di rilascio, preferisci un semplice riferimento, come nell’esempio iniziale. Un import riorganizza le istruzioni, ma non riduce quanto Claude legge all’avvio.

Usi già AGENTS.md? Mantieni un’unica fonte per le istruzioni

Claude Code può usare direttamente AGENTS.md al posto di CLAUDE.md a partire dalla versione 2.1.277, quando il supporto è disponibile. Il comportamento predefinito ha una condizione importante: nella directory di lavoro e nelle directory superiori non devono esserci CLAUDE.md, .claude/CLAUDE.md o CLAUDE.local.md. I file di istruzioni dell’utente e dell’organizzazione non impediscono questo caricamento alternativo. Caricamento di AGENTS.md

Per questo CLAUDE.local.md può creare confusione: aggiungere appunti personali al progetto può cambiare il file di istruzioni condivise che viene caricato nelle tue sessioni.

Se servono entrambi i file, apri /config e imposta Project instructions su claude-md-and-agents-md. In alternativa, inserisci @AGENTS.md in un CLAUDE.md nella stessa directory: questo import funziona anche quando il supporto diretto ad AGENTS.md non è disponibile. Evita di mantenere due copie delle regole del team. La nostra guida alla configurazione di AGENTS.md approfondisce questa scelta.

Memoria di Claude Code: lascia gli appunti alla memoria automatica

La memoria automatica permette a Claude di conservare preferenze utili, correzioni e informazioni sul progetto tra una conversazione e l’altra. Claude decide cosa vale la pena tenere e, in una sessione, potrebbe non salvare nulla. Nelle sessioni locali è attiva per impostazione predefinita. Memoria automatica

Per impostazione predefinita, i file si trovano in ~/.claude/projects/<project>/memory/. All’interno dello stesso repository, worktree e sottodirectory condividono questa cartella di memoria sulla tua macchina. Un worktree è un altro checkout del repository: iniziare a lavorare su un branch al suo interno non crea quindi un taccuino indipendente. Questi file non vengono condivisi automaticamente con i colleghi, altre macchine o ambienti cloud. Dove viene salvata la memoria

MEMORY.md è l’indice. All’inizio della sessione, Claude ne carica le prime 200 righe o 25KB, a seconda del limite raggiunto per primo. I file dedicati ai singoli argomenti vengono letti quando servono. La soglia riguarda il caricamento iniziale dell’indice, non la quantità totale di memoria che puoi archiviare. Come viene caricata la memoria automatica

Parti da /memory: elenca i percorsi della memoria, apre i file nell’editor, dà accesso alla cartella della memoria automatica e permette di attivarla o disattivarla. Usa /context per verificare quali file CLAUDE.md e di regole sono stati caricati all’avvio. Comandi per gestire la memoria

Specifica dove vuoi salvare un’informazione. «Ricorda che preferisco resoconti finali più brevi» chiede di conservare una preferenza appresa. «Aggiungi a CLAUDE.md il comando di test obbligatorio per il team» chiede di aggiornare le istruzioni mantenute dal team. Una regola che serve a tutti non dovrebbe dipendere da un appunto nella directory home di uno sviluppatore.

Non dare per scontato che un normale subagente riceva questo taccuino. La memoria automatica della conversazione principale non viene caricata nei subagenti ordinari; fanno eccezione i fork che ereditano la conversazione di origine, e i subagenti possono avere una propria memoria configurata. Consulta la nostra guida ai subagenti di Claude Code quando distribuisci il lavoro tra più agenti. Come funziona la memoria nei subagenti

Come disattivare la memoria automatica

Scegli l’impostazione adatta al tuo obiettivo:

• Per il tuo utente: apri /memory e disattiva la memoria automatica. L’interruttore salva autoMemoryEnabled in ~/.claude/settings.json.
• Per un solo progetto: imposta "autoMemoryEnabled": false nelle sue impostazioni. Usa .claude/settings.json per un’impostazione condivisa del progetto oppure .claude/settings.local.json per una modifica valida solo in locale.
• Per un avvio controllato dall’ambiente: imposta CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Sono i controlli di disattivazione e i percorsi delle impostazioni documentati. Disattivare la memoria automatica lascia disponibile il meccanismo separato di istruzioni tramite CLAUDE.md. Se vuoi rimuovere anche i vecchi appunti, esamina ed elimina esplicitamente quei file Markdown.

Una revisione mensile della memoria automatica

Considerala una breve revisione editoriale di ciò che Claude porterà nel lavoro futuro. La cadenza mensile è un’abitudine suggerita per il team, non un requisito del prodotto.

1. Apri /memory ed esplora la cartella della memoria automatica. Leggi MEMORY.md, poi segui i riferimenti agli appunti veri e propri.
2. Elimina il contesto superato. Rimuovi scadenze già passate, piani abbandonati ed eccezioni non più valide. Verifica gli appunti dubbi alla luce dello stato attuale del progetto.
3. Unisci le correzioni ripetute. Mantieni una formulazione corretta invece di più versioni leggermente diverse.
4. Trasforma le decisioni stabili del team in istruzioni condivise. Sposta una convenzione che serve a tutti nel CLAUDE.md versionato o in una regola con ambito specifico, poi elimina l’appunto personale ridondante.
5. Accorcia l’indice. Tieni in MEMORY.md riferimenti brevi e sposta i dettagli nei file tematici. Confronta sia il numero di righe sia la dimensione in byte con la soglia di caricamento iniziale.
6. Prova una nuova sessione. Verifica l’elenco delle istruzioni con /context e controlla che nel prossimo compito reale non ricompaiano indicazioni obsolete.

I file della memoria automatica sono Markdown modificabile e le regole di conservazione delle trascrizioni non ne cancellano automaticamente il contenuto. Qualcuno deve comunque eliminare gli appunti superati. Modifica e conservazione

Cinque situazioni in cui questa configurazione aiuta

Parti dai punti in cui le correzioni ripetute stanno già rallentando le revisioni. Questi sono flussi di lavoro proposti, ordinati per probabile utilità per un piccolo team di prodotto.

Due idee da sviluppare attorno a questo metodo

L’opportunità più promettente è una verifica delle istruzioni del repository. Un piccolo team potrebbe pagare per un’analisi che controlli i comandi, trovi indicazioni in conflitto e proponga un breve file di istruzioni con regole ad ambito specifico. Il risultato minimo utile è una pull request revisionata, accompagnata da una checklist per ripetere la verifica. DataForSEO stima 260 ricerche mensili negli Stati Uniti per “claude project instructions”. La query è ampia e comprende interessi che vanno oltre Claude Code: segnala una possibilità di farsi trovare, non un numero di potenziali acquirenti. Un modello generico è facile da copiare; il valore a pagamento dovrebbe quindi risiedere in una valutazione specifica del repository.

Un report locale sulla manutenzione della memoria potrebbe aiutare i team con molti repository attivi. Una prima versione potrebbe segnalare indici troppo grandi, riferimenti a file tematici mancanti e appunti potenzialmente superati, lasciando allo sviluppatore la revisione delle modifiche. DataForSEO stima 1,300 ricerche mensili negli Stati Uniti per “claude code memory”. Il dato mostra interesse per il problema, non domanda per questo specifico strumento. Il limite è rilevante: l’età di un file non basta a stabilire se una decisione è obsoleta. La valutazione del significato degli appunti deve restare a chi conosce il progetto.

Entrambe le stime provengono da un’analisi keyword-overview in inglese per gli Stati Uniti, recuperata l’11 ottobre 2026 tramite l’integrazione di ricerca DataForSEO del sito. Sono proposte di prodotto, non funzionalità integrate in Claude Code. Per un piccolo repository, parti dal file e dalla revisione mensile prima di acquistare o costruire uno dei due strumenti.

La memoria offre contesto, ma non impone i vincoli

Scrivere «non farlo mai» in CLAUDE.md non rende impossibile un’azione. Lo stesso vale per la memoria automatica e per le indicazioni testuali dell’organizzazione. Claude può interpretare male un’istruzione vaga o incontrare direttive contraddittorie. L’avvertenza di Anthropic

Usa un hook PreToolUse, un controllo eseguito prima dell’azione di un tool, quando devi bloccare quell’azione indipendentemente dalla decisione di Claude. Un promemoria sui file protetti può spiegare l’intento del team; per impedire l’azione serve un controllo implementato. La nostra guida alla configurazione degli hook di Claude Code spiega come impostarlo.

Per contenere il contesto, punta a istruzioni che qualcuno possa davvero mantenere aggiornate. Anthropic consiglia di tenere ogni file CLAUDE.md sotto le 200 righe, ma questa raccomandazione è distinta dalla soglia di caricamento iniziale di MEMORY.md. Non allungare il file di partenza per raggiungere una presunta quota e non spostare tutto negli import pensando di averne ridotto il costo. Come scrivere istruzioni efficaci

Le domande pratiche di un piccolo team

Da fare lunedì: riprendi le correzioni delle ultime sessioni, raccogli le decisioni ricorrenti del team in un unico CLAUDE.md revisionato e provalo su un piccolo compito. Aggiungi al calendario del team la revisione mensile della memoria.

Se ti serve una mano a trasformare queste convenzioni in un processo di sviluppo affidabile, scopri il nostro servizio per sistemi AI in produzione.