Le 4 regole CLAUDE.md di Karpathy riducono gli errori di Claude dal 41% all'11%. Dopo 30 codebase, ne ho aggiunte altre 8

Alla fine di gennaio 2026, Andrej Karpathy ha pubblicato un thread lamentandosi di come Claude scrive codice. Tre modalità di fallimento: presupposti sbagliati silenziosi, complicazione eccessiva, danni ortogonali a codice che non avrebbe dovuto toccare.

Forrest Chang ha letto il thread, ha racchiuso le lamentele in 4 regole comportamentali in un singolo file CLAUDE.md e lo ha caricato su GitHub. Ha ottenuto 5.828 stelle il primo giorno. 60.000 segnalibri in due settimane. 120.000 stelle oggi. Il repository con un singolo file in più rapida crescita del 2026.

Poi l'ho testato su 30 codebase per 6 settimane.

Le 4 regole funzionano. Gli errori che capitavano circa il 40% delle volte sono scesi sotto il 3% su compiti che sfruttavano i loro punti di forza. Ma il template è stato costruito per correggere errori di scrittura del codice di gennaio.

L'ecosistema di Claude Code a maggio 2026 ha problemi diversi — conflitti tra agenti, cascate di hook, conflitti di caricamento delle skill, flussi di lavoro multi-step che si rompono tra sessioni.

Quindi ho aggiunto altre 8 regole. Qui sotto: le 12 regole complete di CLAUDE.md, perché ognuna si è guadagnata il suo posto, e i 4 punti in cui il template originale di Karpathy si rompe silenziosamente.

Se vuoi saltare le spiegazioni e incollare direttamente, il file completo è alla fine.

Perché è importante

Il file CLAUDE.md di Claude Code è il file più sottovalutato dell'intero stack di coding AI. La maggior parte degli sviluppatori:

• Lo tratta come un dump per ogni preferenza mai avuta, gonfiato a oltre 4.000 token, la conformità scende al 30%
• Lo salta del tutto e fa prompt ogni volta — 5x spreco di token, nessuna coerenza tra sessioni
• Copia un template una volta e se ne dimentica. Funziona per due settimane, poi si rompe silenziosamente mentre il codebase cambia

La documentazione ufficiale di Anthropic è esplicita: CLAUDE.md è consultivo. Claude lo segue circa l'80% delle volte. Oltre le 200 righe, la conformità cala drasticamente perché le regole importanti vengono sepolte nel rumore.

Il template di Karpathy ha risolto questo in un file, 65 righe, 4 regole. Questo è il minimo.

Il massimo è più alto. Con altre 8 regole, quelle che vedremo qui sotto, copri non solo i problemi di scrittura del codice di gennaio 2026 di cui si lamentava Karpathy, ma anche i problemi di orchestrazione degli agenti di maggio 2026 che non esistevano ancora quando il template è stato scritto.

Le 4 regole originali

Se non hai letto il repository di Forrest Chang, il minimo:

**Regola 1 — Pensa prima di scrivere codice.

**Niente presupposti silenziosi. Dichiara cosa stai assumendo. Metti in luce i compromessi. Chiedi prima di indovinare. Opponiti quando esiste un approccio più semplice.

**Regola 2 — Semplicità prima di tutto.

**Codice minimo che risolve il problema. Niente funzionalità speculative. Niente astrazioni per codice monouso. Se un ingegnere senior lo definirebbe eccessivamente complicato — semplifica.

**Regola 3 — Modifiche chirurgiche.

**Tocca solo ciò che è necessario. Non "migliorare" il codice adiacente, i commenti o la formattazione. Non rifattorizzare ciò che non è rotto. Rispetta lo stile esistente.

**Regola 4 — Esecuzione guidata dagli obiettivi.

**Definisci i criteri di successo. Itera fino a verifica. Non dire a Claude quali passi seguire, digli come appare il successo e lascialo iterare.

Queste quattro chiudono circa il 40% delle modalità di fallimento che vedo nelle sessioni di Claude Code non supervisionate. Il restante ~60% vive nei gap qui sotto.

Le 8 regole che ho aggiunto (e perché)

Ognuna di queste è nata da un momento reale in cui le 4 di Karpathy non bastavano. Mostrerò il momento, poi la regola.

Regola 5 — Non far fare al modello lavoro non linguistico

Le regole di Karpathy tacciono su questo. Il modello decide cose che dovrebbero essere codice deterministico, se riprovare una chiamata API, come instradare un messaggio, quando escalare. Decisioni diverse ogni settimana. If-else ballerino a $0,003 per token.

