Por que o Prompt Cache não reduziu custos? Diagnostique agentes de código com prompt-cache-skills

Sua conta mensal do Claude Code ou do Cline pode estar 30% a 50% acima do necessário. Não por excesso de uso, mas porque o Prompt Cache não está funcionando.

Muitos Agents de programação com IA habilitam prompt caching por padrão, porém uma pequena mudança de configuração pode invalidar todo o prefixo em cache: um timestamp dentro do system prompt, uma cache key calculada incorretamente, a opção de cache desativada ou um TTL curto demais. Isso não gera erro nem aviso na fatura; você apenas continua vendo um custo alto de API todos os meses.

O prompt-cache-skills é uma biblioteca de skills drop-in voltada a corrigir essas configurações de cache que deixam de funcionar silenciosamente. Em cenários adequados, a taxa de acerto pode sair de quase zero e chegar a 80% ou mais. A seguir, você entenderá a cobrança do cache, as quatro causas principais de falha, correções típicas da biblioteca e como validar o resultado.

Como o Prompt Cache reduz custos

A lógica de economia do Prompt Cache é simples: um prefixo estável pode ser armazenado em cache e, quando reutilizado, custa muito menos que tokens de entrada comuns.

Os nomes dos campos de cobrança variam entre APIs, mas o princípio é o mesmo:

Tipo de cobrança	Característica	Cenário	Provedor representativo
cache_creation_input_tokens	Criação inicial do cache, geralmente mais cara que um token comum	Primeira solicitação com prefixo longo	Anthropic
cache_read_input_tokens	Acerto de cache, muito mais barato que um token comum, cerca de 10%	Reutilização de prefixo estável	Anthropic
Tokens de entrada comuns	Cobrança pela tarifa normal	Solicitação curta ou prefixo que muda com frequência	Todos os provedores
cached_tokens (OpenAI)	Acerto de cache, com custo cerca de 50% menor	Reutilização de prefixo estável	OpenAI
cached content (Gemini)	Cobrança conforme o tempo de cache	Contextos longos	Google Gemini

Na Anthropic, por exemplo, imagine um system prompt com 2.000 tokens reutilizado 100 vezes por dia no mesmo Agent. Quando há acerto, esses 2.000 tokens são cobrados como cache_read, em torno de 10% do preço de tokens de entrada comuns. Só esse item pode reduzir o custo de entrada em cerca de 90%.

Para o cache funcionar de verdade, o prefixo precisa permanecer estável e ser reutilizado várias vezes. Se o system prompt muda a cada solicitação — por conter um timestamp ou ID aleatório, por exemplo —, o prefixo precisa ser recalculado sempre, e o custo de cache_creation pode até superar o de uma solicitação comum.

Por que o cache do seu Agent sempre falha

Essas falhas não geram mensagens de erro. Você vê o valor da fatura, mas não encontra onde está o desperdício:

1. Mensagens variáveis quebram o prefixo. Um timestamp, ID aleatório ou outro valor que muda em toda solicitação aparece no início do system prompt e invalida todo o prefixo. Essa é a causa mais comum.

2. Cache key ausente ou incorreta. Algumas ferramentas Agent não definem corretamente a marcação do cache ou calculam de forma errada uma cache key personalizada. O conteúdo do prefixo é estável, mas a API não o reconhece como armazenável.

3. Cache desativado por padrão. Algumas ferramentas mantêm prompt caching desligado até que você o habilite manualmente no arquivo de configuração. Você espera que o Agent cuide disso, mas continua pagando a tarifa normal.

4. TTL curto demais. O prazo de validade pode ser de apenas uma hora, enquanto o intervalo real entre suas solicitações é maior. Quando a próxima chamada chega, o cache já expirou.

Os sintomas exatos variam entre Agents. O README do prompt-cache-skills os organiza por ferramenta. Se você suspeita de uma dessas causas, compare primeiro seu caso com o SKILL.md correspondente.

O que é prompt-cache-skills

O prompt-cache-skills é um conjunto de skills drop-in que qualquer Agent de programação com IA pode ler e aplicar:

Dimensão	Descrição
Posicionamento	Skills drop-in com patches que um Agent de programação com IA pode ler e aplicar
Objetivo	Elevar uma taxa de acerto ruim ou parcial para 80%–99% em cenários adequados
Agents compatíveis	Claude Code, Codex, Cline, Cursor, Devin, Gemini CLI, OpenCode, Aider, Continue, Roo Code e outros
Repositório	https://github.com/OnlyTerp/prompt-cache-skills
Uso	Apontar o repositório → Agent aplica automaticamente → validar acerto; ou aplicar manualmente o patch de skills/
Economia de tempo	Evita pesquisar sozinho os detalhes de cache de cada API

