Il CLAUDE.md che uso in ogni repo: template con esempi reali

Il CLAUDE.md che uso in ogni repo

30 righe. Nella root. Claude Code le legge da solo ogni volta che apri una sessione.

È il file che mi ha fatto smettere di riscrivere il contesto ogni volta.

Cos'è e come funziona

Claude Code ha un meccanismo di context loading automatico: all'avvio, cerca un file chiamato CLAUDE.md nella directory corrente e nei parent. Se lo trova, lo carica nel contesto prima ancora che tu scriva il primo messaggio.

Senza CLAUDE.md:

1. Apri la sessione
2. Spieghi il progetto
3. Spieghi cosa non toccare
4. Dai il task

Con CLAUDE.md:

1. Apri la sessione
2. Dai il task

Dieci minuti risparmiati per run. Su 21 automazioni con task settimanali, sono ore.

Le 4 sezioni che uso

1) Contesto del progetto

Cosa fa questo repo. In 3 righe, non di più. Deve rispondere a tre domande: cosa produce, in quale stack, dove va a finire l'output.

Esempio dal mio repo pipeline reel:

# Pipeline reel Instagram
Repo del Job Cloud Run che renderizza i reel con Remotion,
monta la voce ElevenLabs e pubblica su Instagram via Graph API.
Output: video 1080x1920, pubblicazione automatica ogni giorno.

2) Comandi essenziali

Come si avvia, come si testa, come si fa il deploy. Claude Code usa questi per eseguire, non per sapere. Formattali come comandi veri.

Esempio:

## Comandi
npm run dev        # avvia in locale
npm run test       # test suite
npm run build      # build produzione

3) File e cartelle da non toccare

Questa è la parte più importante per evitare errori silenziosi. Ogni repo ha file che non devono essere modificati automaticamente.

Esempio:

## NON TOCCARE MAI
- /data/raw/*      # dati sorgente
- .env             # credenziali locali
- /dist/*          # generato dal build
- reel-queue/*.json  # file di trigger produzione

Ho aggiunto ogni voce dopo un errore reale. Non ho indovinato a priori: ho imparato sul campo e ho aggiornato il file.

4) Branch principale e convenzioni

Quale branch è main, come si chiamano i branch di sviluppo, qual è la convenzione per i commit.

Esempio:

## Git
branch principale: main
commit convention: tipo: descrizione breve
niente force push su main

Il template da copiare

# Nome del progetto
Cosa fa, in 1-3 righe. Stack. Dove va l'output.

## Comandi
comando    # cosa fa
comando    # cosa fa

## NON TOCCARE MAI
- file o cartella    # motivo
- file o cartella    # motivo

## Git
branch principale: main
convenzione commit: tipo: descrizione

Come lo tengo aggiornato

Ogni volta che scopro un vincolo nuovo, lo aggiungo subito. Il CLAUDE.md è vivo: cresce con il progetto.

Due aggiornamenti che ho fatto:

1. Dopo che Claude Code ha modificato per errore un file di configurazione, ho aggiunto quella cartella nella sezione NON TOCCARE. Non è più successo.
2. Dopo un commit sul branch sbagliato, ho aggiunto la convenzione git. Ora parte sempre dal branch giusto.

Tempo di manutenzione: 5 minuti al mese. Tempo risparmiato: 10 minuti per ogni sessione.

Una cosa che non funziona

Il CLAUDE.md non sostituisce un briefing per task su un dominio nuovo. È il punto di partenza per il contesto strutturale, non il contesto completo per ogni task.

La combinazione: CLAUDE.md per la struttura del progetto, briefing inline per il task specifico. Non uno o l'altro.

Il punto

30 righe. Una volta, per repo. E ogni sessione di Claude Code inizia da dove ti serve, non da zero.