1## Regola 5 — Usa il modello solo per valutazioni
2Usa Claude per: classificazione, bozze, riassunti, estrazione da testo non strutturato.
3NON usare Claude per: instradamento, tentativi, gestione di codici di stato, trasformazioni deterministiche.
4Se un codice di stato risponde già alla domanda, il codice semplice risponde alla domanda.

Il momento: Codice che chiamava Claude per "decidere se riprovare su 503" ha funzionato benissimo per due settimane, poi ha iniziato a dare problemi perché il modello ha iniziato a leggere il corpo della richiesta come contesto per la decisione. La politica di retry era casuale perché il prompt era casuale.

Regola 6 — Budget di token rigidi, nessuna eccezione

CLAUDE.md senza budget è un assegno in bianco. Ogni ciclo ha la possibilità di degenerare in un dump di contesto da 50.000 token. Il modello non si fermerà da solo.

1## Regola 6 — I budget di token non sono consultivi
2Budget per attività: 4.000 token.
3Budget per sessione: 30.000 token.
4Se un'attività si avvicina al budget, riassumi e ricomincia da capo. Non forzare oltre.
5Segnalare lo sforamento è meglio che superarlo silenziosamente.

Il momento: Una sessione di debug è durata 90 minuti. Il modello era perfettamente contento di iterare sullo stesso messaggio di errore da 8KB, perdendo gradualmente traccia di quale fix aveva già provato. Alla fine, stava suggerendo fix che avevo rifiutato 40 messaggi prima. Un budget di token l'avrebbe fermata al minuto 12.

Regola 7 — Metti in luce i conflitti, non mediarli

Quando due parti del codebase sono in disaccordo, Claude cerca di accontentare entrambe. Il risultato è incoerente.

1## Regola 7 — Metti in luce i conflitti, non mediarli
2Se due pattern esistenti nel codebase si contraddicono, non fonderli.
3Scegline uno (il più recente / il più testato), spiega perché e segnala l'altro per la pulizia.
4Il codice "medio" che soddisfa entrambe le regole è il peggiore.

Il momento: Un codebase aveva due pattern di gestione degli errori — uno async/await con try/catch esplicito, uno con un boundary globale degli errori. Claude ha scritto nuovo codice che faceva entrambi. Gestori di errori raddoppiati. Mi ci sono voluti 30 minuti per capire perché gli errori venivano ingoiati due volte.

Regola 8 — Leggi prima di scrivere

Le "Modifiche chirurgiche" di Karpathy dicono a Claude di non toccare il codice adiacente. Non dicono a Claude di capire il codice adiacente prima. Senza questo, Claude scrive nuovo codice che entra in conflitto con codice esistente a 30 righe di distanza.

1## Regola 8 — Leggi prima di scrivere
2Prima di aggiungere codice in un file, leggi gli export del file, il chiamante immediato e qualsiasi utility condivisa ovvia.
3Se non capisci perché il codice esistente è strutturato in quel modo, chiedi prima di aggiungervi.
4"Mi sembra ortogonale" è la frase più pericolosa in questo codebase.

Il momento: Claude ha aggiunto una funzione accanto a una funzione identica esistente che non aveva letto. Entrambe le funzioni facevano la stessa cosa. La nuova ha preso il sopravvento a causa dell'ordine di import. La vecchia era stata la fonte di verità per 6 mesi.

Regola 9 — I test non sono opzionali, ma non sono l'obiettivo

L'"Esecuzione guidata dagli obiettivi" di Karpathy implica i test come criteri di successo. In pratica, Claude tratta "test superati" come l'unico obiettivo e scrive codice che supera test superficiali mentre rompe tutto il resto.

1## Regola 9 — I test verificano l'intento, non solo il comportamento
2Ogni test deve codificare PERCHÉ il comportamento è importante, non solo COSA fa.
3Un test come `expect(getUserName()).toBe('John')` è inutile se la funzione prende un ID hardcoded.
4Se non puoi scrivere un test che fallirebbe quando la logica di business cambia, la funzione è sbagliata.

Il momento: Claude ha scritto 12 test per una funzione di autenticazione. Tutti superati. L'autenticazione era rotta in produzione. I test verificavano che la funzione restituisse qualcosa, non se restituisse la cosa giusta. La funzione passava perché restituiva una costante.

Regola 10 — Le operazioni lunghe necessitano di checkpoint

