### Risposta Rapida: Come ridurre il consumo di token in Claude
Per ridurre l'uso dei token in Claude Code fino al 75%, applica quattro ottimizzazioni fondamentali: configura un file
.claudeignorerigoroso per escludere artefatti di build e file lock, sfrutta lo sconto del 90% in lettura del prompt caching di Anthropic tramite prefissi statici, isola i sotto-task con sub-agenti Scout per prevenire il Context Rot, e prediligiclaude-3-7-sonnetoclaude-3-5-haikuper l'esplorazione del codice prima di ricorrere a Opus.
1. Introduzione: Il consumo invisibile di token negli agenti da terminale
Gli agenti autonomi di programmazione da terminale come Claude Code di Anthropic hanno rivoluzionato i flussi di sviluppo software. A differenza del semplice completamento in-line negli IDE, Claude Code opera all'interno di un ciclo autonomo: analizza alberi di directory, legge file di migliaia di righe, esegue comandi nella shell, interpreta i registri del compilatore e applica patch mirate al codice sorgente.
Tuttavia, questa autonomia presenta un costo elevato sulle API. Senza una configurazione preventiva, una richiesta all'apparenza semplice come "Rifai il refactoring del middleware di autenticazione per supportare la rotazione dei JWT" può consumare da 1,5 a 3,5 milioni di token in una singola sessione. Questa inflazione di token deriva da quattro fattori determinanti:
- Accumulo e degrado del contesto (Context Rot): Ogni output di comandi bash, risultato di grep, traccia del compilatore e dump completo di file rimane bloccato nella finestra di contesto attiva dell'agente.
- Re-ingestione non memorizzata in cache: Modificare inavvertitamente i primi scambi della conversazione invalida la finestra di 5 minuti del prompt caching temporaneo di Anthropic.
- Scansione di artefatti ridondanti: Durante ricerche regex globali, Claude Code legge ripetutamente directory di compilazione (
dist/,target/,.next/), giganteschi file di blocco delle dipendenze (package-lock.json,pnpm-lock.yaml) e dump di database. - Sovradimensionamento del modello: Assegnare modelli di ragionamento di punta (
claude-3-opuso Sonnet con Thinking al massimo) a banali ricerche di file o consultazioni dell'albero delle cartelle.
Implementando vincoli architetturali precisi — una solida disciplina su .claudeignore, la meccanica del prompt caching, l'isolamento dei contesti tramite sub-agenti e la regolazione fine della CLI — i team di sviluppo riducono regolarmente il consumo quotidiano di token in Claude Code del 70% - 80%, migliorando contestualmente la percentuale di successo nei task.
2. Economia quantitativa: Tariffe dei token e architettura di caching
Per diagnosticare le perdite di token, esaminiamo le tariffe ufficiali delle API di Anthropic e i livelli di caching (parametri base 2026):
| Modello Claude | Input Base ($/1M) | Scrittura Cache ($/1M) | Lettura Cache ($/1M) | Output ($/1M) | SWE-bench Verified | Ruolo Ideale nel Terminale |
|---|---|---|---|---|---|---|
| Claude 3.5 / 3.7 Haiku | $0.80 | $1.00 | $0.08 | $4.00 | 41.2% | Ricerca di simboli, filtri regex, messaggi di commit |
| Claude 3.7 Sonnet (Standard) | $3.00 | $3.75 | $0.30 | $15.00 | 70.3% | Refactoring principale, modifiche multifile, test |
| Claude 3.7 Sonnet (Extended Thinking) | $3.00 (in) | $3.75 (write) | $0.30 | $15.00 (pensiero+out) | 72.8% | Bug architetturali complessi, race condition |
| Claude 3 Opus / Opus 4.6 | $15.00 | $18.75 | $1.50 | $75.00 | 74.1% | Audit di sicurezza critici, re-ingegnerizzazione di sistema |
Calcolo matematico per un taglio del 75% su costi e token
Prendiamo in esame una sessione standard di 15 turni per il refactoring di un endpoint REST in un repository TypeScript da 150.000 righe di codice:
[Sessione non ottimizzata]
Turno 1: Carica mappa repository + package-lock.json + schema (180.000 token)
Turni 2-5: Output di grep, log di build, lettura integrale di file (cumulativo 240.000 token/turno)
Percentuale di cache miss: 45% (invalidazione frequente dovuta a header/tool dinamici)
Totale token di input elaborati: 3.250.000
Costo effettivo (Sonnet): ~$9.75
[Sessione ottimizzata: .claudeignore + Prompt Cache + Sub-agenti]
Turno 1: Sintesi AST pulita (18.000 token) -> Salvata in cache al Turno 1
Turni 2-5: Diff incrementali, sub-agente Scout restituisce un report compresso (22.000 token/turno)
Percentuale di cache hit: 92% (lettura con tariffa scontata a $0.30/1M)
Totale token di input elaborati: 410.000 (riduzione fisica dei token dell'87.3%)
Costo effettivo (Sonnet): ~$0.82 (risparmio economico reale del 91.5%)3. Pilastro 1: Configurare .claudeignore per eliminare il contesto superfluo
L'intervento con il più alto ritorno sull'investimento in qualunque repository consiste nell'introdurre un file .claudeignore rigoroso e orientato alla produzione.
Sebbene Claude Code rispetti per impostazione predefinita le regole del file .gitignore, i normali .gitignore lasciano transitare molti file voluminosi che saturano la finestra di contesto dei modelli linguistici. Lockfile delle dipendenze, documentazione generata, cartelle di compilazione e bundle minificati non devono mai entrare nel contesto operativo.
Template .claudeignore per ambienti di produzione
Salva questo file nella radice del tuo progetto:
# ==============================================================================
# .claudeignore - Matrice di esclusione token per ambienti di produzione
# Impedisce a Claude Code di caricare artefatti pesanti durante glob e grep
# ==============================================================================
# Lockfile dei pacchetti (JSON/YAML voluminosi privi di valore AST)
package-lock.json
pnpm-lock.yaml
yarn.lock
bun.lockb
composer.lock
Gemfile.lock
Cargo.lock
poetry.lock
# Artefatti di compilazione e bundle generati
dist/
build/
out/
.next/
.nuxt/
.astro/
.svelte-kit/
storybook-static/
target/
*.min.js
*.min.css
*.map
# Copertura test, file di registro e profiling
coverage/
.nyc_output/
*.lcov
*.log
npm-debug.log*
yarn-debug.log*
pnpm-debug.log*
*.heapsnapshot
*.cpuprofile
# Asset multimediali, immagini e file binari
public/assets/
public/images/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.webp
*.avif
*.ico
*.pdf
*.zip
*.tar.gz
*.wasm
# Documentazione di progetto e specifiche API esterne
docs/
*.mdx
specs/swagger/
*.postman_collection.json
# Variabili d'ambiente locali e certificati
.env*
!.env.example
*.pem
*.key
*.cert
# Migrazioni di database e dump SQL
*.sql
*.dump
prisma/migrations/L'impatto misurato di .claudeignore
Durante una scansione ricorsiva delle cartelle, un file package-lock.json non escluso (spesso compreso tra 25.000 e 80.000 righe) consuma all'istante oltre 120.000 token in una singola lettura. Inserendo lockfile e cartelle di compilazione nella lista di esclusione, l'impronta iniziale di contesto scende da ~180k token a meno di 15k token.
4. Pilastro 2: Architettura di Prompt Caching e sconto del 90%
La funzionalità di prompt caching di Anthropic mantiene i token di input sui server per 5 minuti (il timer viene riazzerato a ogni cache hit). La lettura dei token in cache costa soltanto il 10% del prezzo base di input ($0.30/1M rispetto a $3.00/1M su Sonnet).
+-------------------------------------------------------------------------+
| Ciclo di vita del Prompt Caching Anthropic |
+-------------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------------+
| [System Prompt e Definizione Tool] (Prefisso statico - Sempre in cache) |
+-------------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------------+
| [Mappa architettura repository e Linee Guida] (Checkpoint in cache) |
+-------------------------------------------------------------------------+
|
v (Punto di rottura della cache!)
+-------------------------------------------------------------------------+
| [Istruzioni dinamiche dell'utente e chiamate tool] (Coda non in cache) |
+-------------------------------------------------------------------------+Tre regole per preservare la cache dei prompt
- Non iniettare mai timestamp dinamici nel contesto di sistema: Evita date correnti o ID di sessione variabili all'interno di
CLAUDE.md. Una variazione anche su un singolo carattere invalida tutti i token memorizzati in cache a seguire. - Raggruppa le richieste nella finestra di 5 minuti: Il TTL della cache è di 300 secondi. Se metti in pausa la sessione per 6 minuti per esaminare il codice, il prompt successivo incorrerà nella tariffa di scrittura completa ($3.75/1M).
- Ordina le direttive dalla più statica alla più dinamica: L'engine interno di Claude Code allinea le istruzioni statiche all'inizio del payload API. Assicurati che le regole in
CLAUDE.mdrimangano rigorosamente deterministiche.
5. Pilastro 3: Avvio di sub-agenti e isolamento dei sotto-task
Una delle principali cause di inefficienza nei terminali è la trappola della sessione monolitica. In un'unica conversazione continua, lo sviluppatore chiede a Claude di identificare un bogue, scrivere test unitari, effettuare il refactoring del codice, eseguire test di integrazione e aggiornare la documentazione.
Al dodicesimo turno, la finestra di contesto è sommersa da centinaia di righe di log di test falliti, errori del compilatore e vecchie versioni di file. Ogni nuova richiesta reinvia l'intera mole di dati all'API.
Architettura a due livelli: Scout ed Esecutore
Separare l'analisi esplorativa dalla modifica attiva del codice interrompe l'emorragia di token:
[Richiesta dell'utente]
|
v
+---------------------------------------------+
| Livello 1: Sub-agente Scout (Sola Lettura) |
| - Eseguito su claude-3-5-haiku / modello smol|
| - Usa Glob, Grep e letture mirate di righe |
| - Condensa 500.000 token in un report di 2KB|
+---------------------------------------------+
|
v (Passaggio del contesto compresso)
+---------------------------------------------+
| Livello 2: Agente Esecutore Primario |
| - Eseguito su claude-3-7-sonnet |
| - Riceve PERCORSI ESATTI e simboli AST |
| - Applica patch mirate con ancoraggio righe|
+---------------------------------------------+Come applicare l'isolamento dei task in Claude Code
Suddividi le attività complesse in passaggi operativi distinti nel terminale:
# Approccio inefficiente: causa un'esplosione incontrollata del contesto
claude "Trova tutti gli endpoint con autenticazione deprecata, convertili in OAuth2, correggi i test e scrivi la documentazione"
# Approccio efficiente: Esplorazione isolata -> Modifica mirata
# Passo 1: Analisi a basso consumo di token
claude --model claude-3-5-haiku -p "Elenca esclusivamente i percorsi dei file e i numeri di riga che usano il middleware di auth deprecato, in formato JSON." > auth-audit.json
# Passo 2: Modifica chirurgica con contesto pulito
claude --model claude-3-7-sonnet "Refattorizza gli endpoint elencati in auth-audit.json usando il middleware OAuth2. Non toccare altri file."6. Pilastro 4: Scelta oculata del modello — Quale modello Claude consuma meno token?
Non tutti i modelli consumano lo stesso quantitativo di token a parità di operazione:
- Budget di Extended Thinking: I modelli con ragionamento esteso generano migliaia di token interni di pensiero che vengono fatturati come token di output ($15.00/1M su Sonnet).
- Prolissità nelle chiamate ai tool: Alcuni modelli producono lunghe premesse esplicative prima di invocare uno strumento, aumentando i token generati.
- Efficienza di ricerca: I modelli avanzati individuano i simboli tramite 1-2 chiamate grep mirate, laddove modelli meno capaci leggono intere cartelle alla cieca.
Confronto del consumo di token per tipologia di attività
| Tipo di Attività | Claude 3.5 Haiku | Claude 3.7 Sonnet (Normale) | Claude 3.7 Sonnet (8k Thinking) | Claude 3 Opus |
|---|---|---|---|---|
| Ricerca simbolo nel repo | 12k token / $0.01 | 14k token / $0.04 | 24k token / $0.18 | 18k token / $0.27 |
| Bugfix di singola funzione | 28k token / $0.03 | 22k token / $0.07 | 35k token / $0.24 | 30k token / $0.45 |
| Refactoring di 5 file | Alto tasso di errore | 140k token / $0.48 | 190k token / $1.25 | 220k token / $3.30 |
| Race condition complessa | Non risolto | 320k token (fallito) | 240k token (risolto) / $1.60 | 280k token / $4.20 |
Matrice di raccomandazione
- Modello di riferimento predefinito: Utilizza
claude-3-7-sonnetin modalità standard per l'80% del lavoro quotidiano di sviluppo. - Ricognizione e script di supporto: Usa
claude-3-5-haikuper l'esplorazione di cartelle, generazione di regex, script di shell e analisi dei log. - Thinking mirato: Attiva il ragionamento esteso (
thinking: { budget_tokens: 4000 }) solo per problemi algoritmici ostici o errori di compilazione che falliscono al primo tentativo.
7. Configurazione avanzata e ottimizzazione di .claude/config.json
Claude Code consente un controllo granulare del proprio comportamento tramite il file ~/.claude.json a livello globale o .claude/config.json per il singolo repository.
Configurazione ad alta efficienza .claude/config.json
{
"$schema": "https://json.schemastore.org/claude-code-config.json",
"model": "claude-3-7-sonnet",
"maxThinkingTokens": 2048,
"autoCompactContext": true,
"contextCompactionThreshold": 0.65,
"allowedTools": [
"Edit",
"Bash",
"Glob",
"Grep",
"Read"
],
"toolLimits": {
"bashOutputMaxLines": 150,
"readFileMaxLines": 300
},
"enableTelemetry": false
}Parametri principali spiegati
maxThinkingTokens: 2048: Pone un tetto al budget di ragionamento esteso. In assenza di limiti, un task semplice può bruciare da 8k a 16k token di output ($0.12 - $0.24) per turno.autoCompactContext: true: Avvia automaticamente la sintesi della cronologia quando il contesto raggiunge il 65% della capienza (contextCompactionThreshold: 0.65).bashOutputMaxLines: 150: Evita che suite di test o installazioni di pacchetti riversino 5.000 righe di stdout all'interno della finestra del modello.
8. Modelli tattici di prompt per ridurre i token
Il modo in cui formuli i prompt influenza fino al 40% del consumo di token di una sessione:
Modello 1: Lettura vincolata a intervalli di righe
Non far leggere file interi a Claude, ma circoscrivi l'intervallo d'interesse:
# Inefficiente: Legge 1.800 righe (circa 14.000 token)
"Leggi src/auth/session.ts e verifica perché la validazione del token fallisce"
# Efficiente: Legge appena 60 righe (circa 450 token)
"Esamina le righe 120-180 di src/auth/session.ts dove è definita la funzione verifyJwt()"Modello 2: Soppressione e filtraggio degli output
Quando richiedi l'esecuzione di test o build, esigi un output sintetico:
# Inefficiente: Riversa migliaia di righe di test superati nel contesto
"Esegui npm test e correggi l'errore"
# Efficiente: Contiene l'output
"Esegui npm test -- --reporter=dot oppure filtra con grep solo gli errori. Non mostrare i log dei test superati."Modello 3: Pulizia periodica e compattazione (/compact e /clear)
Usa con regolarità i comandi integrati di Claude Code:
/compact: Comprime immediatamente la cronologia attiva in un riassunto tecnico conciso./clear: Resetta del tutto la memoria del contesto prima di iniziare un'attività differente, senza riavviare il terminale.
9. Matrice comparativa delle strategie di risparmio token
| Strategia di Ottimizzazione | Risparmio Medio di Token | Complessità | Rischio Qualità Codice | Meccanismo Principale |
|---|---|---|---|---|
.claudeignore rigoroso |
40% – 60% | Bassa (5 min) | Nullo | Esclude lockfile, media e cartelle di build |
Compattazione contesto (/compact) |
30% – 50% | Immediata (comando) | Basso | Rimuove vecchi log bash e versioni superate |
| Scouting con sub-agenti | 35% – 55% | Media | Bassissimo | Separa l'analisi pesante dalle modifiche mirate |
| Tetto al budget Thinking | 20% – 35% | Bassa (file config) | Basso-Medio | Previene loop di ragionamento su compiti semplici |
| Patch mirate su righe | 15% – 25% | Bassa (buona prassi) | Basso | Sostituisce la riscrittura dei file con diff locali |
| Allineamento Prompt Cache | 10% – 20% (Costo) | Media | Nullo | Blocca i prefissi statici per ottenere il 90% di sconto |
10. Conclusioni e checklist operativa in 5 punti
Tagliare del 75% i token consumati in Claude Code non richiede di sacrificare la precisione o l'affidabilità del codice generato. Anzi, mantenere un contesto pulito e focalizzato elimina il rumore responsabile di allucinazioni e perdita di attenzione.
Checklist operativa in 5 punti:
- [ ] Attiva
.claudeignore: Salva il template di produzione nella radice del repository per escludere lockfile e build. - [ ] Aggiorna
config.json: Limita i token di pensiero a2048e abilitaautoCompactContexta quota0.65. - [ ] Distribuisci i ruoli ai modelli: Usa
claude-3-7-sonnetper il codice,claude-3-5-haikuper l'esplorazione e riserva il Thinking ai casi complessi. - [ ] Controlla l'output del terminale: Imposta i test con flag minimali (
--reporter=min, filtri grep) per contenere le risposte sotto le 100 righe. - [ ] Ripulisci il contesto: Lancia
/compacto/cleartra un blocco di lavoro e l'altro per sradicare il Context Rot.
Seguendo queste direttive nella tua operatività quotidiana, conserverai tutte le potenzialità di sviluppo autonomo di Claude Code riducendo drasticamente le spese mensili di utilizzo delle API.