Best Practice per CLAUDE.md: Configura Claude Code per Qualsiasi Progetto
CLAUDE.md e' la singola configurazione piu' impattante per Claude Code. Un file ben scritto trasforma l'assistenza IA generica in competenza specifica per il progetto.
CLAUDE.md e' un file markdown nella root del tuo progetto. Claude Code lo legge all'inizio di ogni sessione prima che tu digiti qualsiasi cosa. Un buon CLAUDE.md trasforma l'IA generica in uno strumento che comprende le convenzioni, lo stack tecnologico e i limiti del tuo progetto.
Cosa dovresti includere in CLAUDE.md?
Concentrati sulle informazioni che uno sviluppatore intelligente che entra nel tuo team avrebbe bisogno il primo giorno. Mantienilo pratico: stack tecnologico, comandi, convenzioni e cose da evitare.
Template CLAUDE.md minimale
# Contesto del Progetto
App Next.js 14 con TypeScript, Tailwind CSS e Prisma.
Database: PostgreSQL. Auth: NextAuth.js.
## Comandi
- `npm run dev` — avvia server di sviluppo (porta 3000)
- `npm run test` — esegui test Jest
- `npm run lint` — esegui ESLint
- `npm run db:migrate` — esegui migrazioni Prisma
## Architettura
- Server component di default, client component in /components/client/
- Route API in /app/api/ con validazione Zod
- Query database in /lib/db/ (mai nei component)
## Convenzioni
- TypeScript strict mode, non usare mai `any`
- Tailwind per lo styling, niente CSS modules
- Commit convenzionali: feat:, fix:, chore:
## NON fare
- Modificare file in /legacy/ o /vendor/
- Cambiare la configurazione auth senza approvazione esplicita
- Aggiungere nuove dipendenze senza chiedere primaQuali sono gli errori piu' comuni con CLAUDE.md?
| Errore | Perche' danneggia | Soluzione |
|---|---|---|
| Troppo lungo (500+ righe) | Spreca la finestra di contesto ad ogni sessione | Mantienilo sotto le 200 righe, linka alla documentazione per i dettagli |
| Troppo vago ("scrivi codice pulito") | Non fornisce indicazioni attuabili | Sii specifico: "Usa server component di default" |
| Comandi mancanti | Claude indovina come eseguire/testare/buildare | Elenca ogni script npm rilevante |
| Nessuna restrizione | Claude potrebbe modificare file sensibili | Aggiungi una sezione chiara "NON fare" |
| Duplicato del README | Il README e' per gli umani, CLAUDE.md e' per l'IA | Concentrati su convenzioni e regole, non sulla descrizione del progetto |
Come strutturare CLAUDE.md per progetti grandi?
Per codebase grandi, usa la sintassi @import per dividere la configurazione tra le directory. Claude Code segue gli import e costruisce un quadro completo.
# Root CLAUDE.md
## Convenzioni globali
- TypeScript strict, niente `any`
- Tutte le route API validano l'input con Zod
@import packages/api/CLAUDE.md
@import packages/web/CLAUDE.md
@import packages/shared/CLAUDE.mdOgni sotto-CLAUDE.md contiene regole specifiche per quel pacchetto. Questo mantiene il file root breve dando a Claude Code un contesto approfondito su ogni area del codebase.
Come generare CLAUDE.md automaticamente?
Claude Code puo' generare un CLAUDE.md iniziale analizzando il tuo progetto:
# Auto-generare CLAUDE.md
claude /init
# Questo crea un CLAUDE.md basato su:
# - Script package.json
# - Struttura del progetto
# - File di configurazione esistenti
# - Pattern della cronologia gitInizia con /init, poi affina manualmente. Il file auto-generato e' un buon punto di partenza, ma non conoscera' le convenzioni non scritte del tuo team. Aggiungile tu stesso.
La gerarchia di memoria di CLAUDE.md
Claude Code legge i file CLAUDE.md da piu' posizioni, in ordine di priorita':
- +CLAUDE.md nella root del progetto (condiviso con tutto il team)
- +File CLAUDE.md nelle sottodirectory (tramite @import)
- +~/.claude/CLAUDE.md (le tue preferenze personali globali)
- +Memoria Automatica (MEMORY.md, gestita dal comando /memory)
Le impostazioni a livello di progetto sovrascrivono quelle personali. Questo significa che le convenzioni del team hanno sempre la precedenza sulle preferenze individuali.