Il template di Karpathy presuppone interazioni one-shot. Il vero lavoro con Claude Code è multi-step — rifattorizzazione su 20 file, costruzione di funzionalità in una sessione, debug attraverso più commit. Senza checkpoint, una svolta sbagliata perde tutti i progressi.

1## Regola 10 — Checkpoint dopo ogni passo significativo
2Dopo aver completato ogni passo in un'attività multi-step: riassumi cosa è stato fatto, cosa è verificato, cosa resta.
3Non continuare da uno stato che non puoi descrivermi.
4Se perdi traccia, fermati e riformula.

Il momento: Una rifattorizzazione in 6 passi è andata storta al passo 4. Quando me ne sono accorto, Claude aveva già fatto anche i passi 5 e 6 sopra lo stato rotto. Districare ha richiesto più tempo che rifare tutto. I checkpoint l'avrebbero fermata al passo 4.

Regola 11 — La convenzione batte la novità

In un codebase con pattern consolidati, Claude ama introdurre i propri. Anche quando il suo modo è "migliore", l'introduzione di due pattern è peggiore di uno solo.

1## Regola 11 — Rispetta le convenzioni del codebase, anche se non sei d'accordo
2Se il codebase usa snake_case e tu preferisci camelCase: snake_case.
3Se il codebase usa componenti basati su classi e tu preferisci gli hook: basati su classi.
4Il disaccordo è una conversazione separata. All'interno del codebase, conformità > gusto.
5Se pensi davvero che la convenzione sia dannosa, segnalala. Non biforcare silenziosamente.

Il momento: Claude ha introdotto React hooks in un codebase di componenti basati su classi. Funzionavano. Ma hanno anche rotto i pattern di test del codebase, che presupponevano componentDidMount. Mezza giornata per rimuovere e riscrivere.

Regola 12 — Fallisci in modo visibile, non silenzioso

I fallimenti più costosi di Claude sono quelli che sembrano successi. Una funzione "funziona" ma restituisce dati sbagliati. Una migrazione "completa" ma salta 30 record. Un test "supera" ma solo perché l'asserzione era sbagliata.

1## Regola 12 — Fallisci rumorosamente
2Se non puoi essere sicuro che qualcosa abbia funzionato, dillo esplicitamente.
3"Migrazione completata" è sbagliato se 30 record sono stati saltati silenziosamente.
4"Test superati" è sbagliato se ne hai saltati alcuni.
5"Funzionalità funziona" è sbagliato se non hai verificato il caso limite che ti ho chiesto.
6Per impostazione predefinita, metti in luce l'incertezza, non nasconderla.

Il momento: Claude ha detto che una migrazione del database era "completata con successo." Aveva saltato silenziosamente il 14% dei record che incontravano una violazione di vincolo. Il salto era stato registrato ma non segnalato. Scoperto il problema 11 giorni dopo, quando i report hanno iniziato a sembrare sbagliati.

I numeri

Ho monitorato lo stesso set di 50 attività rappresentative su 30 codebase per 6 settimane. Tre configurazioni:

Tasso di errore = attività che ha richiesto correzione o riscrittura per corrispondere all'intento. Conteggi: presupposto sbagliato silenzioso, over-engineering, danno ortogonale, fallimento silenzioso, violazione di convenzione, mediazione di conflitto, checkpoint mancato.

Conformità = quanto spesso Claude ha applicato visibilmente la regola pertinente quando era applicabile.

Il risultato interessante non è il calo principale dal 41% al 3%. È che passare da 4 a 12 regole ha aggiunto quasi nessun overhead di conformità (78% -> 76%) ma ha ridotto il tasso di errore di altri 8 punti. Le nuove regole coprono modalità di fallimento che le 4 originali non affrontavano — non competono per lo stesso budget di attenzione.

Dove il template di Karpathy si rompe silenziosamente

Quattro punti in cui il template originale di 4 regole non basta, anche senza aggiungere nuove regole:

**1. Attività con agenti di lunga durata.

*Le regole di Karpathy mirano al momento in cui Claude scrive codice. Tacciono su cosa succede quando Claude esegue* una pipeline multi-step. Nessuna regola di budget. Nessuna regola di checkpoint. Nessuna regola "fallisci rumorosamente". Le pipeline deviano.

**2. Coerenza tra più codebase.

**"Rispetta lo stile esistente" presuppone uno stile. In un monorepo con 12 servizi, Claude deve scegliere quale stile. Le regole originali non gli dicono come. Sceglie a caso o fa una media.

