Perché Prompt Cache non riduce i costi: diagnosticare gli agenti di coding con prompt-cache-skills

La fattura mensile di Claude Code o Cline potrebbe essere superiore del 30%–50% al necessario. Non perché l’utilizzo sia elevato, ma perché Prompt Cache non sta funzionando.

Molti Agent di coding con IA abilitano prompt caching per impostazione predefinita, ma una piccola modifica alla configurazione può invalidare l’intero prefisso memorizzato: un timestamp nel system prompt, una cache key calcolata male, l’opzione della cache disattivata o un TTL troppo breve. Non appare alcun errore e la fattura non lo segnala; continui soltanto a vedere costi API elevati ogni mese.

prompt-cache-skills è una raccolta di skill drop-in dedicata alla correzione di queste configurazioni che smettono di funzionare in silenzio. Nei casi adatti, il tasso di hit può passare da quasi zero all’80% o più. Di seguito vedremo il principio di fatturazione, le quattro cause principali, alcuni casi di correzione tipici e il metodo di verifica.

Come Prompt Cache riduce i costi

Il meccanismo di risparmio di Prompt Cache è semplice: un prefisso stabile può essere memorizzato e, quando viene riutilizzato, costa molto meno dei normali token di input.

I nomi dei campi di fatturazione cambiano tra le API, ma il principio rimane lo stesso:

Tipo di fatturazione	Caratteristica	Caso d’uso	Provider rappresentativo
cache_creation_input_tokens	Prima creazione della cache, in genere più costosa dei token normali	Prima richiesta con prefisso lungo	Anthropic
cache_read_input_tokens	Cache hit, molto meno costoso dei token normali, circa il 10%	Riutilizzo di un prefisso stabile	Anthropic
Token di input normali	Tariffa standard	Richiesta breve o prefisso che cambia spesso	Tutti i provider
cached_tokens (OpenAI)	Cache hit, costo ridotto di circa il 50%	Riutilizzo di un prefisso stabile	OpenAI
cached content (Gemini)	Costo legato alla durata della cache	Contesti lunghi	Google Gemini

Prendiamo Anthropic come esempio. Se il system prompt contiene 2.000 token e viene riutilizzato 100 volte al giorno dallo stesso Agent, quando la cache viene colpita questi 2.000 token sono fatturati come cache_read, circa il 10% del costo di normali token di input. Solo questa voce può ridurre di circa il 90% il costo di input.

La condizione necessaria è che il prefisso sia stabile e venga riutilizzato più volte. Se il system prompt cambia a ogni richiesta, per esempio perché contiene timestamp o ID casuali, il prefisso deve essere ricalcolato ogni volta e cache_creation può persino costare più di una richiesta normale.

Perché la cache del tuo Agent continua a fallire

Questi problemi non generano errori. Vedi la cifra in fattura, ma non riesci a individuare lo spreco:

1. I messaggi variabili rompono il prefisso. Timestamp, ID casuali o altri valori che cambiano a ogni richiesta sono inseriti all’inizio del system prompt e invalidano l’intero prefisso. È la causa più comune.

2. La cache key è assente o errata. Alcuni strumenti Agent non impostano correttamente il marcatore della cache oppure calcolano male una cache key personalizzata. Il prefisso è stabile, ma l’API non lo riconosce come contenuto memorizzabile.

3. La cache è disattivata per impostazione predefinita. Alcuni strumenti tengono prompt caching spento finché non lo abiliti manualmente nel file di configurazione. Pensi che l’Agent lo gestisca, ma continui a pagare la tariffa normale.

4. Il TTL è troppo breve. La durata può essere soltanto un’ora, mentre l’intervallo reale tra le richieste è maggiore. Quando arriva la chiamata successiva, la cache è già scaduta.

I sintomi specifici variano da un Agent all’altro. Il README di prompt-cache-skills li descrive per strumento. Se sospetti una di queste cause, confronta prima il tuo caso con lo SKILL.md corrispondente.

Che cos’è prompt-cache-skills

prompt-cache-skills è un insieme di skill drop-in che qualsiasi Agent di coding con IA può leggere e applicare:

Dimensione	Descrizione
Posizionamento	Skill drop-in con patch che un Agent di coding con IA può leggere e applicare
Obiettivo	Portare un tasso di hit negativo o parziale all’80%–99% nei casi adatti
Agent supportati	Claude Code, Codex, Cline, Cursor, Devin, Gemini CLI, OpenCode, Aider, Continue, Roo Code e altri
Repository	https://github.com/OnlyTerp/prompt-cache-skills
Utilizzo	Indicare il repository → applicazione automatica dell’Agent → verifica; oppure patch manuale dalla directory skills/
Tempo risparmiato	Evita di studiare da zero i dettagli della cache di ogni API

Il progetto conta attualmente circa 99 stars. L’elenco e i nomi degli skill possono cambiare, quindi consulta il README del repository.

