Guia de cache do Claude Code dos engenheiros da Anthropic para economizar 300 milhões de tokens por semana

Título original: Como os Engenheiros da Anthropic Realmente Economizam Tokens
Autor original: Nate Herk
Traduzido por: Peggy, BlockBeats

Autor original do artigo: BlockBeats

Fonte original:

Repostagem: Mars Finance

Prefácio do editor: Muitas pessoas ao usar Claude Code têm a impressão de que o consumo de tokens é muito rápido e que sessões longas facilmente consomem o limite. Mas, do ponto de vista dos engenheiros da Anthropic, o que realmente afeta o custo muitas vezes não é quanto código você escreve, mas se o sistema consegue reutilizar continuamente o contexto já processado.

O núcleo deste artigo é como economizar tokens através de um mecanismo de cache. O autor, em uma semana, reutilizou mais de 300 milhões de tokens via cache, com um pico diário de 91 milhões. Como o custo de tokens em cache é apenas 10% do de tokens de entrada normais, isso significa que 91 milhões de tokens em cache equivalem a aproximadamente 9 milhões de tokens normais em cobrança. A razão pela qual sessões longas do Claude Code parecem mais "duráveis" não é porque o modelo trabalha de graça, mas porque uma grande quantidade de contexto repetido foi reutilizada com sucesso.

A chave do prompt caching está em "não interromper o cache". Claude Code armazena em camadas o prompt do sistema, a definição de ferramentas, o CLAUDE.md, as regras do projeto e o histórico de diálogos; desde que o prefixo da solicitação subsequente permaneça consistente, Claude pode simplesmente ler o cache, sem precisar reprocessar todo o contexto. A Anthropic também monitora a taxa de reutilização do prompt cache, pois isso não afeta apenas o limite do usuário, mas também o custo do serviço do modelo e a eficiência operacional.

Para usuários comuns, não é necessário entender todos os detalhes de implementação, basta seguir alguns hábitos-chave: não deixar a sessão inativa por mais de uma hora; fazer uma transferência de sessão ao trocar de tarefa; evitar trocar de modelo com frequência; e colocar documentos grandes em Projects, ao invés de colar repetidamente na conversa.

Este artigo, mais do que ensinar uma técnica de economia de tokens, oferece uma abordagem mais próxima do pensamento de engenheiro para usar o Claude Code: tratar o contexto como um ativo, manter o cache reutilizável, e reduzir cálculos repetidos em sessões longas.

A seguir, o texto original:

Nessa semana, economizei 300 milhões de tokens, com 91 milhões em um único dia, totalizando mais de 300 milhões em uma semana.

Não alterei nenhuma configuração. Isso é apenas o prompt caching funcionando normalmente nos bastidores.

Mas, ao entender de verdade o que é o cache e como evitar "interrompê-lo", consegui manter minhas sessões por mais tempo com o mesmo limite de uso. Portanto, aqui está um guia introdutório 80/20 do prompt caching do Claude Code, sem entrar em detalhes profundos da API.

TL;DR

O custo de tokens em cache é apenas 10% do de tokens de entrada normais. 9100 mil tokens em cache, na prática, custam aproximadamente 900 mil tokens.

A TTL do cache na assinatura do Claude Code é de 1 hora; na API, o padrão é 5 minutos; o Sub-agent sempre é 5 minutos.

O cache é dividido em três camadas: camada do sistema, camada do projeto e camada da conversa.

Trocar de modelo no meio da sessão pode destruir o cache, incluindo ao ativar o modo "opus plan".

Como o cache é cobrado?

Cada token em cache tem um custo de apenas 10% do token de entrada normal.

Assim, quando meu painel mostra que em um dia foram utilizados 91 milhões de tokens em cache, a cobrança real é aproximadamente equivalente a 9 milhões de tokens processados. Essa é a razão pela qual, ao usar Claude Code por longos períodos, a sensação é de que a conversa quase "não custa" para ser prolongada.

No painel, há dois números importantes:

Cache create: custo único ao escrever conteúdo no cache. Ele começa a fazer efeito na próxima rodada de diálogo.
Cache read: tokens reutilizados pelo Claude a partir do cache, como seu CLAUDE.md, definições de ferramentas, mensagens anteriores, etc. Comparado a processar tudo como entrada novamente, esse custo é 10 vezes menor.

Se seu número de Cache read for alto, significa que você está aproveitando bem o cache; se for baixo, indica que está pagando várias vezes pelo mesmo contexto.

Thariq, da Anthropic, disse algo que me impressionou: "Na verdade, monitoramos a taxa de acerto do prompt cache. Quando ela fica muito baixa, acionamos alertas ou até uma emergência de nível SEV."

Ele também escreveu um ótimo artigo no X. Quando a taxa de acerto do cache é alta, quatro coisas acontecem simultaneamente: Claude Code fica mais rápido, o custo do serviço da Anthropic diminui, sua cota de assinatura dura mais, e sessões longas de codificação se tornam mais viáveis.

Por outro lado, se a taxa de acerto for baixa, todos perdem.

Portanto, os incentivos de ambos os lados são alinhados: a Anthropic quer que sua taxa de cache seja alta, e você também quer. O que realmente prejudica tudo são pequenos hábitos que parecem inofensivos, mas que silenciosamente resetam o cache.

Como o cache cresce a cada rodada de diálogo?

O cache depende de "prefix matching", ou seja, "correspondência de prefixo".

Sem entrar em detalhes técnicos profundos, basta entender que: desde que o conteúdo antes de uma determinada posição seja exatamente igual ao conteúdo já cacheado, Claude pode reutilizar esses tokens.