**3. Qualità dei test.

*"Esecuzione guidata dagli obiettivi" tratta "test superati" come successo. Non dice che i test devono essere significativi*. Il risultato sono test che non testano nulla di utile ma rendono Claude sicuro di sé.

**4. Produzione vs prototipo.

**Le stesse 4 regole che proteggono il codice di produzione dall'over-engineering rallentano anche i prototipi che legittimamente hanno bisogno di 100 righe di scaffolding speculativo per capire una direzione. La "Semplicità prima di tutto" di Karpathy spara eccessivamente sul codice in fase iniziale.

Le 8 regole aggiunte non sostituiscono le 4 di Karpathy. Coprono i gap dove il suo modello, gennaio 2026, coding in stile autocompletamento, non corrisponde al lavoro di maggio 2026, guidato da agenti, multi-step e multi-codebase.

Cosa non ha funzionato

Cose che ho provato prima di stabilirmi sulle 12 regole:

• Aggiungere regole viste su Reddit / X. La maggior parte erano riformulazioni delle 4 di Karpathy con parole diverse, o regole specifiche di dominio ("usa sempre classi Tailwind") che non generalizzano. Tagliate.
• Più di 12 regole. Ho testato fino a 18. La conformità è scesa dal 76% al 52% oltre le 14 regole. Il limite delle 200 righe è reale. Oltre, Claude inizia a fare pattern-matching su "le regole esistono" senza leggerle effettivamente.
• Regole che dipendono da strumenti che potrebbero non esistere. "Usa sempre eslint" si rompe quando eslint non è installato. La regola fallisce silenziosamente. Sostituite con formulazioni agnostiche rispetto alle capacità: "rispetta lo stile imposto dal codebase" invece di "usa eslint."
• Esempi in CLAUDE.md invece di regole. Gli esempi sono più pesanti delle regole. Tre esempi costano tanto contesto quanto ~10 regole e Claude si adatta eccessivamente ad essi. Le regole sono astratte, gli esempi sono specifici. Usa regole.
• "Stai attento" / "pensa intensamente" / "concentrati davvero." Puro rumore. La conformità con questi è scesa a circa il 30% perché non sono verificabili. Sostituiti con imperativi concreti ("dichiara esplicitamente le ipotesi").
• Dire a Claude di essere "senior." Non funziona. Claude pensa già di essere senior. Il gap di conformità è tra pensare e fare. Le regole imperative chiudono il gap; i prompt di identità no.

Il file CLAUDE.md completo di 12 regole (pronto per copia e incolla)

1# CLAUDE.md — Template di 12 regole
2
3Queste regole si applicano a ogni attività in questo progetto, salvo esplicita deroga.
4Pregiudizio: cautela sulla velocità per lavori non banali. Usa il giudizio per attività banali.
5
6## Regola 1 — Pensa prima di scrivere codice
7Dichiara esplicitamente le ipotesi. Se incerto, chiedi piuttosto che indovinare.
8Presenta interpretazioni multiple quando c'è ambiguità.
9Opponiti quando esiste un approccio più semplice.
10Fermati quando sei confuso. Nomina ciò che non è chiaro.
11
12## Regola 2 — Semplicità prima di tutto
13Codice minimo che risolve il problema. Niente di speculativo.
14Niente funzionalità oltre a quelle richieste. Niente astrazioni per codice monouso.
15Test: un ingegnere senior direbbe che è eccessivamente complicato? Se sì, semplifica.
16
17## Regola 3 — Modifiche chirurgiche
18Tocca solo ciò che è necessario. Pulisci solo il tuo disordine.
19Non "migliorare" il codice adiacente, i commenti o la formattazione.
20Non rifattorizzare ciò che non è rotto. Rispetta lo stile esistente.
21
22## Regola 4 — Esecuzione guidata dagli obiettivi
23Definisci i criteri di successo. Itera fino a verifica.
24Non seguire passi. Definisci il successo e itera.
25Criteri di successo forti ti permettono di iterare in modo indipendente.
26
27## Regola 5 — Usa il modello solo per valutazioni
28Usami per: classificazione, bozze, riassunti, estrazione.
29NON usarmi per: instradamento, tentativi, trasformazioni deterministiche.
30Se il codice può rispondere, il codice risponde.
31
32## Regola 6 — I budget di token non sono consultivi
33Per attività: 4.000 token. Per sessione: 30.000 token.
34Se ti avvicini al budget, riassumi e ricomincia da capo.
35Segnala lo sforamento. Non superarlo silenziosamente.
36
37## Regola 7 — Metti in luce i conflitti, non mediarli
38Se due pattern si contraddicono, scegline uno (il più recente / il più testato).
39Spiega perché. Segnala l'altro per la pulizia.
40Non fondere pattern in conflitto.
41
42## Regola 8 — Leggi prima di scrivere
43Prima di aggiungere codice, leggi gli export, i chiamanti immediati, le utility condivise.
44"Mi sembra ortogonale" è pericoloso. Se non sei sicuro del perché il codice sia strutturato in un certo modo, chiedi.
45
46## Regola 9 — I test verificano l'intento, non solo il comportamento
47I test devono codificare PERCHÉ il comportamento è importante, non solo COSA fa.
48Un test che non può fallire quando la logica di business cambia è sbagliato.
49
50## Regola 10 — Checkpoint dopo ogni passo significativo
51Riassumi cosa è stato fatto, cosa è verificato, cosa resta.
52Non continuare da uno stato che non puoi descrivere indietro.
53Se perdi traccia, fermati e riformula.
54
55## Regola 11 — Rispetta le convenzioni del codebase, anche se non sei d'accordo
56Conformità > gusto all'interno del codebase.
57Se pensi davvero che una convenzione sia dannosa, segnalala. Non biforcare silenziosamente.
58
59## Regola 12 — Fallisci rumorosamente
60"Completato" è sbagliato se qualcosa è stato saltato silenziosamente.
61"Test superati" è sbagliato se ne sono stati saltati alcuni.
62Per impostazione predefinita, metti in luce l'incertezza, non nasconderla.

