Memoria di Claude Code: CLAUDE.md e auto-memory

Claude Code ha due layer di memoria che convivono nella stessa sessione e spesso vengono confusi: CLAUDE.md, file di istruzioni che l’utente scrive a mano per guidare il modello, e l’auto-memory, note che Claude salva in autonomia tra una sessione e l’altra. Capire dove finisce una cosa e inizia l’altra e’ la differenza tra un setup che resta leggibile nel tempo e un groviglio di file che si contraddicono.

Layer 1: CLAUDE.md, le istruzioni scritte a mano

CLAUDE.md e’ un file markdown che la harness include automaticamente nel system prompt all’avvio della sessione. Esistono due livelli: quello globale in ~/.claude/CLAUDE.md che vale per ogni progetto, e quello per-progetto nella radice del repository, che vale solo quando Claude viene lanciato dentro quella cartella. Entrambi vengono caricati, il per-progetto prevale in caso di conflitto.

Il contenuto tipico e’ tutto cio’ che un collega nuovo chiederebbe al primo giorno: convenzioni del codice, percorsi importanti, API interne, comandi di build, anti-pattern noti. Non va confuso con la documentazione: non serve raccontare a Claude cosa fa una funzione se il nome della funzione lo dice gia’. Serve raccontargli cosa NON puo’ dedurre dal codice.

Layer 2: auto-memory, le note che prende Claude

L’auto-memory e’ un sistema separato: file salvati sotto ~/.claude/projects/<path>/memory/, indicizzati da un MEMORY.md. Claude li scrive autonomamente quando ritiene utile ricordare qualcosa oltre la sessione corrente, e li ricarica all’inizio di ogni nuova sessione nello stesso percorso.

Le memorie si dividono per convenzione in quattro tipi: user (identita’ e preferenze dell’utente), feedback (correzioni ricevute su errori ripetuti), project (stato di progetti in corso), reference (link e URL utili gia’ validati). L’indice in MEMORY.md e’ un semplice elenco di link ai file singoli, cosi’ solo l’indice entra nel contesto iniziale e i dettagli vengono letti on demand.

Quando usare CLAUDE.md, quando lasciar fare all’auto-memory

La regola pratica e’ la seguente: CLAUDE.md contiene regole durable che valgono per settimane o mesi, l’auto-memory contiene fatti contingenti che cambiano col procedere dei progetti.

• CLAUDE.md: “preferisci TypeScript a JavaScript”, “non committare senza chiedere conferma”, “usa pnpm, non npm”, “la API di staging e’ su un dominio diverso”
• Auto-memory: “il cliente X preferisce email brevi”, “il progetto Y e’ in pausa sul task Z”, “il feedback di ieri era che i titoli devono essere senza emoji”

Mettere fatti contingenti in CLAUDE.md significa dover aggiornare il file a mano ogni settimana. Mettere regole durable nell’auto-memory significa sperare che Claude si ricordi di salvarle, il che non e’ garantito.

Un CLAUDE.md minimo ma significativo

Un esempio che copre i casi piu’ frequenti senza diventare un papiro. Va messo nella radice del repository per valere solo su quel progetto.

# Progetto: api-billing

## Stack
- Node 20, TypeScript strict, pnpm
- Framework: Fastify 4
- DB: PostgreSQL 15, migrazioni con node-pg-migrate

## Convenzioni
- Niente `any`, se serve usa `unknown` + narrowing
- Endpoint in `src/routes/`, business logic in `src/services/`
- Test accanto al sorgente: `foo.ts` + `foo.test.ts`
- Nomi file in kebab-case, nomi export in camelCase

## Comandi
- `pnpm dev` avvia server con watch
- `pnpm test` esegue vitest
- `pnpm db:migrate` applica le migrazioni

## Cose da NON fare
- Non importare da `src/legacy/`, viene rimosso al prossimo release
- Non modificare `prisma/schema.prisma`, lo rigeneriamo da DB
- Non committare senza chiedere, nemmeno se i test passano

## API interne
- Il servizio auth gira su `auth.internal:8080`, non esposto
- Le chiavi Stripe sono in vault, non in .env locali

Meno di 30 righe, zero ridondanza con il codice, tutto cio’ che un nuovo collega chiederebbe al primo giorno. Se il file cresce oltre le 200 righe comincia a rischiare troncamento o diluizione dell’attenzione del modello: meglio spezzare in sezioni e linkare file di dettaglio, oppure spostare la parte contingente nell’auto-memory.

Anti-pattern comuni

• Documentare cio’ che il codice gia’ dice: se la funzione si chiama sendInvoiceEmail, non serve spiegare che invia email con fatture
• Istruzioni contrastanti tra globale e per-progetto (es. globale dice “usa yarn”, progetto dice “usa pnpm”): il per-progetto vince ma il conflitto resta in contesto e confonde
• File troppo lunghi: oltre 200 righe aumenta il rischio che porzioni finiscano tagliate o ignorate. Meglio spezzare
• Incollare interi README: il README e’ gia’ nel repository, basta puntarci. Duplicarlo in CLAUDE.md significa mantenere due copie
• Regole troppo vaghe: “scrivi codice pulito” non aiuta nessuno. “Preferisci early return a if annidati” si’

Manutenzione: revisione periodica

Entrambi i layer vanno rivisti. CLAUDE.md invecchia quando lo stack cambia o convenzioni evolvono: una rilettura ogni due mesi di solito basta per togliere regole obsolete. L’auto-memory invecchia molto piu’ in fretta, perche’ conserva fatti legati a progetti in corso: vale la pena aprire MEMORY.md ogni tanto e rimuovere voci su progetti chiusi, altrimenti la directory cresce senza controllo e l’indice diventa rumore.

Un buon momento per la pulizia e’ subito dopo una release o una chiusura di progetto: si sa cosa non serve piu’. Un hook su Stop (https://www.smartworkers.cloud/?p=3421) puo’ ricordare a fine turno di dare un’occhiata, oppure uno slash command (https://www.smartworkers.cloud/?p=3419) dedicato che apre il file in editor.

Privacy: cosa non scrivere

CLAUDE.md viene caricato in ogni sessione e, se il repository e’ pubblico, il file finisce su GitHub come qualunque altro. Quindi: mai credenziali, mai API key, mai segreti, nemmeno “provvisori”. Valgono le stesse cautele del README. L’auto-memory resta locale, ma contiene spesso note su progetti, clienti, decisioni strategiche: se il disco e’ condiviso o la macchina e’ aziendale, vale la pena pensare in anticipo a cosa sia accettabile che Claude annoti.

In pratica: tutto cio’ che non metteresti in un commit, non metterlo nemmeno in CLAUDE.md. Tutto cio’ che non diresti a voce in una riunione aperta, evita che finisca in auto-memory.

I due layer insieme

CLAUDE.md e auto-memory non sono alternativi, sono complementari. Il primo e’ la costituzione del progetto, cambia raramente e in modo deliberato. Il secondo e’ il diario operativo, cambia ogni settimana e in modo semi-automatico. Usati bene, riducono drasticamente il tempo speso a “spiegare di nuovo” a ogni sessione. Qual e’ la prima regola che varrebbe la pena mettere nero su bianco nel proprio CLAUDE.md?