Elimina il tuo CLAUDE.md, misurato: tabelle di ablation, checklist e fonti

TL;DR

• Su un repo reale con un CLAUDE.md di 177 righe, 3 skill e 1 hook, eliminare tutto ha rotto esattamente una regola, in una sola situazione: la regola i18n su un file appena creato. Tutte le altre convenzioni hanno retto perché il codice circostante le insegnava già.
• Il file è costato dal 4 al 14% dei token letti nei task in cui l'output era identico, circa un dollaro su dieci. Il risparmio del 32% in evidenza è dominato dall'unico task in cui il file ha spinto il modello a lavorare di più.
• Skill e hook non costano nulla di misurabile: le skill si caricano solo quando vengono invocate e nessuna lo è stata, l'hook inietta una sola frase.
• La panoramica dell'architettura di 82 righe non ha portato nulla sulla domanda di architettura: sei risposte, tutte corrette, con o senza il file.
• "Delete", nelle parole di Anthropic, significa fare ablation e passare alla progressive disclosure, non cancellare. Tieni le regole che il codice non può insegnare, sposta il resto in file di regole e skill, e trasforma le regole non negoziabili in hook.
• Due ripetizioni per configurazione sono un minimo, non un verdetto: i delta per task sotto il 15% rientrano nel rumore tra una run e l'altra.

Cosa dicono le misure

Il talk a cui tutti reagiscono dice due cose, e la seconda viene persa. Boris Cherny conferma sul palco che Claude Code ha eliminato l'80% del suo system prompt, e descrive il metodo: eliminare l'intero system prompt, poi reintrodurlo riga per riga per misurare l'impatto di ciascuna riga s2. Il passaggio sul "every 6 months" si trova da 00:06:58 a 00:07:05, e la formula è "really do recommend", non "strongly recommend" s1. Due frasi che gli vengono attribuite spesso non sono nel talk: "context, goals and a definition of done" (la frase reale più vicina, a 15:22, è "describe the task, the guardrails, the exit criteria") e "64 agents". Lui dice "eleven days" e, alla domanda sul numero di agenti, "I'm not sure" s2. La cifra 64 appartiene al post sulla riscrittura di Bun: "64 Claudes running for 11 days", circa $165,000 a prezzi API, 9 miliardi di token di input non in cache, 690 milioni di token di output e 72 miliardi di letture di token di input in cache s14.

Il meccanismo che rende misurabile tutto questo è il caricamento. CLAUDE.md e i file di regole vengono iniettati a ogni turno; le skill si caricano solo quando vengono invocate. La documentazione sulla memoria contiene anche l'indicazione di dimensione che tutti parafrasano: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." s4. La versione scritta del consiglio di Anthropic presenta il CLAUDE.md come repository centrale come un mito e rimanda alla progressive disclosure e all'auto-memory s3.

L'unico studio controllato prima del nostro è il paper dell'ETH su AGENTS.md: 138 issue su 12 repo, e "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average". I file scritti dagli sviluppatori e committati superano in media del 7% quelli generati da un LLM, e le istruzioni che nominano strumenti specifici aiutano s5.

Due dati su cosa contengono i file e come vengono letti. Su 28,721 repository e 165,063 file, il file di istruzioni mediano contiene 50 elementi di contenuto, di cui 12 sono vere direttive; l'autore la mette così: solo il 27% del file fa quello che pensi s8. In un esperimento controllato con due istruzioni in conflitto reale, spostare una singola regola dall'inizio alla fine del file cambia di circa 90 punti la frequenza con cui il modello la rispetta, da quasi mai a quasi sempre s9. Lo stesso editore traccia la linea che il nostro esperimento segue: l'ablation non è cancellazione, e gli hook sono enforcement, non scadono con un aggiornamento del modello s7.

Due prior informali coincidono con il nostro risultato. Un CLAUDE.md da 1,000 righe confrontato con una versione ridotta di ~20 righe sulle stesse issue GitHub e con lo stesso modello: l'architettura ha retto, le regole della casa si sono rotte s6. Un commentatore che ha spostato tutto in progressive disclosure riporta un contesto caricato automaticamente sceso da ~35k a ~4.5k token per sessione, senza alcuna conoscenza eliminata s11. Per valutare le ablation delle skill esiste uno strumento: --ablate di caliper copre skill e server MCP e il suo compare riporta tasso di successo, token e tempo di esecuzione; lo scambio del CLAUDE.md resta manuale s16.

