CLAUDE.md: le quattro regole che fanno sbagliare meno un agente di coding
Il CLAUDE.md è il file di testo che Claude Code legge all'inizio di ogni sessione per sapere come lavorare dentro un progetto. Un repository su GitHub, multica-ai/andrej-karpathy-skills, ha preso quel formato e lo ha ridotto a quattro regole di comportamento, ricavate dalle osservazioni di Andrej Karpathy sugli errori tipici dei modelli quando scrivono codice. Secondo la pagina del repository ha circa 219.000 stelle ed è distribuito con licenza MIT.
Le stelle contano poco. Contano le quattro regole, perché ognuna corrisponde a un errore che ha già visto chiunque abbia lasciato lavorare un agente di coding da solo per più di un quarto d'ora.
Quali regole mettere nel CLAUDE.md per far sbagliare meno l'agente
Le regole da mettere nel CLAUDE.md sono quattro, e la tabella le riassume con il nome originale del repository, l'errore che ciascuna previene e la riga che scriverei in italiano. La terza colonna è una mia traduzione, non un testo del repository.
| Principio del repository | Errore che previene | Riga da scrivere nel file |
|---|---|---|
| Think Before Coding | Il modello sceglie in silenzio un'interpretazione e va avanti | Se la richiesta ha più letture, elencale e chiedi prima di scrivere codice |
| Simplicity First | Codice speculativo, astrazioni usate una volta sola, opzioni mai richieste | Scrivi il minimo codice che risolve il problema, niente funzioni che non ho chiesto |
| Surgical Changes | Refactoring di codice che funzionava, modifiche estranee al compito | Tocca solo ciò che serve al compito e segnala il codice morto invece di cancellarlo |
| Goal-Driven Execution | Compiti vaghi, nessun criterio per dire che sono finiti | Trasforma il compito in un risultato verificabile, per esempio un test che fallisce prima della correzione |
Il repository precisa che le regole privilegiano la prudenza sulla velocità e che per i compiti banali si può affidarsi al giudizio del modello.
Da dove arrivano le quattro regole e perché sono criteri
Il README del repository fa risalire le regole alle osservazioni di Andrej Karpathy sugli errori dei modelli nel codice e descrive il problema in una frase:
The models make wrong assumptions on your behalf and just run along with them without checking.
Il README aggiunge che i modelli tendono a complicare il codice e a lasciare in giro codice morto. Le quattro regole rispondono a questi due difetti: Think Before Coding contro le assunzioni non verificate, Simplicity First e Surgical Changes contro la complicazione e il rumore, Goal-Driven Execution contro la consegna senza prova.
Sono criteri e non divieti, ed è la ragione per cui reggono. Un divieto elenca i casi che conosci, un criterio copre anche quelli che non hai previsto. È la stessa logica che ho descritto in come riscrivere CLAUDE.md, skill e prompt per Claude 5: conviene scrivere una regola come criterio e non come divieto.
Come funziona un agente come Claude Code quando legge il CLAUDE.md
Claude Code legge il CLAUDE.md all'inizio di ogni sessione, perché secondo la documentazione sulla memoria ogni sessione parte con una finestra di contesto nuova. Se vuoi il quadro dello strumento, l'ho scritto in cos'è Claude Code e come funziona.
La stessa documentazione dice tre cose che cambiano il modo di scrivere il file. Claude tratta il CLAUDE.md come contesto e non come configurazione imposta. Conviene restare sotto le 200 righe per file, perché i file più lunghi consumano contesto e riducono l'aderenza. E un'istruzione specifica funziona meglio di una vaga: la documentazione contrappone "API handlers live in src/api/handlers/" a "Keep files organized".
Le quattro regole sono scritte in forma generale, quindi vanno adattate al progetto. "Tocca solo ciò che serve" diventa più efficace se aggiungi dove sta il codice che l'agente non deve toccare.
Come aggiungere le quattro regole al CLAUDE.md di un progetto
Le strade sono due, e le indica il README del repository. La prima è installare il plugin, che rende la skill disponibile in tutti i progetti, con due comandi dentro Claude Code:
/plugin marketplace add forrestchang/andrej-karpathy-skills
/plugin install andrej-karpathy-skills@karpathy-skills
L'alternativa è scaricare il file CLAUDE.md nel progetto, se è nuovo, oppure aggiungerlo in fondo a quello che hai già. Questa strada ha un vantaggio: le regole stanno nel repository, si vedono in una pull request e viaggiano con il codice.
Per sapere se funzionano, il README elenca quattro segni: meno modifiche inutili nei diff, meno riscritture dovute a primi tentativi troppo complicati, domande di chiarimento prima dell'implementazione e non dopo l'errore, pull request pulite e senza refactoring collaterale. Il controllo più semplice è git diff --stat dopo ogni compito: se l'agente ha toccato dieci file per una modifica che ne richiedeva due, la regola Surgical Changes non sta lavorando.
Cosa c'è, e cosa manca, nel CLAUDE.md di questo sito
Il CLAUDE.md di questo sito è lungo 66 righe e ha due sezioni, Commands e Architecture. Dice come si avvia il progetto, dove stanno le rotte e come funziona il blog. Non contiene nessuna regola di comportamento: nessuna delle quattro regole di questo articolo c'è scritta.
Il confronto con il repository di Karpathy mette in discussione questa scelta. Un file che descrive il progetto aiuta l'agente a orientarsi. Un file che descrive come comportarsi lo aiuta a non fare danni, e sono due lavori diversi.
Le istruzioni sul comportamento stanno altrove, nelle skill della cartella .claude/skills, per esempio quella che governa come si scrive un articolo. Valgono per un compito preciso e non proteggono gli altri; il ragionamento su quando una procedura merita una skill invece di una riga nel file è in trasformare un documento in una skill per Claude Code.
Dove le quattro regole non bastano
Le quattro regole non bastano perché restano testo, e il testo non obbliga nessuno. La documentazione di Claude Code lo dice in modo esplicito: per bloccare un'azione a prescindere da ciò che Claude decide serve un hook PreToolUse. Se una modifica non deve mai avvenire, per esempio su un file di configurazione, la regola nel CLAUDE.md è una richiesta e l'hook è un divieto: lo spiego in come bloccare un'azione con gli hook di Claude Code.
Anche la quarta regola ha un limite. Un criterio di successo verificabile presuppone che esistano i test, e chi li fa scrivere allo stesso agente che scrive il codice ha un problema che il file non risolve, come racconto in chi scrive la prova che giudica il codice di un agente.
La mia posizione è questa: metti le quattro regole nel file, riscrivile con i nomi delle tue cartelle, e tieni gli hook per tutto ciò che non puoi permetterti di sbagliare.
Domande frequenti
CLAUDE.md e AGENTS.md sono la stessa cosa?
No, sono due file diversi con lo stesso scopo. Secondo la documentazione di Claude Code, se un repository usa un file AGENTS.md, Claude può leggerlo al posto del CLAUDE.md. Chi lavora con più strumenti di coding sullo stesso progetto può quindi tenere un solo file di istruzioni.
Le regole di Karpathy funzionano anche con Cursor?
Il repository multica-ai/andrej-karpathy-skills contiene accanto al CLAUDE.md anche un file CURSOR.md e una cartella .cursor/rules, quindi l'autore le ha pensate anche per Cursor. Non ho misurato la differenza di comportamento fra i due strumenti, quindi non posso dire quanto funzionino.
Che cosa succede se due righe del CLAUDE.md si contraddicono?
Secondo la documentazione di Claude Code, quando due istruzioni sono in contrasto Claude può sceglierne una a caso. Per questo conviene rileggere ogni tanto il CLAUDE.md, quelli annidati nelle sottocartelle e la cartella .claude/rules, togliendo le righe vecchie.
Come si crea un CLAUDE.md in un progetto nuovo?
Dentro Claude Code si lancia il comando /init, che analizza il progetto e crea un file con i comandi di build, le istruzioni per i test e le convenzioni che trova. Se il file esiste già, /init propone miglioramenti senza sovrascriverlo.