Un architetto senior viene chiamato quando la spesa cresce più in fretta del traffico, oppure quando un agente affidabile a dieci turni comincia a sbagliare al cinquantesimo. I due sintomi hanno la stessa radice: nessuno ha trattato la finestra di contesto come una risorsa con un proprietario e un budget.

Il contesto è un budget di attenzione, non uno spazio da riempire

La documentazione smonta da sola l’idea che «più contesto sia meglio»: «As token count grows, accuracy and recall degrade, a phenomenon known as context rot». Il saggio di Anthropic sul context engineering fornisce la regola operativa corrispondente: «good context engineering means finding the smallest possible set of high-signal tokens that maximize the likelihood of some desired outcome».

Nel budget entra tutto ciò che spedisci — system prompt, ogni messaggio in messages inclusi tool result, immagini e documenti, e le definizioni dei tool — più l’output generato, thinking compreso. Il campo usage riporta il consumo a posteriori; la token counting API lo stima prima dell’invio. Sui modelli con finestra da 1M token, fra cui Claude Opus 5 e Claude Sonnet 5, 1M è il valore predefinito: nessun beta header e prezzo standard.

Il comportamento al limite va progettato, perché i due casi non si somigliano:

input già oltre la finestra  -> 400 invalid_request_error ("prompt is too long")
input + max_tokens oltre     -> sui modelli 4.5 e successivi la richiesta passa, e la
                                generazione si ferma con
                                stop_reason: "model_context_window_exceeded"

Il secondo caso non arriva come errore ma come risposta troncata: se il codice non legge lo stop reason, la degradazione resta invisibile fino al reclamo dell’utente.

Tre leve, tre problemi diversi

Non sono alternative: agiscono su punti diversi della pipeline, e la scelta si difende dicendo dove stanno realmente i token.

  • Definizioni dei tool caricate a vuoto. Un setup multiserver tipico (GitHub, Slack, Sentry, Grafana, Splunk) «can consume ~55k tokens in definitions before Claude does any work»; il tool search «typically reduces this by over 85 percent». E la capacità di scegliere il tool giusto «degrades once you exceed 30–50 available tools».
  • Storia della conversazione che cresce. La compaction lato server riassume il contesto più vecchio all’avvicinarsi del limite. È in beta sui modelli 4.6 e successivi, con soglia predefinita a 150.000 input token e minimo consentito 50.000; dopo il blocco di riassunto l’API scarta i blocchi precedenti.
  • Tool result ormai inerti. Il context editing con la strategia clear_tool_uses_20250919 cancella i risultati più vecchi in ordine cronologico, governato dai parametri trigger, keep e clear_at_least.

L’ultima leva ha un costo che va detto in riunione: cancellare invalida i prefissi in cache. È esattamente il motivo per cui esiste clear_at_least, cioè «clear enough tokens to make the cache invalidation worthwhile».

Il caching si progetta a strati, non si accende

Il caching non riduce i token in contesto: «prompt caching changes what you pay for those tokens, not whether they count». È una decisione economica, e la sua unità di progetto è il breakpoint, di cui se ne possono definire fino a quattro.

I prefissi si formano nell’ordine tools, system, messages, e «changes at each level invalidate that level and all subsequent levels»: in cima ciò che cambia meno (definizioni dei tool, istruzioni di ruolo, tassonomie), in fondo ciò che cambia a ogni richiesta.

I numeri per il business case:

scrittura cache 5 minuti : 1,25x il prezzo base degli input
scrittura cache 1 ora    : 2x
lettura cache            : 0,1x
minimo memorizzabile     : 512 token (Opus 5), 1.024 (Sonnet 5), 4.096 (Haiku 4.5)

Il TTL predefinito è di 5 minuti; l’ora si chiede con ttl impostato a 1h. Le trappole sono più insidiose dei prezzi: cambiare le definizioni dei tool, aggiungere o togliere immagini, attivare web search o citations (che modificano il system prompt) e cambiare il livello di effort invalidano la cache. L’effort in particolare invalida sempre i blocchi dei messaggi, quindi va tenuto costante dentro una conversazione che vive di cache hit.

Skills e prompt modulari: riuso che non paga il contesto

Le Skill risolvono il problema opposto al caching: non «paghiamo meno gli stessi token», ma «non carichiamo affatto ciò che non serve». Il meccanismo è la progressive disclosure, con costi dichiarati per livello:

Livello 1 - metadati  : sempre in contesto, ~100 token per Skill (name + description)
Livello 2 - istruzioni: al trigger, sotto i 5k token (corpo di SKILL.md)
Livello 3 - risorse   : nulla finché non vengono lette; gli script eseguiti via bash
                        portano in contesto solo il proprio output

«Until a Skill is triggered, only its name and description occupy context»: è la frase che giustifica una libreria ampia davanti a chi teme il costo. Il rovescio è che tutto si gioca sulla description, che «must include both what the Skill does and when Claude should use it». Una description vaga produce Skill che non partono mai, o che partono sempre.

Sul piano di governo, tre vincoli cambiano il disegno. Le Skill personalizzate caricate via API sono accessibili all’intero workspace, non al singolo utente o alla singola conversazione: in uno scenario multi-tenant il workspace è il confine di isolamento. Non si sincronizzano fra superfici, quindi claude.ai, API e Claude Code vanno gestiti separatamente. E vanno trattate come software installato — «use Skills only from trusted sources» — perché una Skill ostile può indirizzare Claude a usare i tool in modi estranei al suo scopo dichiarato.