Misure

Protocollo: un repo privato Expo / React Native (1,021 file tracciati), CLAUDE.md di 177 righe, 7,243 caratteri, circa 1,800 token, 3 skill, 4 slash command, 1 hook PreToolUse. Modello fissato a claude-opus-5 per ogni run, Claude Code 2.1.278, claude -p headless, --max-turns 40, cartella di configurazione utente vuota, nessun MCP, clone pulito ripristinato prima di ogni run. Cinque task di tutti i giorni (nuovo componente, modifica di un componente, refactoring di helper condivisi, persistenza di un campo dello store, spiegazione di un flusso di dati), ablation un elemento alla volta. 44 run, $38.97 a prezzi API, 92 minuti di tempo agente. Valutazione: le regole della casa del repo sulle righe aggiunte, tsc --noEmit, eslint, risposte valutate a mano.

Qualità, cosa si è rotto:

Costo per run, media sulle run della config (token = letture dalla cache, il contesto riletto a ogni turno):

Per task, da A a B (media di 2 run ciascuna):

Lettura delle tabelle. Senza il CLAUDE.md, 3 run su 4 del nuovo componente hanno scritto il titolo come semplice stringa; con il file, 4 su 4 hanno creato il .content.ts con EN e FR. Nel task di modifica ogni config, anche la E, ha messo la nuova stringa in un .content.ts: i file vicini portavano la convenzione. Tutto il resto ha retto in tutte le 44 run: 0 import relativi, type e non interface in sei modifiche del file dei tipi, design token in ogni diff, 0 colori esadecimali, nessun barrel file. Un'istruzione che nessuno poteva seguire: il file dice di importare theme da @design-tokens, un alias che non esiste in tsconfig.json; nessuna run, in nessuna config, lo ha usato, 1,800 token letti per niente a ogni sessione. Il risparmio su T1 è la run più economica che fa meno lavoro. La varianza tra run è più grande della maggior parte degli effetti delle config: T1 con la config completa è costato $2.11 poi $1.33. Un controllo con il grafo di codice da 333 MB presente è finito sui numeri della config completa ($1.59 contro $1.72 su T1, $0.38 contro $0.34 su T5): il blocco del grafo e l'hook non hanno cambiato nulla di misurabile.

Da fare lunedì

• Conta il tuo CLAUDE.md: righe, caratteri e numero di righe che sono vere direttive (Always, Never, Use, Prefer). Il resto è contesto che il modello rilegge a ogni turno.
• Scegli una convenzione per sezione e verifica se un file vicino la mostra già. Se tre file della cartella seguono la regola, la riga è candidata alla cancellazione.
• Trova la regola che il codice non può insegnare su un file nuovo (i18n, telemetria, header di licenza, un passaggio di registrazione obbligatorio). Tienila, scrivila in una riga e mettila vicino all'inizio.
• Prova ogni percorso di import e ogni comando che il tuo file nomina. Un alias morto o uno script rinominato è un'istruzione che nessuno può seguire.
• Sposta le lunghe panoramiche di architettura e le guide di setup in un file di regole o in una skill che si carica su richiesta, poi confronta il contesto caricato automaticamente prima e dopo.
• Trasforma le tue due o tre regole non negoziabili in un hook o in una regola di lint. L'enforcement non dipende dal fatto che il modello legga un paragrafo.
• Esegui i tuoi due task più comuni due volte con il file e due volte senza, su un modello fissato, e leggi token e diff. Due ripetizioni dicono dove guardare, non cosa concludere.

Per approfondire

