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.

Le AI parlano di te? Le AI stanno cambiando il modo in cui le persone cercano e scelgono. La domanda che riguarda la tua attività è una sola: quando qualcuno chiede di te a ChatGPT, Gemini, Perplexity o Google AI, compari nelle risposte? Se non lo sai, è da lì che parto. Con il check di visibilità AI gratuito misuro dove sei oggi e ti mando un report con la prima mossa da fare, senza impegno.

Se vuoi approfondire l‘argomento puoi leggere questa guida che ho creato: Usare l’AI nel marketing senza perdere la tua voce (né il giudizio)