token-discipline per Claude Code: benchmark onesto

Passiamo le giornate a misurare le skill Claude di altri, e nella telemetria continuava a spuntare lo stesso schema: le sessioni che diventavano costose non lo diventavano perché Claude scriveva risposte lunghe. Diventavano costose per quello che Claude leggeva. File interi aperti per trovare una singola funzione. File riletti subito dopo una modifica riuscita, "solo per controllare". Un JSON da 16.000 record caricato in contesto come se fosse un post di un blog.

Così abbiamo creato una skill che attacca proprio quel lato della bolletta, l'abbiamo pubblicata con licenza MIT e abbiamo fatto quello che chiediamo a ogni skill che recensiamo: l'abbiamo confrontata con un baseline attraverso run controllati e abbiamo pubblicato i numeri — compresi quelli che non la fanno bella figura.

La skill si chiama token-discipline. È gratuita: github.com/Skillproofdev/token-discipline.

Il vuoto in tutte le skill sui token che abbiamo analizzato

Prima di scrivere una riga, abbiamo analizzato otto skill e protocolli pubblicati per il risparmio di token — dal ruleset sulla verbosità dell'output con 5.800 star che domina la nicchia, alle skill "di emergenza" che scattano al 40% del context, fino a protocolli che dichiarano risparmi del 76–93% senza alcun meccanismo dichiarato e senza telemetria reperibile.

Quasi tutte condividono lo stesso punto cieco: ottimizzano l'output. Eliminano il preambolo, accorciano le risposte, smettono di ripetere il piano. È un risparmio reale, ma è la metà minore della bolletta. Nelle sessioni agentiche — Claude Code che lavora davvero dentro un repository — a dominare è l'input: ogni file letto, ogni risultato di ricerca, ogni output di un tool finisce nel contesto e viene rimandato a ogni richiesta successiva.

Tre tecniche lato input non comparivano, come regole vincolanti, in nessuna delle otto:

1. Cerca prima di leggere. Individua prima con grep/glob, poi leggi solo la porzione che corrisponde. Non aprire mai un file intero per trovare qualcosa.

2. Raggruppa le chiamate ai tool indipendenti. Se tre letture non dipendono l'una dall'altra, vanno in un solo messaggio. Ogni turno in più ripaga token di ragionamento e narrazione tra una chiamata e l'altra.

3. Fidati dello stato che hai già. Dopo una tua modifica riuscita, non rileggere il file per controllare — il tool di modifica segnala l'errore in modo chiaro quando fallisce. Le riletture servono per cambiamenti esterni, non per i tuoi.

Queste tre sono diventate il cuore della skill. Intorno ci sono altre sei regole: leggere porzioni invece di file interi, interrogare JSON/log grandi con python o jq invece di aprirli, riassumere-e-poi-scartare gli output lunghi, delegare le esplorazioni ampie a subagent, mantenere il contesto cache-friendly (prefisso stabile intatto — il blog di engineering di Anthropic definisce il prompt caching il singolo fattore di costo a maggiore leva), e sì, anche l'output sintetico. Nove regole, ognuna scritta come regola vincolante con un'alternativa dichiarata, così seguirla non costa mai in termini di correttezza.

Come abbiamo fatto il benchmark

Stesso protocollo della nostra serie Skill Bench: stesso modello, stesso prompt, una sola variabile. Ogni task è stato eseguito due volte — un agente Claude Sonnet senza skill, e uno che ha letto prima SKILL.md e a cui è stato detto di seguirlo alla lettera. I totali dell'agente con la skill includono il costo di lettura della skill stessa. Il banco di prova era il nostro stesso codebase: un sito Astro con circa 9.000 righe di template più un dataset JSON da 16.682 record — abbastanza grande perché una lettura indisciplinata faccia davvero male.

Cinque coppie di task, scelte per coprire lo spettro dal banale al davvero multi-step:

Task	Baseline	Con la skill	Δ
Q&A sul codebase — 8 domande su più sottosistemi	88.419	71.636	−19,0%
Modifica multi-file — 4 cambi coordinati	68.219	54.637	−19,9%
Trace del codice — one-shot	53.986	52.850	−2,1%
Sweep di audit — one-shot	44.691	44.705	+0,0%
Digest di un JSON grande — one-shot	42.726	45.164	+5,7%

Cosa dicono davvero i numeri

Sul lavoro reale multi-step, la skill fa risparmiare circa il 20%. Il Q&A da otto domande sul codebase è la cosa più vicina a una normale sessione di lavoro — tracciare il flusso di autenticazione, spiegare il webhook, trovare la logica di ordinamento. L'agente baseline ha risposto correttamente, ma lungo il percorso ha letto in modo generoso e verificato in modo ridondante. L'agente disciplinato ha risposto alle stesse domande, con la stessa precisione (abbiamo controllato ogni riferimento file:line di entrambi), con 16.783 token in meno.

La modifica multi-file è il risultato più interessante. Quattro cambi coordinati su quattro file. L'agente baseline ha finito e poi — citando il suo stesso report — ha "verificato rileggendo le regioni modificate". Questa sola abitudine vale un quinto della bolletta. L'agente con la skill ha applicato gli stessi quattro cambi, ha saltato le riletture di rito e ha dichiarato fatto. Abbiamo confrontato entrambi i working tree con un diff: le modifiche erano equivalenti e corrette in entrambi i casi. Non si è perso nulla fidandosi del tool nel segnalare l'errore in caso di fallimento, perché è esattamente quello che i tool fanno.

