Perché Claude Code invia 33k token prima del tuo prompt (e cosa fare)

Comprendere il sovraccarico nell'utilizzo dei token di Claude Code

Ogni strumento di programmazione basato su agenti carica il contesto prima ancora di vedere il tuo prompt. Il modello deve sapere chi è, quali strumenti può chiamare e in quale ambiente opera. Claude Code si colloca tra gli strumenti più pesanti di questa categoria. Un avvio a freddo comporta in genere circa 33k token di preambolo; un'alternativa minimale come OpenCode riporta un valore più vicino a 7k.

Questa differenza è reale, ma non è una classifica di qualità. È una scelta progettuale. 33k garantisce strumenti integrati più ricchi e un comportamento dell'agente più affidabile; 7k garantisce un'impronta più contenuta e avvii a freddo meno costosi. Nessuno dei due è «corretto»: sono punti diversi su una curva che mette in relazione capacità e costo.

Ecco una ripartizione indicativa dei token utilizzati da Claude Code all'avvio. I numeri esatti cambiano da una versione all'altra, quindi considerali come proporzioni, non come costanti fisse:

La voce più consistente è quasi sempre quella delle definizioni degli strumenti. Questo sorprende chi si aspetta che sia il prompt di sistema a predominare.

Perché gli schemi degli strumenti sono così pesanti

Ogni strumento che il modello può chiamare viene fornito come schema strutturato: nome, descrizione e uno Schema JSON completo per i suoi parametri. Un singolo strumento ben documentato può arrivare a 500–1,500 token, contando le descrizioni dei parametri annidati e le enumerazioni. Claude Code abilita un ampio insieme predefinito di strumenti (lettura/scrittura di file, modifica, bash, glob, grep, recupero di contenuti web, creazione di task/agenti, monitoraggio delle attività da svolgere e altro), e ognuno di essi è presente in ogni richiesta.

Uno schema semplificato per un singolo strumento ha più o meno questo aspetto:

{
  "name": "edit_file",
  "description": "Make a targeted edit to an existing file. Use this instead of rewriting the whole file when possible...",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": { "type": "string", "description": "Absolute path to the file" },
      "old_string": { "type": "string", "description": "Exact text to replace, including surrounding context for uniqueness" },
      "new_string": { "type": "string", "description": "Replacement text" }
    },
    "required": ["path", "old_string", "new_string"]
  }
}

Moltiplica questo per più di una dozzina di strumenti, poi aggiungi tutti quelli esposti da ogni server MCP che hai collegato, e il payload degli schemi cresce rapidamente. Un'insidia comune: qualcuno installa tre server MCP «per provarli», ciascuno dei quali espone 8–15 strumenti, e il suo consumo di base aumenta di 10k token a cui non pensa più.

Il contesto dell'ambiente che non hai richiesto

Quando Claude Code si avvia all'interno di un repository, inserisce informazioni sull'ambiente affinché l'agente non debba consumare un turno per fare domande di base. In pratica, questo include elementi come:

Working directory: /home/ryan/projects/api-gateway
Platform: linux
Git branch: feature/rate-limiting
Git status: 4 modified, 1 untracked
Recent commits: ...

È davvero utile: è il motivo per cui l'agente sa già che stai lavorando su un branch dedicato a una funzionalità. Ma sono comunque token e, in un monorepo di grandi dimensioni, l'istantanea delle directory può avere un peso significativo.

Cosa ottieni davvero in cambio del sovraccarico

Prima di eliminare questo sovraccarico con delle ottimizzazioni, valuta con onestà il compromesso. Quei 33k sono il motivo per cui Claude Code può, già alla prima risposta, modificare il file giusto con il contesto circostante corretto, eseguire i tuoi test, avviare un sottoagente per un'attività parallela e rispettare le convenzioni del progetto, il tutto senza una serie di domande di chiarimento. Un agente da 7k token deve spesso acquisire quel contesto attraverso turni aggiuntivi, il che significa più richieste, più latenza e, a volte, più token complessivi nell'arco di un'intera sessione.

Quindi il confronto non è «33k sprecone contro 7k efficiente». È:

• Meno richieste, più pesanti (Claude Code) contro più richieste, più leggere (agenti minimali)
• Capacità disponibili immediatamente contro capacità costruite su richiesta
• Costo fisso più alto per sessione contro costo variabile più alto per attività

In una sessione di debug di cinque messaggi, il sovraccarico fisso si ammortizza bene. Per una richiesta di una sola riga senza seguito, sembra uno spreco. Entrambe le reazioni sono corrette nel rispettivo contesto.

Le leve su cui puoi effettivamente agire