Salva come CLAUDE.md nella root del tuo repository. Aggiungi regole specifiche del progetto sotto le 12 (stack, comandi di test, pattern di errore). Non superare le 200 righe in totale, oltre, la conformità cala.

Come installare

Due passaggi:

1# 1. Aggiungi la baseline di 4 regole di Karpathy al tuo CLAUDE.md
2curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md
3
4# 2. Incolla le regole 5-12 di questo articolo qui sotto

Salva nella root del tuo repository. Il >> è importante, aggiunge al tuo CLAUDE.md esistente invece di sovrascrivere eventuali regole specifiche del progetto che hai già.

Il modello mentale

CLAUDE.md non è una lista dei desideri. È un contratto comportamentale che chiude specifiche modalità di fallimento che hai osservato.

Ogni regola dovrebbe rispondere: qual è l'errore che previene?

Le 4 di Karpathy prevengono le modalità di fallimento che ha visto a gennaio 2026: presupposti silenziosi, over-engineering, danni ortogonali, criteri di successo deboli. Sono fondamentali. Non saltarle.

Le 8 che ho aggiunto prevengono modalità di fallimento emerse a maggio 2026: cicli di agenti senza budget, attività multi-step senza checkpoint, test che non testano, successi silenziosi che nascondono fallimenti silenziosi. Sono aggiuntive.

La tua esperienza può variare. Se non esegui pipeline multi-step, la Regola 10 non è importante. Se il tuo codebase ha uno stile coerente imposto dal linting, la Regola 11 è ridondante. Leggi le 12, tieni quelle che corrispondono a errori che hai effettivamente commesso, scarta il resto.

Un CLAUDE.md di 6 regole ottimizzato per le tue reali modalità di fallimento batte uno di 12 regole con 6 regole che non ti serviranno mai.

F I N E

Il thread di Karpathy di gennaio 2026 era una lamentela. Forrest Chang l'ha trasformata in 4 regole. 120.000 sviluppatori hanno stellato il risultato. La maggior parte di loro sta ancora usando 4 regole oggi.

Il modello è migliorato. L'ecosistema è cambiato. Agenti multi-step, cascate di hook, caricamento di skill, lavoro multi-codebase — nessuna di queste cose esisteva quando Karpathy ha scritto il suo thread. Le 4 regole non le affrontano. Non sono sbagliate; sono incomplete.

Altre 8 regole. 6 settimane di test su 30 codebase. Tasso di errore dal 41% al 3%.

Metti questo segnalibro e incolla le 12 regole nel tuo CLAUDE.md stasera. Ripubblica se ti ha risparmiato una settimana di errori di Claude.

Telegram per consigli quotidiani sull'ottimizzazione di Claude:

*https://t.me/+_ZWrQN7GuDA3ZDEy*