Sui one-shot banali, è un pareggio — e lo pubblichiamo comunque. Il task di digest del JSON è costato in realtà il 5,7% in più con la skill. Due motivi, entrambi istruttivi. Primo, la skill in sé costa circa 1.400 token da leggere, e un task che si chiude in due chiamate ai tool non lascia spazio per ammortizzare quel costo. Secondo, un modello di ultima generazione si comporta già bene sui task facili: l'agente baseline ha dato una sola occhiata a un JSON da 16.682 record e ha scelto python invece di aprirlo. Nessuna skill necessaria. La disciplina paga dove l'indisciplina è possibile — sessioni lunghe, tanti file, contesto che si accumula — non dove non c'è nulla da sprecare.

Se le tue sessioni sono per lo più one-liner, la skill porta già la propria risposta: un blocco distillato da 60 token da incollare in CLAUDE.md invece di installare la skill intera. Sempre attivo, costa quanto questa frase, e una sola lettura di file intero evitata lo ripaga molte volte. (Abbiamo costruito un calcolatore proprio per questa tassa always-on — la matematica sulle trigger description vale anche per i blocchi di regole.)

Le nove regole, in breve

Il SKILL.md completo è di circa 1.400 token ed è leggibile in una sola schermata; ecco la struttura:

1. Cerca prima di leggere. Prima grep; poi leggi il risultato ±30 righe. Leggere più di ~200 righe richiede un motivo esprimibile in una frase.
2. Leggi la porzione, non il file. Offset+limit per tutto ciò che è lungo; python/jq per tutto ciò che è strutturato. Un JSON grande è un database, non un documento.
3. Raggruppa le chiamate ai tool indipendenti. Un messaggio, più chiamate, ogni volta che gli output non alimentano gli input successivi.
4. Fidati dello stato che hai già. Niente riletture di verifica dopo le tue modifiche; niente ricerche ripetute i cui risultati sono già nel contesto.
5. Non ricitare il codice. Fai riferimento a file:line. Incolla solo ciò che l'umano deve vedere per decidere.
6. Riassumi, poi scarta. Dopo un output lungo di un tool, tieni i 2–5 fatti chiave, non richiedere mai di nuovo il log.
7. Delega le esplorazioni pesanti. Gli sweep ampi vanno a un subagent; le letture pesanti muoiono nel suo contesto, non nel tuo.
8. Mantieni il contesto cache-friendly. Prefisso stabile intatto; aggiungi, non riscrivere; tieni d'occhio il TTL della cache.
9. Disciplina dell'output. Risposta prima di tutto, niente preamboli, niente saggi sui diff.

Più un checkpoint di auto-audit (tre domande prima di qualsiasi rilettura importante) e una lista esplicita di cose da non fare, perché una skill sui token che fa saltare a un agente una verifica necessaria non ti fa risparmiare niente — sta solo rimandando il lavoro extra. Se una vera caccia al bug richiede il file intero, la regola dice di leggerlo, con il motivo dichiarato.

Dove si colloca nel quadro più ampio dei costi

Regole come queste sono la metà variabile della tua bolletta. La metà fissa — il preambolo da 30.000 token di server MCP, i file CLAUDE.md gonfiati e le descrizioni delle skill sempre attive che vengono rimandate letteralmente a ogni richiesta — è un problema diverso con soluzioni diverse, e di solito è il guadagno maggiore per chi usa Claude Code in modo intensivo. Abbiamo scritto quell'audit in Come ridurre i costi in token di Claude Code; i due articoli sono complementari: sistema i costi fissi una volta, poi lascia che token-discipline mantenga piatti i costi variabili per tutta la sessione.

E se ti stai chiedendo se le skill in generale facciano risparmiare token: la nostra serie Skill Bench ha misurato quattro skill popolari e ha scoperto che perlopiù non lo fanno — costano token extra e comprano invece qualità e disciplina. token-discipline è stata costruita apposta per essere l'eccezione, e anche così, si ripaga solo sul lavoro multi-step. Questo è il confine onesto, e preferiamo tracciarlo noi piuttosto che farvelo scoprire sulla bolletta.

Installazione

git clone https://github.com/Skillproofdev/token-discipline ~/.claude/skills/token-discipline

Riavvia Claude Code. Si attiva su "reduce token usage", "work token-efficiently", lamentele sul limite di contesto e domande sui costi — oppure applicala a tutta la sessione tramite il blocco CLAUDE.md incluso.

FAQ

Sostituisce le skill sulla verbosità dell'output? No — ne include il nucleo (Regola 9) e aggiunge il lato input che quelle skill non coprono. Se usi già un ruleset per l'output sintetico, token-discipline ci si sovrappone su una regola su nove.

Renderà Claude più sciatto? Il benchmark dice di no: la modifica multi-file è risultata equivalente e corretta su entrambi i lati, e la lista delle cose da non fare della skill protegge esplicitamente le verifiche davvero necessarie. Le regole sostituiscono le letture di rito, non quelle necessarie.

Perché la skill in sé è così corta? Perché una skill per risparmiare token che costa migliaia di token a sessione solo per essere caricata sarebbe un'auto-parodia. Il SKILL.md è di circa 1.400 token caricati on demand; il blocco always-on per CLAUDE.md è di circa 60.

Ho un abbonamento Pro/Max, non uso l'API. Fa differenza? Sì, nella valuta dei limiti: gli stessi token che vengono fatturati agli utenti API consumano i tuoi tetti di utilizzo. Il 20% di token in meno nelle sessioni di lavoro significa proporzionalmente più lavoro prima di toccare il tetto.

Il benchmark è stato selezionato ad arte? I cinque task sono stati definiti prima di eseguire una qualsiasi delle due varianti, e abbiamo pubblicato i due risultati in cui la skill ha perso. La telemetria grezza — conteggio dei token e delle chiamate ai tool per ogni run — è nel README del repo.