Smettila di ripeterti. Ecco come configurare un CLAUDE.md a prova di bomba

Immagina di avere al tuo fianco uno sviluppatore instancabile, velocissimo e geniale, ma con la memoria di un pesce rosso ogni volta che aprite un nuovo terminale. Frustrante, vero? Passi i primi venti minuti a spiegargli come avviare il server, in quali cartelle mettere le mani e quali sono le regole non scritte del tuo codice.

Eppure, c’è un segreto (se così possiamo chiamarlo) che la maggior parte delle persone ignora o sottovaluta. Mettiamola così: se utilizzi Claude, il file CLAUDE.md è il cuore pulsante di ogni tuo progetto. Non è un semplice file di testo: è il DNA della tua repository, il vero e proprio “libretto di istruzioni” che Claude legge ancor prima che tu digiti il primo prompt. È quella mappa del tesoro capace di trasformare l’AI da uno stagista confuso al tuo miglior alleato tecnico, perfettamente allineato con il tuo modo di programmare. Un file debole equivale a paracadutare Claude nel buio totale; un file scritto a regola d’arte equivale a fare un onboarding perfetto a un senior engineer.

Scopriamo come scrivere un documento che cambierà radicalmente le tue sessioni di coding.

Perché il tuo file CLAUDE.md attuale (probabilmente) non funziona

Se hai già provato a crearne uno senza successo, è probabile che tu sia caduto in una di queste tre trappole:

1. Hai scritto un papiro illeggibile: L’attenzione di Claude, per quanto vasta, ha dei limiti. Gran parte del suo “spazio mentale” è già occupato dalle istruzioni di sistema. Se gli propini un documento di oltre 200 righe, lo stai solo ingolfando. Le direttive fondamentali si annacquano e verranno ignorate per puro sovraccarico cognitivo. Sii spietatamente conciso.
2. Hai inserito solo banalità: Scrivere istruzioni come “Comportati da esperto” o “Ragiona con calma” è tempo perso. Claude lo fa già. Ogni singola riga di questo file deve avere un mandato chirurgico: prevenire un errore che altrimenti accadrebbe. Se una frase non serve a questo scopo, eliminala. È solo rumore.
3. Manca totalmente di gerarchia: Trattare tutte le regole allo stesso modo crea caos. I professionisti dividono il contesto su tre livelli ben definiti:
   • Globale (~/.claude/CLAUDE.md): Le tue regole d’oro, valide sempre.
   • Di Progetto (.claude/CLAUDE.md): Le convenzioni condivise con il resto del team.
   • Locale (CLAUDE.local.md): I tuoi test o le preferenze del momento.

Le 5 sezioni per un setup infallibile

Guardando sotto il cofano dei progetti più efficienti, emerge un pattern chiarissimo. I migliori file si basano su queste cinque colonne portanti.

1. I comandi (Commands)

Smettila di far indovinare a Claude come si accende il motore del tuo progetto. Dagli le chiavi in mano.

Comandi:

## Commands
- Dev: npm run dev
- Build: npm run build
- Test singolo: npm test -- path/to/file
- Test tutti: npm test
- Lint: npm run lint
- Type check: npx tsc --noEmit

2. La mappa dell’architettura (Architecture)

Non devi scrivere l’Enciclopedia Britannica del tuo codice, ma solo fornirgli una bussola per non perdersi tra le cartelle.

Struttura:

## Architecture
- src/components/ → Solo UI
- src/lib/services/ → Logica di business
- src/lib/store/ → Stato globale
- src/app/api/ → Solo rotte API
- Accesso al Database tramite API o server actions

3. I paletti (Rules)

Questa è la vera zona di massima allerta. Chiediti: “Se ometto questa regola, l’AI farà un disastro?”. Se la risposta è sì, scrivila qui. Usa il maiuscolo per le cose davvero critiche e non superare mai le 15 regole totali.

Regole:

## Rules
- MAI pushare .env o segreti
- Tutte le chiamate async devono usare try/catch
- Usa solo functional componenti
- Esegui i test prima di terminare qualsiasi task
- IMPORTANTE: esegui il type check dopo ogni modifica

4. Il comportamento (Workflow)

Come vuoi che agisca? Vuoi che parta in quarta o che ti chieda il permesso? Questa sezione blocca sul nascere la frustrazione dell’over-engineering.

Flusso lavorativo:

## Workflow
- Chiedi prima di iniziare task complessi
- Apporta solo modifiche minimali
- Non rifattorizzare codice non correlato
- Esegui i test dopo le modifiche
- Crea commit separati per ogni modifica logica
- Se insicuro, presenta le opzioni prima di agire

5. L’arte di omettere (Out of scope)

Un file eccellente si nota anche da ciò che esclude. Lascia fuori: i tratti della personalità, le regole di formattazione (ci pensa già il tuo linter!), i papiri di documentazione tecnica e, soprattutto, non ripetergli cose che ha già interiorizzato lavorando con te. La memoria di Claude si evolve, non serve fare i pappagalli.

Il tuo template pronto all’uso

Copia e incolla questa struttura nel tuo progetto. Mettiti come obiettivo di non superare le 80 righe complessive: l’essenziale batte sempre l’esaustivo.

# CLAUDE.md

## Project
[Cosa fa questo progetto]

## Stack
[Framework, linguaggio, database]

## Commands
- Dev: 
- Build: 
- Test: 
- Lint: 
- Type check: 

## Architecture
- [cartella] → scopo
- [cartella] → scopo

## Rules
- [previeni un errore reale]
- IMPORTANTE: [regola critica]

## Workflow
- [come Claude dovrebbe lavorare]
- [aspettative sui test]
- [stile dei commit]

## Out of scope
- [cose che Claude non deve toccare]

I “Cheat Code” per svoltare davvero

Vuoi fare il salto di qualità? Inserisci sempre queste indicazioni universali per azzerare gli errori stupidi:

• Esigi il type check: Costringilo a verificare i tipi dopo ogni singola modifica.
• Imponi il minimalismo: Niente rifattorizzazioni non richieste in file che non c’entrano nulla.
• Dividi e impera: Fagli creare commit logicamente separati, mai un unico blocco gigante.
• Fallo dubitare: Obbligalo a proporti delle alternative prima di prendere una strada se il task è ambiguo.
• Blocca le iniziative architettoniche: Nessun nuovo pattern o libreria senza la tua esplicita approvazione.

CLAUDE.MD il cuore del tuo progetto

Smettila di trattare il CLAUDE.md come se fosse la letterina dei desideri a Babbo Natale. Non lo è. È un contratto tecnico nudo e crudo.

Creare un file impeccabile significa abbattere drasticamente la necessità di ripeterti a ogni sessione. Significa godere di un workflow in cui l’AI non commette mai due volte lo stesso errore, perché ogni tuo rimprovero passato si è trasformato in una regola di ferro.

Il segreto della produttività con l’AI non è passare le notti a cercare “il prompt magico”. È costruire un sistema di base talmente solido da rendere ogni tua richiesta, anche la più banale, un successo assicurato.