Um novo diálogo geralmente funciona assim:

De acordo com a documentação do Claude Code, uma sessão nova normalmente funciona assim:

Primeira rodada: não há cache ainda. O prompt do sistema, o contexto do projeto (como CLAUDE.md, memória, regras), e sua primeira mensagem são processados novamente e escritos no cache.

Segunda rodada: todo o conteúdo da primeira rodada já está cacheado. Claude só precisa processar sua nova resposta e a próxima mensagem. O custo dessa rodada é muito menor.

Terceira rodada: mesma lógica. o diálogo anterior permanece no cache, apenas a última interação precisa ser reprocessada.

O cache em si é dividido em três camadas:

Segundo o artigo de Thariq:

Camada do sistema (System layer): inclui instruções básicas, definições de ferramentas (read, write, bash, grep, glob) e estilo de saída. Essa camada é cache global.

Camada do projeto (Project layer): inclui CLAUDE.md, memória, regras do projeto. Essa camada é cache por projeto.

Camada da conversa (Conversation): inclui respostas e mensagens, que crescem a cada rodada.

Se, no meio da sessão, qualquer mudança na camada do sistema ou do projeto ocorrer, tudo precisa ser cacheado novamente do zero. Essa é a operação mais "cara". Imagine: você já está na 16ª mensagem, e de repente altera o prompt do sistema ou fica uma hora inativo, tudo desde a primeira mensagem precisa ser reprocessado.

Confusão entre 1 hora e 5 minutos

Essa é a confusão mais comum.

Claude Code assinatura: TTL padrão de 1 hora.
API do Claude: TTL padrão de 5 minutos. Você pode pagar mais para aumentar para 1 hora.
Sub-agent de qualquer plano: sempre 5 minutos.

Chat no site do Claude.ai: a documentação oficial não é clara. Pode ser igual ao da assinatura, mas ainda não confirmei.

Alguns meses atrás, muitos reclamaram que o limite do Claude estava sendo consumido muito rápido. Achavam que a Anthropic tinha reduzido silenciosamente o TTL de 1 hora para 5 minutos, sem aviso. Mas isso não é verdade: o TTL do Claude Code continua sendo 1 hora.

O problema é que a documentação do Claude Code e da API é separada, e esses dois são coisas diferentes, o que causa confusão.

Se você roda muitos fluxos de trabalho com Sub-agent ou usa a API diretamente, o valor de 5 minutos é importante. Mas, para 95% dos usuários do Claude Code, o que importa mesmo é a janela de 1 hora.

Três hábitos para cobrir 95% dos usuários

Aqui estão as práticas que considero mais úteis no uso diário:

Não pause por muito tempo

Se ficar inativo por mais de uma hora, o cache provavelmente expirou. Sua próxima mensagem vai reconstruir o cache. Nesse caso, é melhor fazer uma transição clara e iniciar uma nova sessão, geralmente com menor custo.

Ao trocar de tarefa, reinicie de forma direta

/compress ou /clear já destroem o cache, então é melhor usar esse momento para realmente resetar.

Criei uma habilidade de transferência de sessão, para substituir /compact. Ela resume o que foi feito, decisões pendentes, arquivos mais importantes, e onde continuar. Depois, executo /clear e coloco esse resumo, continuando como se nada tivesse sido interrompido.

O comando /compact às vezes é lento. Essa transferência geralmente leva menos de um minuto.

No chat do Claude, coloque documentos grandes em Projects sempre que possível

O mecanismo de cache do Claude.ai não tem documentação oficial detalhada, mas Projects claramente usa uma otimização diferente do fluxo normal de diálogo. Portanto, se for colar um documento grande, é melhor colocá-lo em um Project, ao invés de colar na conversa.

Quais ações podem silenciosamente destruir o cache?

Algumas ações podem resetar tudo sem aviso:

Trocar de modelo: pois o cache depende de correspondência de prefixo, e cada modelo tem seu próprio cache. Trocar de modelo faz com que a próxima requisição leia todo o histórico novamente, sem cache.

Modo "Opus plan": essa configuração usa Opus na fase de planejamento e Sonnet na execução. Recomendei em vídeos de otimização de tokens, e há razões para isso. Mas é importante entender que cada troca de plano é, na prática, uma troca de modelo, o que implica reconstrução do cache. A longo prazo, ajuda a prolongar o limite, mas é importante saber o que acontece por baixo.

Editar o CLAUDE.md no meio da conversa é possível: essa alteração não é aplicada imediatamente, só na próxima reinicialização. Portanto, o cache atual não é afetado.

Meu painel de tokens gratuito

A captura de tela que mostrei antes vem de um painel de tokens.

É um repositório simples no GitHub. Você fornece o link ao Claude Code, que roda localmente no localhost, e ele lê todas as suas sessões passadas, sem começar do zero. Assim, você consegue ver os dados diários de input, output, cache create e cache read.

Mas atenção: esse painel mostra os tokens no seu dispositivo local. Se você trocar de desktop para notebook, os números podem não coincidir exatamente. Cada dispositivo tem sua própria visualização.

Resumo

Prompt caching é um tema bastante aprofundado. O artigo de Thariq cobre de forma mais completa, se você quiser uma visão geral, vale a pena ler.

Mas você não precisa entender todos os detalhes para tirar proveito. Basta dominar o essencial 80/20: tokens em cache custam 10% do normal; TTL do Claude Code é 1 hora; trocar de modelo destrói o cache; fazer uma transição clara entre tarefas costuma ser mais barato do que deixar uma sessão antiga "expirar" e continuar.