CLAUDE.md fatto bene: il file che decide quanto è brava la tua AI

C'è un solo file che decide quanto è brava la tua AI. Claude lo legge all'inizio di ogni sessione, prima ancora che tu scriva: se è fatto bene, parte già sul pezzo.

Un file decide quanto è brava la tua AI

Se usi Claude Code, tutto quello che ottieni dipende dal CLAUDE.md. Claude lo apre da solo a ogni sessione: se è fatto bene, si presenta già sapendo com'è fatto il tuo progetto, dove stanno le cose e come lavori. Se è fatto male — o non c'è — riparte ogni volta da zero e tu passi il tempo a rispiegargli le stesse cose. Quasi tutti lo impostano nel modo sbagliato.

I cinque consigli

1 · Capisci cos'è davvero

È un indice, non un manuale. Il CLAUDE.md non deve contenere tutto: deve essere la tabella dei contenuti del tuo progetto — una mappa che dice a Claude dove trovare le cose, non che gliele racconta tutte.

Puoi avere anche centinaia di file. Questo è l'unico che Claude apre da solo, sempre. Quindi il suo lavoro è uno: puntare a tutto il resto. I dettagli stanno negli altri file, e il CLAUDE.md li richiama quando servono.

2 · Non scriverlo da zero

Qui la gente si blocca, e non serve. Non devi scrivere il CLAUDE.md a mano davanti al cursore che lampeggia. Lancia un comando e Claude analizza il progetto e ti scrive la prima bozza da solo.

3 · Trattalo come una bozza

Quello che esce da /init è un punto di partenza, non la verità. Rileggilo, correggi quello che è sbagliato, aggiungi le regole che tu conosci ma che l'AI non poteva indovinare: le tue convenzioni, cosa non toccare mai, come vuoi che lavori.

E soprattutto: aggiornalo nel tempo. Va posseduto e revisionato come il resto del lavoro — ogni volta che qualcosa cambia, digli di aggiornarlo. Un file fermo a tre mesi fa mente a Claude.

4 · Dai a Claude una mappa

È il pezzo che fa la differenza: un riassunto veloce + l'albero delle cartelle. Così sa dove guardare, invece di andare a tentoni. Modello pronto da incollare e riempire:

# Progetto: [nome]
Cos'è: [1-2 frasi]

## Comandi
- Installa: [es. npm install]
- Avvia:    [es. npm run dev]
- Test:     [es. npm test]

## Dove vivono le cose
- src/        codice principale
- data/       dati e configurazioni
- contenuti/  [quello che produci]
- docs/       guide e SOP

## Regole
- [es. lancia i test prima di committare]
- [es. rispetta lo stile dei file esistenti]
- [es. non toccare /legacy]

## Approfondimenti (on-demand)
- Architettura: docs/architettura.md
- Deploy:       docs/deploy.md

5 · Tienilo sotto le 200 righe

Snello è più produttivo. Sempre. Questo file entra in ogni singola sessione. Se diventa enorme succede una cosa controintuitiva: Claude presta meno attenzione a ciò che conta, perché l'importante è annegato nel resto. Non serve che dica tutto — deve rimandare a tutto: i dettagli lunghi negli altri file, richiamati quando servono. Il CLAUDE.md resta corto e affilato.

Il test dei 30 secondi

C'è un modo veloce per capire se è fatto bene. Chiediti:

Se arrivasse oggi una persona nuova nel progetto, capirebbe com'è fatto e come si lavora leggendo solo il CLAUDE.md, in due minuti?

Se la risposta è sì, è a posto. Se no, è troppo confuso o troppo pieno: sfoltisci e riordina.

Bonus: fallo auto-verificare a Claude

Non devi giudicarlo da solo. Incolla questo prompt a Claude, insieme al tuo CLAUDE.md:

Prima di chiudere

• Indice, non manuale. Il CLAUDE.md punta agli altri file, non li sostituisce. Corto e affilato.
• Parti da /init, poi possiedilo. La prima bozza te la scrive Claude — il tuo lavoro è correggerla e tenerla viva.
• Snello vince. Sotto le 200 righe, sennò l'importante annega e l'AI smette di guardarlo.

Claude Code è uno strumento di terze parti: comandi e menu possono cambiare nel tempo — segui la logica dei passaggi.