CLAUDE.md — il cervello del tuo progetto

Dai a Claude contesto permanente con un singolo file markdown

⏱ Stima ~4 min

01 · Leggi

Ogni volta che apri una nuova session di Claude Code, Claude riparte da zero. Non ricorda la conversazione precedente, il tuo stile di codice, le convenzioni del progetto, né il framework che usi. Devi rispiegare tutto ogni volta.

CLAUDE.md risolve questo. È un file markdown che Claude legge all'inizio di ogni session — il manuale di istruzioni permanente del tuo progetto.

💡 Immagina cosìPensa a CLAUDE.md come al documento di onboarding per un nuovo membro del team. Invece di spiegare le convenzioni del team ogni mattina, lo scrivi una volta sola. CLAUDE.md è quel documento — Claude lo legge ogni volta che "inizia a lavorare".

Punti chiave

Ogni session di Claude Code ricomincia da capo — non ricorda le conversazioni passate
CLAUDE.md viene caricato automaticamente all'inizio di ogni session
Dice a Claude le regole del progetto, le convenzioni e il contesto importante
È solo un file markdown — lo modifichi come qualsiasi altro file

02 · Leggi

CLAUDE.md può stare in tre posti, ciascuno con uno scope diverso.

Livello progetto — metti CLAUDE.md nella root del repo (o in .claude/CLAUDE.md). Condiviso con il team tramite git. Usalo per convenzioni del progetto, comandi di build, pattern architetturali.

Livello utente — metti ~/.claude/CLAUDE.md. Personale, vale per tutti i tuoi progetti. Usalo per le tue preferenze personali.

Sottocartelle — i file CLAUDE.md nelle sottocartelle vengono caricati on demand quando Claude legge file in quella cartella. Ideale per istruzioni specifiche a un modulo.

Punti chiave

Livello progetto (./CLAUDE.md): condiviso con il team, committato su git
Livello utente (~/.claude/CLAUDE.md): personale, per tutti i tuoi progetti
CLAUDE.md nelle sottocartelle: caricato on demand per moduli specifici
In caso di conflitto, le regole del progetto prevalgono su quelle dell'utente

03 · Esempio di codice

Un buon CLAUDE.md include comandi di build, stile del codice, architettura e convenzioni specifiche del progetto. Ecco un esempio reale.

Esempio CLAUDE.md

# Build & Test
- `npm run dev` — start frontend dev server
- `npm run build` — TypeScript check + production build
- `npm test` — run tests (Vitest)

# Code Style
- TypeScript strict mode, ES modules (import/export)
- 2-space indentation, single quotes
- Functional React components, no class components

# Architecture
- API routes in `server/src/routes/`
- Database schema in `server/src/db/schema.ts`
- Frontend components in `src/components/`

# Important
- The `--color-purple` CSS variable is actually orange (#FF6B35)
- Auth cookies use sameSite: 'none' for cross-origin

Nota cosa include: le cose che Claude non scoprirebbe da solo leggendo il codice. Comandi di build, convenzioni di naming inusuali, quirk da fonti diverse. Non includere cose che Claude può scoprire esplorando — concentrati su ciò che non è ovvio.

04 · Esempio di codice

Quando il tuo CLAUDE.md cresce, puoi usare import e una cartella rules per suddividerlo in file focalizzati.

CLAUDE.md con @import

# Project Overview
See @README.md for project description
See @specs/ARCHITECTURE.md for system design

# Code Style
@docs/code-style.md

Struttura della cartella Rules

.claude/
├── CLAUDE.md          (main instructions)
└── rules/
    ├── api-design.md  (API conventions)
    ├── testing.md     (test patterns)
    └── security.md    (security rules)

Il prefisso @ importa il contenuto di un altro file in CLAUDE.md. La cartella .claude/rules/ contiene regole specifiche per argomento, caricate automaticamente da Claude. Mantiene il CLAUDE.md principale snello, dando a Claude accesso a conoscenze dettagliate per dominio.

05 · Quiz

Hai convenzioni di progetto che ogni sviluppatore del team deve seguire. Dove metti il tuo CLAUDE.md per condividerle con il team?

La tua home directory (~/.claude/CLAUDE.md)
La root del repo (./CLAUDE.md), committato su git
Un Google Doc linkato nel README
Un messaggio fissato nel canale Slack

06 · Completa

Per importare un altro file in CLAUDE.md, aggiungi _____ davanti al percorso

Altre lezioni di questo capitolo

⚠ L'esperienza interattiva completa richiede JavaScript. Attivalo e ricarica la pagina.

※ Questo è un progetto educativo indipendente — non è un prodotto ufficiale di Anthropic. Claude™ è un marchio di Anthropic, PBC.