Non puoi riscrivere l'insieme degli strumenti di base di Claude Code, ma tre impostazioni incidono in modo significativo sul consumo di base.

1. Riduci CLAUDE.md senza pietà

CLAUDE.md viene inserito integralmente in ogni richiesta. È l'unica parte del preambolo che dipende da te al 100%, ed è dove vedo più sprechi: file da 4k token pieni di linee guida stilistiche aspirazionali che il modello segue già per impostazione predefinita.

Mantienilo conciso ed essenziale. Privilegia:

# Project: api-gateway

- Package manager: pnpm (never npm)
- Tests: `pnpm test` — must pass before any commit
- Do NOT edit files in /generated
- API errors use the AppError class in src/errors.ts

Elimina tutto ciò che il modello farebbe comunque («scrivi codice pulito», «aggiungi commenti»). Una buona regola pratica: se eliminare una riga non cambierebbe il comportamento dell'agente, ti sta costando token inutilmente. Per un contesto approfondito, inseriscilo in un file di riferimento che l'agente legga su richiesta invece di incollarlo nella memoria.

2. Disabilita i server MCP e gli strumenti inutilizzati

Per la maggior parte delle persone, questa è la misura con il maggiore impatto. Controlla cosa è effettivamente collegato:

claude mcp list

Se vedi server che hai aggiunto mesi fa e non usi mai, rimuovili:

claude mcp remove some-unused-server

Puoi anche limitare gli strumenti consentiti, mantenendo i relativi schemi fuori dal contesto. Nelle impostazioni del progetto o dell'utente:

{
  "permissions": {
    "allow": ["Read", "Edit", "Bash", "Grep", "Glob"],
    "deny": ["WebFetch"]
  }
}

Ogni strumento che escludi è uno schema che non paghi per inviare a ogni turno. Nella pratica, disabilitare un solo server MCP particolarmente prolisso mi ha fatto risparmiare più token di qualsiasi modifica al prompt.

3. Punta decisamente sulla memorizzazione dei prompt nella cache

Questo è il punto più importante e cambia completamente il calcolo. Il prompt di sistema, le definizioni degli strumenti e il contesto stabile del progetto sono gli stessi in ogni richiesta all'interno di una sessione e questo li rende ideali per la memorizzazione dei prompt nella cache. I token di input memorizzati nella cache costano molto meno di quelli nuovi, quindi quel preambolo da 33k smette in gran parte di pesare dopo la prima chiamata.

Claude Code usa automaticamente la cache, ma puoi facilitarne l'uso mantenendo davvero stabile la parte stabile del tuo contesto:

• Evita di riscrivere CLAUDE.md durante la sessione: una modifica invalida la cache per tutto ciò che segue.
• Inserisci il contesto statico all'inizio; mantieni i dettagli variabili nei tuoi messaggi, non nel preambolo.
• L'ordine conta: la cache funziona su un prefisso, quindi qualsiasi modifica nelle parti iniziali invalida tutto ciò che viene dopo.

La conseguenza pratica: ottimizza il numero di token della tua prima richiesta per ridurre il costo, ma ottimizza la tua sessione per sfruttare la cache. Un prefisso stabile da 33k che viene memorizzato correttamente nella cache è spesso più economico, durante una vera sessione di lavoro, di un prefisso da 7k che non viene mai memorizzato perché viene ricostruito a ogni turno.

Se esegui carichi di lavoro con agenti su larga scala e segui attentamente i calcoli dei costi per token, è anche qui che un accesso API più economico, come quello offerto da AI Prime Tech per i modelli Claude, si combina efficacemente con una buona gestione della cache.

Indicazioni pratiche

• Il costo di avvio di circa 33k è dovuto soprattutto agli schemi degli strumenti, non al prompt di sistema. Le definizioni degli strumenti e i server MCP assorbono la maggior parte dei token.
• È un compromesso, non uno spreco. Il sovraccarico offre capacità immediate e meno scambi nella conversazione; gli agenti più leggeri spostano il costo da fisso a variabile.
• Controlla prima i tuoi server MCP. Rimuovere i server inutilizzati e negare l'accesso agli strumenti inutilizzati è la singola misura di riduzione con il maggiore impatto.
• Mantieni CLAUDE.md essenziale. Elimina tutto ciò che il modello fa per impostazione predefinita; rimanda alla documentazione approfondita da leggere su richiesta invece di incollarla.
• Progetta per sfruttare la cache, non solo per avere una prima richiesta piccola. Un preambolo stabile che viene memorizzato correttamente nella cache è più vantaggioso di uno minuscolo che viene ricostruito a ogni turno.
• Misura per sessione, non per messaggio. Valuta il sovraccarico rispetto all'intera attività, dove i costi fissi si ammortizzano.