Rispetto a un’analisi manuale, questa raccolta evita di dover leggere la documentazione di prompt caching di ogni API, confrontare le configurazioni di Agent diversi e indovinare quale campo invalidi il prefisso. Ogni skill identifica già una causa specifica e fornisce il diff e il metodo di verifica.

Come correggere il tuo Agent con prompt-cache-skills

Puoi lasciare che l’Agent applichi automaticamente la correzione oppure modificare manualmente i file seguendo la directory skills/.

Metodo 1: lasciare che l’Agent corregga automaticamente (consigliato)

Per prima cosa, indica il repository. Invia questa istruzione al tuo Agent di coding con IA:

Leggi https://github.com/OnlyTerp/prompt-cache-skills e applica ogni skill in skills/ compatibile con l'harness che sto usando: conferma la destinazione → applica il diff → verifica secondo SKILL.md

In secondo luogo, l’Agent identifica lo strumento corrente, per esempio Cline, Continue o Aider, e presenta l’elenco degli skill corrispondenti. Vedrai la causa affrontata da ciascuno.

In terzo luogo, controlla il diff. Ogni directory contiene uno SKILL.md che descrive l’obiettivo e le modifiche. Leggilo con attenzione e verifica che siano sicure.

In quarto luogo, applica la modifica. Dopo il controllo, lascia che l’Agent applichi il diff ai file di configurazione locali o del progetto. Prima salva una copia della configurazione originale.

In quinto luogo, verifica l’hit. Usa tools/check_cache.py per confermare che la cache funzioni. Il procedimento è descritto nella sezione “Come verificare che la cache sia stata davvero colpita”.

Metodo 2: correzione manuale

Se non vuoi permettere modifiche automatiche, puoi applicarle manualmente.

Per prima cosa, apri il repository: https://github.com/OnlyTerp/prompt-cache-skills

In secondo luogo, esplora la directory skills/ e trova lo skill dello strumento utilizzato, per esempio cline-fix-volatile-msg o continue-enable-defaults.

In terzo luogo, leggi SKILL.md. Ogni directory descrive destinazione, sintomi, correzione e verifica.

In quarto luogo, modifica manualmente il file di configurazione secondo le istruzioni.

In quinto luogo, verifica il cache hit con tools/check_cache.py.

Avvertenza di sicurezza

Lasciare che l’Agent applichi un diff modifica direttamente la configurazione locale o del progetto. Leggi lo SKILL.md e comprendi ogni cambiamento prima di autorizzarlo. Salva una copia del file originale.

Dettagli della raccolta: casi tipici di correzione

Ogni skill del repository è una correzione completa, con Agent di destinazione, sintomo, diff e metodo di verifica. Questi sono alcuni casi tipici:

Nome dello skill	Agent di destinazione	Sintomo	Correzione
cline-fix-volatile-msg	Cline	Il prefisso del system prompt contiene un timestamp e cambia a ogni richiesta	Rimuovere o fissare il messaggio variabile
cline-openai-cache-key	Cline + OpenAI	Calcolo errato della cache key OpenAI	Correggere la logica di generazione della cache key
cline-pin-timestamp	Cline	Il timestamp invalida la cache	Fissare o rimuovere il timestamp
continue-fix-volatile-msg	Continue	Il system prompt contiene campi variabili	Eliminare i messaggi variabili
continue-enable-defaults	Continue	Prompt caching non è attivo per impostazione predefinita	Abilitare la configurazione della cache
continue-gemini-explicit	Continue + Gemini	Configurazione della cache Gemini assente	Impostare esplicitamente i parametri della cache
aider-1h-ttl	Aider	TTL di una sola ora e scadenze frequenti	Estendere il TTL o regolare la frequenza delle richieste
aider-cache-default-on	Aider	Cache disattivata per impostazione predefinita	Abilitare l’opzione predefinita
opencode-detect-openai-compat	OpenCode	Cache non funzionante in modalità compatibile con OpenAI	Rilevare e gestire correttamente l’API compatibile
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Problema di cache con i blocchi documento Bedrock	Correggere la strategia di cache dei blocchi

L’elenco continua a crescere e i nomi possono cambiare. Fai riferimento al README e alla directory skills/. Se il tuo Agent non è incluso, usa gli SKILL.md e i file patch esistenti come riferimento per diagnosticare manualmente problemi simili.

Come verificare che la cache sia stata davvero colpita

prompt-cache-skills include tools/check_cache.py, che confronta una richiesta cold e una warm e calcola il tasso di hit.

Procedura

Per prima cosa, scarica check_cache.py dal repository:
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

In secondo luogo, configura la credenziale API nella variabile d’ambiente:

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Google Gemini: GOOGLE_API_KEY

In terzo luogo, esegui la richiesta cold, cioè la prima:

python check_cache.py --provider anthropic --prompt "il tuo system prompt" --message "il messaggio dell'utente"