O projeto tem atualmente cerca de 99 stars. A lista e os nomes dos skills podem mudar; confirme sempre no README do repositório.

Em comparação com um diagnóstico manual, a biblioteca evita que você precise percorrer a documentação de prompt caching de cada API, comparar configurações de diferentes Agents e adivinhar qual campo está invalidando o prefixo. Cada skill identifica uma causa específica, fornece o diff de correção e explica como validar.

Como usar prompt-cache-skills para corrigir seu Agent

Há duas opções: pedir ao Agent que faça a correção automaticamente ou alterar manualmente os arquivos seguindo o diretório skills/.

Opção 1: deixar o Agent corrigir automaticamente (recomendado)

Primeiro, aponte o repositório. Envie esta instrução ao seu Agent de programação com IA:

Leia https://github.com/OnlyTerp/prompt-cache-skills e aplique cada skill de skills/ compatível com o harness que uso: confirme o alvo → aplique o diff → valide conforme o SKILL.md

Segundo, o Agent identificará sua ferramenta atual — Cline, Continue ou Aider, por exemplo — e listará os skills compatíveis. Você verá a causa tratada por cada um.

Terceiro, revise o diff. Cada diretório de skill contém um SKILL.md que descreve o alvo e as alterações. Leia com atenção e confirme se são seguras.

Quarto, aplique a alteração. Depois da revisão, permita que o Agent aplique o diff aos arquivos de configuração locais ou do projeto. Faça backup da configuração original primeiro.

Quinto, valide o acerto. Use tools/check_cache.py para confirmar se o cache entrou em ação. O procedimento está na seção “Como validar se o cache realmente acertou”.

Opção 2: correção manual

Se você não quer que o Agent altere a configuração automaticamente, pode aplicar a correção manualmente.

Primeiro, acesse o repositório: https://github.com/OnlyTerp/prompt-cache-skills

Segundo, abra o diretório skills/ e localize o skill da ferramenta que você usa, como cline-fix-volatile-msg ou continue-enable-defaults.

Terceiro, leia o SKILL.md. Cada diretório explica o alvo, os sintomas, a correção e a validação.

Quarto, altere manualmente o arquivo de configuração conforme as instruções.

Quinto, valide o acerto com tools/check_cache.py.

Aviso de segurança

Deixar o Agent aplicar um diff altera diretamente configurações locais ou do projeto. Leia o SKILL.md e entenda cada modificação antes de autorizar. Faça backup do arquivo original.

Detalhes da biblioteca de skills: correções típicas

Cada skill do repositório é uma correção completa, com Agent-alvo, sintomas, diff e método de validação. Estes são alguns casos típicos:

Nome do skill	Agent-alvo	Sintoma	Correção
cline-fix-volatile-msg	Cline	O prefixo do system prompt contém timestamp e muda a cada solicitação	Remover ou fixar a mensagem variável
cline-openai-cache-key	Cline + OpenAI	Cálculo incorreto da cache key da OpenAI	Corrigir a lógica de geração da cache key
cline-pin-timestamp	Cline	O timestamp invalida o cache	Fixar ou remover o timestamp
continue-fix-volatile-msg	Continue	O system prompt contém campos variáveis	Remover mensagens variáveis
continue-enable-defaults	Continue	Prompt caching não está habilitado por padrão	Habilitar a configuração de cache
continue-gemini-explicit	Continue + Gemini	Falta configuração de cache do Gemini	Definir explicitamente os parâmetros de cache
aider-1h-ttl	Aider	TTL de apenas uma hora, com expirações frequentes	Estender o TTL ou ajustar a frequência de solicitações
aider-cache-default-on	Aider	Cache desativado por padrão	Habilitar a opção padrão de cache
opencode-detect-openai-compat	OpenCode	Cache falha no modo compatível com OpenAI	Detectar e tratar corretamente a API compatível com OpenAI
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Problema de cache em blocos de documento do Bedrock	Corrigir a estratégia de cache dos blocos

A lista continua crescendo e os nomes podem mudar. Consulte o README e o diretório skills/ do repositório. Se o seu Agent ainda não estiver contemplado, use os arquivos SKILL.md e patches existentes como referência para diagnosticar problemas semelhantes manualmente.

Como validar se o cache realmente acertou

O prompt-cache-skills inclui tools/check_cache.py, que compara duas solicitações, uma a frio e outra a quente, e calcula a taxa de acerto.

Etapas

Primeiro, obtenha check_cache.py no repositório:
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

Segundo, configure a credencial da API pela variável de ambiente:

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

Terceiro, execute a solicitação a frio, ou seja, a primeira chamada:

python check_cache.py --provider anthropic --prompt "seu system prompt" --message "sua mensagem de usuário"

