CLAUDE.md: cos'è, cosa scriverci e come scriverlo bene

In breve: CLAUDE.md è un file di testo che metti nella cartella del tuo progetto e che Claude Code legge all'inizio di ogni sessione. Serve a dargli, una volta sola, le informazioni che altrimenti dovresti ripetere: lo stack, le convenzioni, i comandi utili, le cose da non toccare. Più il file è breve, preciso e verificabile, meglio l'agente lo rispetta.

È il modo più economico per migliorare i risultati di Claude Code, ed è la prima cosa da fare in un progetto nuovo. Vediamo cosa scriverci, dove metterlo e gli errori da evitare.

Come funziona

All'avvio di una sessione Claude Code carica i file CLAUDE.md che trova: uno nella radice del progetto (che puoi condividere con il team nel repository) e uno personale nella tua cartella ~/.claude/, valido per tutti i progetti. Quel testo diventa parte delle istruzioni che accompagnano ogni richiesta. Se nel repository c'è già un file AGENTS.md pensato per altri agenti, Claude Code può leggere anche quello. Inoltre l'agente costruisce da solo una "memoria automatica" durante il lavoro, salvando ciò che impara tra una sessione e l'altra.

Puoi generare una prima bozza con il comando /init, che analizza il progetto e scrive un file iniziale da rifinire.

Cosa metterci

• Lo stack e la struttura: linguaggio, versioni, cartelle importanti.
• I comandi: come si avvia, come si testano le modifiche, come si fa la build.
• Le convenzioni: nomi, stile, come si scrivono i commit.
• I divieti e le cautele: cosa non modificare, cosa non fare mai senza chiedere (per esempio pubblicare in produzione).
• Il flusso di lavoro: dove lavori, cosa aggiorni dopo ogni sessione.

Un esempio

# Progetto: sito vetrina in PHP

## Stack
- PHP 8.3, senza framework. CSS in un file solo, niente librerie esterne.

## Comandi
- Avvio locale: php -S localhost:8000
- Controllo sintassi: php -l file.php

## Regole
- Modifiche minime: non riscrivere interi file, applica patch mirate.
- Non toccare la cartella /vendor né i file .env.
- Dopo ogni modifica, controlla la sintassi e mostra il diff.
- Chiedi conferma prima di qualsiasi operazione di deploy.

Come scriverlo bene

1. Sii breve: ogni riga viene letta a ogni sessione e occupa contesto. Meglio venti righe utili che duecento generiche.
2. Sii specifico e verificabile: "usa PHP 8.3 senza framework" funziona meglio di "scrivi codice pulito".
3. Scrivi cosa fare, non solo cosa evitare: un divieto senza alternativa lascia l'agente a indovinare.
4. Niente contraddizioni: due regole opposte producono comportamenti a caso. Rileggi il file ogni tanto.
5. Niente segreti: mai chiavi API o password, soprattutto se il file finisce nel repository.
6. Aggiornalo con l'uso: quando ti accorgi di ripetere la stessa correzione, aggiungila al file.

Gli errori più comuni

• Il file da mille righe: l'agente ne ignora una parte e consumi contesto inutilmente. Sposta le procedure lunghe in skill richiamabili quando servono.
• Istruzioni vaghe: "fai attenzione alla sicurezza" non dice nulla; "valida sempre gli input lato server" sì.
• Regole ovvie: non serve spiegare come si scrive un ciclo. Scrivi solo ciò che è specifico del tuo progetto.
• File dimenticato: un CLAUDE.md non aggiornato contiene regole di uno stack che non usi più.

CLAUDE.md, skill e hook: a ognuno il suo compito

Le istruzioni che valgono sempre vanno in CLAUDE.md. Le procedure ripetibili e lunghe, come una revisione o un deploy, stanno meglio in una skill, che l'agente carica solo quando serve. Le cose che devono accadere sempre e in modo garantito, come formattare il codice dopo ogni modifica, sono compito degli hook, che eseguono comandi in automatico. È parte di ciò che si chiama harness: l'insieme di ciò che circonda il modello.

Se stai iniziando, la guida è Cos'è Claude Code, e per un progetto passo passo come creare un'app con Claude Code. Per i costi: prezzi e piani.

Fonti

• Documentazione ufficiale di Claude Code