• Il talk stesso, per il metodo più che per la battuta: eliminare, poi reintrodurre riga per riga s2.
• Tutti i risultati del paper, incluso il dato che i file scritti dagli sviluppatori battono quelli generati del 7% e che nominare gli strumenti aiuta s5.
• La posizione della regola come variabile: lo scarto di ~90 punti e come il modello risolve in silenzio le istruzioni in conflitto s9.
• L'anatomia di un file di istruzioni su 30k repo: 50 elementi, 12 direttive, e cosa sono gli altri 38 s8.
• La guida di HumanLayer per scrivere un buon CLAUDE.md e il thread che la contesta s10.
• Il thread "MUST use agent, ignored 80% of the time": un caso a favore degli hook dove la prosa fallisce s12.
• Il thread "Claude Code now ignores everything", utile per separare la deriva del modello dai conflitti tra istruzioni s13.
• caliper, per valutare le ablation di skill e MCP con tasso di successo, token e tempo di esecuzione s16.

Fonti

• Boris Cherny: We Cut 80% of Claude Code's Prompt, Y Combinator. Perché leggerla: la citazione primaria, con la precisazione che le clip tagliano.
• Transcript of the talk, Y Combinator. Perché leggerla: testo ricercabile per verificare cosa è stato detto e cosa no.
• The new rules of context engineering for Claude 5 generation models, Anthropic. Perché leggerla: la versione scritta del consiglio, progressive disclosure invece di un file centrale.
• Memory docs: CLAUDE.md and rules files, Claude Code docs. Perché leggerla: cosa si carica a ogni turno, cosa su richiesta, e l'indicazione delle 200 righe.
• Evaluating AGENTS.md, arXiv. Perché leggerla: l'unica misura controllata dei file di contesto prima di questa.
• Should you delete your CLAUDE.md every 6 months?, Modern Creator. Perché leggerla: un confronto informale tra 1,000 e 20 righe il cui schema di rotture coincide con il nostro.
• Opus 5: delete your CLAUDE.md?, reporails. Perché leggerla: ablation contro cancellazione, e perché gli hook sopravvivono a un aggiornamento del modello.
• The State of AI Instruction Quality: 30k-repo analysis, reporails. Perché leggerla: cosa contiene davvero un file di istruzioni mediano.
• Opus 5: the cost of instruction conflicts, reporails. Perché leggerla: un esperimento controllato sulla posizione delle regole.
• Writing a good CLAUDE.md, HN thread, Hacker News. Perché leggerla: sviluppatori che discutono di cosa appartiene al file.
• Anthropic says keep CLAUDE.md under 200 lines, r/ClaudeCode. Perché leggerla: il commento sul prima e dopo da ~35k a ~4.5k.
• CLAUDE.md says MUST use agent, Claude ignores it, r/ClaudeCode. Perché leggerla: un caso concreto in cui le istruzioni in prosa falliscono.
• Claude Code now ignores everything, r/ClaudeCode. Perché leggerla: le segnalazioni dietro la sensazione che "qualcosa sia cambiato".
• Rewriting Bun in Rust, Simon Willison. Perché leggerla: da dove vengono le cifre di 64 agenti e $165,000.
• caliper, GitHub. Perché leggerla: un harness di valutazione per le ablation di skill e MCP.

FAQ

Devo eliminare il mio CLAUDE.md?

Non alla cieca. Sul nostro repo l'unica perdita è stata una regola sui file nuovi; tutto ciò che il codice già dimostrava ha retto senza il file. Fai ablation una sezione alla volta e tieni ciò che cambia l'output.

Perché il file ha fatto risparmiare il 32% di token se è costato solo dal 4 al 14%?

Perché il totale è dominato dal task del nuovo componente, dove il file ha spinto il modello a scrivere un secondo file in due lingue. La run più economica ha fatto meno lavoro. Nei task con output identico, il risparmio è stato dal 4 al 14%.

Skill e hook costano token a ogni turno?

Le skill si caricano solo quando vengono invocate, quindi una skill non invocata non costa nulla; l'hook inietta una sola frase. Eliminare entrambi non ha cambiato nessun numero nelle nostre run. I file di regole e il CLAUDE.md sono quelli riletti a ogni turno.

Bastano due run per configurazione?

No. Due ripetizioni localizzano l'effetto, non lo dimensionano. La nostra config completa è costata $2.11 poi $1.33 sullo stesso task, quindi i delta per task sotto il 15% rientrano nel rumore.