Observe o campo cache_creation_input_tokens:

• Um valor indica que o cache foi criado
• Registre a quantidade de input_tokens

Quarto, aguarde um segundo e execute a solicitação a quente. Repita exatamente o mesmo comando, com prompt e message idênticos.

Observe:

• cache_read_input_tokens: um valor maior que zero indica acerto
• cache_creation_input_tokens: deve ser zero ou não aparecer
• input_tokens: deve cair bastante, pois a parte em cache não é cobrada como entrada comum

Quinto, calcule a taxa de acerto:

Taxa de acerto = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

Exemplo:

• Primeira solicitação: input_tokens=2000, cache_creation_input_tokens=1800
• Segunda solicitação: cache_read_input_tokens=1800, input_tokens=200
• Taxa de acerto = 1800 / (1800 + 200) = 90%

Sexto, interprete o resultado:

• Cache funcionando: cache_read_input_tokens > 0 na solicitação a quente
• Cache não funcionando: cache_read_input_tokens = 0 ou ausente

Se cache_read_input_tokens for zero na solicitação a quente, volte às quatro causas principais e procure mensagens variáveis, cache key incorreta, opção desativada ou TTL curto.

Métricas

• cache_creation_input_tokens: campo da Anthropic com o número de tokens usados para criar o cache
• cache_read_input_tokens: campo da Anthropic com o número de tokens lidos em um acerto
• cached_tokens: campo da OpenAI com o número de tokens em cache
• input_tokens: tokens de entrada comuns, fora do cache

cache_read_input_tokens = 0 na solicitação a quente significa que o cache não funcionou. Retorne às quatro causas anteriores e revise a configuração.

Quando esta biblioteca é ou não é recomendada

A biblioteca corrige problemas conhecidos, mas não serve para todos os cenários:

Cenário	Recomendação	Motivo
System prompt longo + várias solicitações semelhantes	Recomendada	O prefixo estável pode ser reutilizado e gera boa economia
Ferramenta Agent de programação, como Claude Code ou Cline	Recomendada	O projeto foi criado para essas ferramentas
Conta mensal acima de US$ 50	Recomendada	A economia potencial justifica o trabalho
Prompt caching configurado, mas sem confirmação de funcionamento	Recomendada	A ferramenta de validação confirma o resultado
Prompt curto + uma única solicitação	Não recomendada	O custo do cache pode superar o benefício
System prompt muda com frequência, como dados em tempo real	Não recomendada	O prefixo não é estável e não pode ser reutilizado
Intervalo entre solicitações maior que o TTL, como poucas chamadas por dia	Avaliar	O cache pode expirar e gerar pouco benefício
Agent fora da lista compatível	Avaliar	Requer adaptação manual ou um futuro skill da comunidade

Se sua conta mensal já passa de US$ 50 e você usa um Agent compatível, o retorno pode ser relevante. Se a frequência é baixa ou o prefixo muda muito, avalie primeiro se a alteração compensa.

Riscos e cuidados

Antes de usar a biblioteca, considere estes riscos:

1. O projeto é novo. Atualmente tem cerca de 99 stars, e a lista e os nomes dos skills podem mudar. Confirme no README. A biblioteca continuará evoluindo.

2. Alterações automáticas exigem cuidado. Um diff aplicado pelo Agent modifica configurações locais ou do projeto. Leia o SKILL.md e entenda cada ponto antes de autorizar.

3. Os campos de cobrança variam. A Anthropic usa cache_creation/cache_read, a OpenAI usa cached_tokens e o Gemini usa cached content. Consulte a documentação atual.

4. Cache não resolve tudo. Chamadas curtas e únicas ou prefixos variáveis geram pouco benefício e podem custar mais. Não force o uso em todos os casos.

5. A ferramenta de validação tem limites. check_cache.py foi criada principalmente para a API da Anthropic. Consulte também a documentação da OpenAI e do Gemini.

6. A taxa não é garantida. De 80% a 99% é a meta declarada pelo projeto. O resultado depende do prefixo, da frequência, do TTL e de outros fatores.

Próximos passos e leituras

Para reduzir ainda mais o custo da programação com IA:

• Centralize monitoramento, cache e failover com um AI Gateway — gerencie vários provedores e reduza custos evitáveis

• Técnicas de Prompt Engineering para melhorar respostas — melhore prompts e evite tokens desnecessários

• Computer-Use Agent: deixe a IA controlar seu computador — entenda esses Agents e melhore o fluxo de trabalho

Recursos oficiais:

• Repositório prompt-cache-skills no GitHub
• Documentação de Prompt Caching da Anthropic
• Documentação de Prompt Caching da OpenAI
• Documentação de Context Caching do Google Gemini