Controlla il campo cache_creation_input_tokens:

• Se ha un valore, la cache è stata creata
• Registra il numero di input_tokens

In quarto luogo, attendi un secondo ed esegui la richiesta warm. Ripeti esattamente lo stesso comando con prompt e message identici.

Controlla questi campi:

• cache_read_input_tokens: un valore maggiore di 0 indica un hit
• cache_creation_input_tokens: dovrebbe essere 0 o assente
• input_tokens: dovrebbe diminuire nettamente perché la parte memorizzata non viene fatturata come input normale

In quinto luogo, calcola il tasso di hit:

Tasso di hit = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

Esempio:

• Prima richiesta: input_tokens=2000, cache_creation_input_tokens=1800
• Seconda richiesta: cache_read_input_tokens=1800, input_tokens=200
• Tasso di hit = 1800 / (1800 + 200) = 90%

In sesto luogo, interpreta il risultato:

• Cache funzionante: cache_read_input_tokens > 0 nella richiesta warm
• Cache non funzionante: cache_read_input_tokens = 0 o assente nella richiesta warm

Se cache_read_input_tokens è 0 nella richiesta warm, torna alle quattro cause principali e controlla messaggi variabili, cache key errata, impostazione disattivata o TTL troppo breve.

Significato delle metriche

• cache_creation_input_tokens: campo Anthropic con il numero di token usati per la prima creazione della cache
• cache_read_input_tokens: campo Anthropic con il numero di token letti durante un hit
• cached_tokens: campo OpenAI con il numero di token trovati nella cache
• input_tokens: token di input normali non memorizzati

cache_read_input_tokens = 0 nella richiesta warm significa che la cache non ha funzionato. Devi tornare alle quattro cause e controllare la configurazione.

Quando usare o non usare questa raccolta

La raccolta corregge problemi noti, ma non è adatta a ogni scenario:

Scenario	Consiglio	Motivo
System prompt lungo + più richieste simili	Consigliata	Il prefisso stabile è riutilizzabile e genera un buon risparmio
Strumento Agent di coding, come Claude Code o Cline	Consigliata	Il progetto è progettato per questi strumenti
Fattura mensile superiore a 50 USD	Consigliata	Il risparmio potenziale giustifica il lavoro
Prompt caching già configurato, ma funzionamento incerto	Consigliata	Lo strumento di verifica permette di confermarlo
Prompt breve + singola richiesta	Non consigliata	Il costo della cache può superare il beneficio
System prompt che cambia spesso, per esempio con dati in tempo reale	Non consigliata	Il prefisso è instabile e non può essere riutilizzato
Intervallo tra richieste superiore al TTL, per esempio poche chiamate al giorno	Da valutare	La cache può scadere e offrire un beneficio limitato
Agent non presente nell’elenco supportato	Da valutare	Richiede un adattamento manuale o un futuro skill della community

Se la fattura supera già 50 USD al mese e usi un Agent supportato, il ritorno può essere significativo. Se le richieste sono rare o il prefisso cambia spesso, valuta prima se la modifica conviene.

Rischi e precauzioni

Prima di usare questa raccolta, considera i seguenti rischi:

1. Il progetto è relativamente nuovo. Attualmente conta circa 99 stars e l’elenco e i nomi degli skill possono cambiare. Controlla il README più recente.

2. Le modifiche automatiche richiedono cautela. Un diff applicato dall’Agent modifica file di configurazione locali o del progetto. Leggi lo SKILL.md e comprendi ogni punto prima di autorizzarlo.

3. I campi di fatturazione variano. Anthropic usa cache_creation/cache_read, OpenAI usa cached_tokens e Gemini usa cached content. Consulta la documentazione attuale.

4. La cache non risolve tutto. Chiamate brevi e singole o prefissi variabili offrono poco beneficio e possono costare di più. Non forzarla in ogni scenario.

5. Lo strumento di verifica ha dei limiti. check_cache.py è progettato principalmente per l’API Anthropic. Consulta anche la documentazione di OpenAI e Gemini.

6. Il tasso non è garantito. L’80%–99% è l’obiettivo dichiarato dal progetto. Il risultato dipende da prefisso, frequenza, TTL e altri fattori.

Passi successivi e altre letture

Per ridurre ulteriormente i costi del coding con IA:

• Centralizzare monitoraggio, cache e failover con un AI Gateway — gestisci più provider e riduci i costi evitabili

• Tecniche di Prompt Engineering per migliorare le risposte — migliora i prompt ed evita token inutili

• Computer-Use Agent: lasciare che l’IA controlli il computer — comprendi questi Agent e migliora il flusso di lavoro

Risorse ufficiali:

• Repository GitHub prompt-cache-skills
• Documentazione Prompt Caching di Anthropic
• Documentazione Prompt Caching di OpenAI
• Documentazione Context Caching di Google Gemini