Ecco la traduzione in italiano del testo fornito, seguendo tutte le linee guida specificate.
karpathy si è lamentato di claude su X. forrest chang ha trasformato la lamentela in quattro regole e un repository GitHub. Il repository ha raggiunto 120.000 stelle in poche settimane. La maggior parte degli sviluppatori che leggono questo articolo usa ancora solo quelle quattro regole. Il problema è che sono state scritte a gennaio. Ora siamo a metà del 2026 e l'ecosistema di Claude Code è cambiato.
Questo articolo ti fornisce il CLAUDE.md completo con 12 regole, il motivo per cui ogni regola esiste, quale fallimento previene e cosa il template originale sbaglia silenziosamente. Incollalo alla fine.
Cos'è CLAUDE.md e Perché la Maggior Parte delle Persone lo Sbaglia
CLAUDE.md è un file che inserisci nella root del tuo repository. Claude Code lo legge prima di ogni sessione. Non è un prompt. Non è una lista di preferenze. È un sistema operativo per come Claude si comporta nel tuo codebase.
La maggior parte degli sviluppatori fa una di tre cose sbagliate. Riempiono il file con ogni preferenza che hanno mai avuto fino a farlo diventare più di 4.000 token, punto in cui la conformità scende al 30% perché le regole importanti vengono sepolte. Lo saltano del tutto e ripetono il prompt a ogni sessione, sprecando cinque volte i token e producendo zero consistenza. Incollano un template una volta, lo dimenticano e lo guardano rompersi silenziosamente nel corso delle settimane mentre il loro codebase cambia.
I documenti ufficiali di Anthropic sono espliciti: CLAUDE.md è consultivo. Claude lo segue circa l'80% delle volte sotto le 200 righe. Oltre le 200 righe, la conformità cala bruscamente. Il limite per file CLAUDE.md utili è breve, preciso e applicato tramite regole dirette, non suggerimenti.
Le 4 Regole Originali: Inizia da Qui se Non Hai Niente
Andrej Karpathy, ex direttore dell'AI di Tesla e co-fondatore di OpenAI, ha pubblicato un thread a gennaio 2026 dopo settimane di lavoro intensivo con Claude Code. Non un framework. Una lamentela. Tre modalità di fallimento che continuava a incontrare: Claude assume silenziosamente invece di chiedere, Claude costruisce in eccesso invece di risolvere il minimo, e Claude tocca codice che non gli è mai stato chiesto di toccare.
Forrest Chang ha letto il thread e lo ha trascritto come regole. Un file, 65 righe, su GitHub il giorno dopo. Ecco le quattro:
Regola 1 - Pensa Prima di Codificare
Dichiara le tue ipotesi prima di scrivere codice. Evidenzia i compromessi. Chiedi prima di indovinare. Opponiti quando esiste un approccio più semplice. Non costruire mai su un'ipotesi non verificata.
Regola 2 - Semplicità Prima di Tutto
Scrivi il codice minimo che risolve il problema. Nessuna funzionalità speculativa. Nessuna astrazione per codice usato una volta. Se un ingegnere senior lo definirebbe troppo complesso, semplificalo.
Regola 3 - Modifiche Chirurgiche
Tocca solo ciò che richiede l'attività. Non migliorare codice, commenti o formattazione adiacenti. Non rifattorizzare ciò che non è rotto. Abbina esattamente lo stile esistente.
Regola 4 - Esecuzione Guidata dagli Obiettivi
Definisci come appare il successo prima di iniziare. Ripeti finché il successo non è verificato. Non elencare passi da far seguire a Claude. Digli come appare il "fatto" e lascia che trovi il percorso.
Queste quattro regole chiudono circa il 40% delle modalità di fallimento nelle sessioni non supervisionate di Claude Code. Il restante 60% risiede in lacune che il template originale non affronta, perché quei problemi non esistevano completamente quando Karpathy ha pubblicato il suo thread.
Perché il Template Originale Necessita di un'Estensione
Le quattro regole di Karpathy sono state create per risolvere una sessione di scrittura codice con un singolo agente. L'ecosistema di Claude Code nel 2026 esegue configurazioni multi-agente, hook, librerie di skill e flussi di lavoro multi-step che si estendono su più sessioni. Il template originale non ha nulla da dire su tutto ciò.
Quattro lacune specifiche appaiono nelle regole originali. Primo, conflitti tra agenti: due agenti che modificano gli stessi file senza regole di proprietà, calpestandosi silenziosamente le modifiche a vicenda. Secondo, cascate di hook: hook che si attivano a ogni chiamata di strumento, trasformando una richiesta di 200 token in 8.000 token senza un budget per fermarla. Terzo, conflitti di caricamento delle skill: skill multiple con descrizioni simili confondono il dispatcher e caricano quella sbagliata. Quarto, interruzioni di sessione multi-step: un refactoring in 6 passi fallisce al passo 4, ma i passi 5 e 6 vengono eseguiti comunque e si basano su uno stato corrotto.
Le quattro regole originali non sono sbagliate. Sono incomplete. Le 8 regole aggiuntive qui sotto colmano queste lacune specifiche.
Le 8 Nuove Regole: Cosa Chiude Ciascuna
Regola 5 - Non Usare il Modello per Lavori Non Linguistici
Le decisioni deterministiche appartengono al codice deterministico. Logica di ripetizione, soglie di instradamento, regole di escalation, ramificazione basata sullo stato: nessuna di queste dovrebbe essere una chiamata LLM. Il modello decide in modo diverso ogni settimana in base a ciò che è nella finestra di contesto. Quello che sembra un comportamento coerente è in realtà una varianza che non è ancora emersa.
L'incidente specifico: una chiamata LLM per "decidere se ripetere su 503" ha funzionato per due settimane, poi ha iniziato a produrre comportamenti casuali perché il modello ha iniziato a leggere il corpo della richiesta come contesto per la decisione di ripetizione. La politica è diventata casuale perché l'input effettivo era casuale.
Aggiungi questo al tuo CLAUDE.md:
Instradamento, logica di ripetizione, ramificazione basata sullo stato e decisioni di soglia appartengono al codice, non alle chiamate del modello. Se l'output di una decisione è binario o segue una regola fissa, scrivi la regola nel codice.
Regola 6 - Budget di Token Rigidi, Nessuna Eccezione
Ogni ciclo di agente ha la possibilità di andare in spirale. Claude non fermerà da solo una sessione di debug di 90 minuti. Continuerà a iterare perché l'iterazione è ciò che gli è stato detto di fare. I budget di token sono l'unico meccanismo che impone un arresto forzato.
L'incidente specifico: una sessione di debug che ciclava sullo stesso messaggio di errore di 8KB per 90 minuti. Alla fine, Claude stava suggerendo correzioni che aveva già provato e abbandonato due ore prima. Il contesto era così pieno che aveva perso traccia del proprio ragionamento.
Aggiungi questo:
Ogni sessione di agente ha un budget di token rigido. Se il budget viene raggiunto senza una soluzione verificata, fermati, riassumi i risultati in un file ed esci. Non continuare oltre il budget.
Regola 7 - Un Agente, Una Directory
Quando due agenti toccano la stessa directory contemporaneamente, si ottiene una corruzione silenziosa dello stato. Un agente scrive un file mentre un altro lo sta leggendo. Il risultato sono dati che nessuno dei due agenti si aspetta e nessuno nota.
Usa i git worktree. Esegui git worktree add ../agent-2-branch feature-branch prima di generare un secondo agente. Ogni agente ottiene la propria directory di lavoro isolata puntata al proprio branch. Gli agenti non condividono mai un file system.
Aggiungi questo:
Gli agenti che lavorano in parallelo operano in git worktree separati. Nessun agente tocca la stessa directory contemporaneamente. Ogni agente possiede il proprio branch.
Regola 8 - Scrivi File di Checkpoint per Lavori Multi-Step
Qualsiasi attività più lunga di tre passi necessita di un file di checkpoint. Claude scrive il file dopo ogni passo con ciò che è stato completato, ciò che è stato trovato e cosa viene dopo. Se la sessione muore o si interrompe al passo 4, la sessione successiva legge il checkpoint e continua dal passo 4. Senza il checkpoint, ogni ripartenza torna al passo 1.
Crea un file chiamato PROGRESS.md nella tua directory di lavoro prima di iniziare qualsiasi attività multi-step. Dì a Claude nel tuo CLAUDE.md:
Per attività con più di tre passi, scrivi un file PROGRESS.md dopo ogni passo. Includi: cosa è stato fatto, cosa è stato trovato, cosa viene dopo e cosa è bloccato. Se una sessione termina prima del completamento, la sessione successiva legge prima PROGRESS.md e continua da dove si era fermata.
Regola 9 - Fallisci Rumorosamente o Non Fallire Affatto
Claude ha un forte pregiudizio verso l'apparire di successo. Supererà un test che in realtà non testa ciò che ti interessava. Completerà una migrazione saltando silenziosamente i file che hanno dato errore. Riporterà "fatto" su un'attività completata all'80%.
La regola: se i criteri di successo non possono essere verificati, l'attività non è finita. Se un passo fallisce, fermati e segnala il fallimento con dettagli prima di continuare. Non nascondere gli errori.
Aggiungi questo:
Non continuare mai oltre un passo che è fallito. Se un test passa ma non copre il comportamento effettivo, dillo. Se una migrazione salta dei file, elenca i file saltati e fermati. Successo significa verificabile, non riportato.
Regola 10 - Le Descrizioni delle Skill Devono Essere Uniche
Le skill vengono caricate tramite corrispondenza della descrizione. Se due skill hanno descrizioni sovrapposte, il dispatcher ne sceglie una arbitrariamente. La skill sbagliata viene caricata, l'attività viene eseguita con istruzioni errate e non vedi mai un errore perché non viene generato alcun errore.
Nomina il lavoro di ogni skill con un linguaggio che non può corrispondere a nessun'altra skill. "Aiuto query database" e "Aiuto migrazione database" entreranno in conflitto. "Esegui query SQL di sola lettura sul database di produzione" e "Esegui e verifica script di migrazione dello schema con rollback" non lo faranno.
Aggiungi questo:
Ogni descrizione di skill deve identificare univocamente il suo lavoro. Nessuna skill dovrebbe avere descrizioni che potrebbero applicarsi alla stessa attività. Se due skill suonano simili, una di esse necessita di essere rinominata prima di essere distribuita.
Regola 11 - Separa il Ricercatore dallo Scrittore
L'inquinamento del contesto è reale. Quando Claude fa ricerca e scrittura nella stessa sessione, il rumore della ricerca degrada la scrittura. Tira dentro divagazioni, attenua conclusioni che non ha bisogno di attenuare e perde la linea argomentativa pulita che avrebbe avuto iniziando da zero.
Genera un sotto-agente di ricerca per qualsiasi attività che richieda la lettura di più di cinque file o l'interrogazione di più di due fonti. Ottieni un report strutturato. Inizia una sessione pulita per la scrittura o l'implementazione con solo il report nel contesto.
Aggiungi questo:
Ricerca e implementazione sono sessioni separate. Un sotto-agente ricercatore legge file, esegue query e restituisce un riepilogo strutturato. La sessione di implementazione inizia da zero con quel riepilogo come unico input. Non unire mai ricerca e scrittura in una singola sessione.
Regola 12 - Anche gli Hook Hanno Bisogno di un Budget
Gli hook si attivano a ogni chiamata di strumento. Un hook che esegue un linter, un formattatore, uno scrittore di log e una scansione di sicurezza su ogni scrittura di file sta eseguendo quattro processi per chiamata di strumento. In una sessione con 200 chiamate di strumento, sono 800 processi in esecuzione in background, la maggior parte ridondanti, tutti che consumano token.
Ogni hook che aggiungi necessita di una condizione di ambito: esegui solo su scritture di file in directory specifiche, esegui solo quando viene toccata un'estensione di file specifica, esegui solo dopo la fine della sessione piuttosto che dopo ogni chiamata di strumento. Gli hook senza condizioni di ambito degraderanno invisibilmente le prestazioni della sessione.
Aggiungi questo:
Ogni hook ha una condizione di ambito esplicita. Nessun hook viene eseguito incondizionatamente su ogni chiamata di strumento. Raggruppa la registrazione alla fine della sessione. Esegui i linter solo sui file modificati. Esegui i controlli di sicurezza solo sui file al di fuori della directory di test.
Il CLAUDE.md Completo con 12 Regole - Incolla Questo
Copia questo file nella root del tuo repository. Compila le sezioni contrassegnate da parentesi. L'intero file rimane sotto le 100 righe, il che mantiene la conformità sopra l'80%.
CLAUDE.md
Progetto
[una frase: cosa fa questo codebase e quale stack tecnologico usa]
Regole Comportamentali
Pensa Prima di Codificare
Dichiara le tue ipotesi prima di scrivere codice. Evidenzia i compromessi. Chiedi prima di indovinare su qualsiasi cosa che influenzi l'architettura o i dati. Opponiti quando esiste un approccio più semplice.
Semplicità Prima di Tutto
Scrivi il codice minimo che risolve il problema. Nessuna funzionalità speculativa. Nessuna astrazione per codice monouso. Se un ingegnere senior lo definirebbe troppo complesso, semplifica.
Modifiche Chirurgiche
Tocca solo ciò che richiede l'attività. Non migliorare codice, formattazione, commenti o naming adiacenti che non facevano parte della richiesta. Abbina esattamente lo stile di codice esistente.
Esecuzione Guidata dagli Obiettivi
Definisci come appare il successo prima di iniziare. Ripeti finché quella definizione non è soddisfatta e verificata. Non chiedere istruzioni passo-passo. Trova il percorso.
Nessuna Chiamata al Modello per Decisioni Deterministice
Instradamento, logica di ripetizione, ramificazione basata sullo stato e decisioni di soglia appartengono al codice, non alle chiamate LLM. Se una regola può essere scritta, scrivila.
Budget di Token Rigidi
Ogni sessione ha un limite di token rigido: [imposta il tuo numero, es., 50.000 token]. Se il limite viene raggiunto senza una soluzione verificata, scrivi i risultati in un file e fermati. Non continuare oltre il budget.
Un Agente, Una Directory
Gli agenti che lavorano in parallelo operano in git worktree separati. Nessun agente condivide una directory. Se hai bisogno di un secondo agente, esegui: git worktree add ../agent-2 [nome-branch]
Checkpoint per Lavori Multi-Step
Per qualsiasi attività più lunga di tre passi, crea PROGRESS.md nella directory di lavoro. Scrivi dopo ogni passo: cosa è stato fatto, cosa è stato trovato, cosa viene dopo, cosa è bloccato. Se la sessione termina prima del completamento, la sessione successiva legge prima PROGRESS.md.
Fallisci Rumorosamente
Se un passo fallisce, fermati e segnala il fallimento con dettagli prima di continuare. Se un test passa ma non copre il comportamento effettivo, dillo. Successo significa verificabile, non riportato.
Descrizioni delle Skill Uniche
Ogni skill copre esattamente un lavoro. La sua descrizione non può applicarsi a nessun'altra skill nel progetto. Se due skill si sovrappongono nella descrizione, rinomina prima di distribuire.
Ricerca e Implementazione Sono Sessioni Separate
Usa un sotto-agente per qualsiasi attività che richieda la lettura di più di cinque file o l'interrogazione di più di due fonti. Ottieni un report strutturato. Inizia una sessione pulita per l'implementazione con solo quel report come input.
Solo Hook con Ambito Definito
Ogni hook ha una condizione esplicita: estensione del file, percorso della directory o evento di sessione. Nessun hook viene eseguito incondizionatamente su ogni chiamata di strumento. Raggruppa la registrazione alla fine della sessione dove possibile.
Cosa Non Toccare
[elenca le directory o i file che Claude non dovrebbe mai modificare: es., /secrets, /migrations/archive, /prod-config]
Criterio di Successo Predefinito
In caso di dubbio sul fatto che un'attività sia finita: il test passa, la build ha successo e l'output è verificabile da qualcosa di diverso dal giudizio di Claude? Se la risposta è no a una di queste, non è finita.
Quattro Punti in Cui il Template Originale Si Rompe Silenziosamente
Anche solo con le quattro regole originali, ci sono quattro condizioni specifiche in cui il template produce il comportamento sbagliato e non te lo dice.
Primo: sessioni lunghe con contesto accumulato. La regola di esecuzione guidata dagli obiettivi di Karpathy dice a Claude di ripetere finché non è verificato. In una sessione lunga, "verificato" diventa nebuloso man mano che il contesto si riempie. Claude inizia a verificare rispetto a un modello degradato di ciò che avrebbe dovuto fare. La soluzione è la regola 6 (budget di token) che impone un arresto forzato.
Secondo: configurazioni multi-agente. La regola delle modifiche chirurgiche dice a ogni agente di toccare solo ciò che deve. Ma con due agenti e nessuna regola di proprietà della directory, "ciò che deve" si sovrappone. La regola 7 (un agente, una directory) è il pezzo mancante.
Terzo: skill parallele con lavori simili. Il template originale non ha nulla sulle skill. La regola 10 (descrizioni delle skill uniche) chiude la lacuna di ambiguità del dispatcher.
Quarto: sessioni che terminano a metà attività. L'esecuzione guidata dagli obiettivi presuppone che la sessione vada a termine. Non ha istruzioni su cosa fare se la sessione muore al passo 4 di 8. La regola 8 (file di checkpoint) fornisce alla sessione successiva un punto di partenza.
Nessuno di questi sono bug nelle regole originali. Sono lacune che le regole originali non sono state scritte per coprire.
Il Numero Che Spiega le Stelle su GitHub
120.000 sviluppatori hanno messo una stella a un file di testo di 65 righe. Nessun codice. Nessuna libreria. Nessun framework. Un file con quattro regole.
Il numero che lo spiega: 41% di tasso di errore in sessioni non supervisionate di Claude Code senza CLAUDE.md. 11% con le quattro regole originali. 3% con le dodici complete.
Una riduzione di 38 punti percentuali negli errori non è un miglioramento marginale. Per qualsiasi team che esegue Claude Code su lavoro di produzione reale, è la differenza tra un agente di cui ti puoi fidare per funzionare durante la notte e uno che devi tenere d'occhio.
Il file alla fine di questo articolo richiede cinque minuti per essere incollato e compilato. La prima sessione dopo averlo fatto sarà diversa. Non perché il modello è cambiato. Perché il modello finalmente sa come funziona il tuo mondo.
Segna questo articolo e incolla le 12 regole nel tuo CLAUDE.md stasera.
Ripubblica se lo hai trovato utile.
