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
Tradução: Peggy, BlockBeats

Autor original do artigo:律动BlockBeats

Fonte original:

Reprodução: 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, sob a perspectiva dos engenheiros da Anthropic, o que realmente afeta o custo não é tanto a quantidade de código que você escreve, mas se o sistema consegue reutilizar continuamente o contexto já processado.

O núcleo deste artigo é compartilhar 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 de 91 milhões de tokens em um único dia. 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". O Claude Code armazena em camadas o prompt do sistema, a definição de ferramentas, o arquivo CLAUDE.md, as regras do projeto e o histórico de diálogos; desde que o prefixo da solicitação subsequente permaneça consistente, o Claude pode ler diretamente do cache, sem precisar reprocessar todo o contexto. A equipe da Anthropic também monitora a taxa de reutilização do prompt cache, pois ela não afeta apenas o limite do usuário, mas também influencia diretamente 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 adotar 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 colá-los repetidamente na conversa.

Este artigo, mais do que ensinar uma técnica para economizar 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 evitar 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", minhas sessões podem durar mais com o mesmo limite de uso. Portanto, aqui está um guia introdutório 80/20 para o 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. 91 milhões de tokens em cache, na prática, custam aproximadamente 9 milhões de tokens.

A TTL do cache na assinatura do Claude Code é de 1 hora; na API, o padrão é 5 minutos; e 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 quebra 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. É por isso que, comparado a sessões sem cache, o uso prolongado do Claude Code parece quase "gratuito" para estender a conversa.

No painel, há dois números que merecem atenção:

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 o seu número de Cache read for alto, significa que você está aproveitando bem o cache; se for baixo, você está pagando repetidamente pelo mesmo contexto.

Thariq, da Anthropic, disse uma frase que me impressionou: "Na verdade, monitoramos a taxa de acerto do prompt cache; se ela ficar muito baixa, acionamos alertas ou até mesmo 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: o 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.

Assim, os incentivos de ambos os lados são alinhados: a Anthropic quer que sua taxa de acerto seja maior, e você também quer. O que realmente prejudica é o hábito de fazer pequenas ações que parecem inofensivas, 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 anterior a uma determinada posição seja exatamente igual ao conteúdo já cacheado, o 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 é 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á em cache. O 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 re-cacheado 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; então, todos os tokens desde a primeira mensagem precisam ser reprocessados.

Confusão entre 1 hora e 5 minutos

Esse é o ponto mais fácil de entender errado.

Claude Code assinatura: TTL padrão é 1 hora.
API do Claude: TTL padrão é 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.

Há alguns meses, muitos reclamaram que o limite do Claude consumia muito rápido. Achavam que a Anthropic tinha reduzido 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 workflows de 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 transferência clara e iniciar uma nova sessão, geralmente com menor custo.

Ao trocar de tarefa, reinicie de forma direta

/compress ou /clear já quebram o cache, então é melhor usar esses momentos para realmente resetar.

Criei uma habilidade de transferência de sessão, que substitui o /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

A mecânica de cache no Claude.ai não é detalhadamente documentada, mas Projects claramente usa uma otimização diferente das conversas normais. Então, se for colar um documento grande, é melhor colocá-lo em um Project do que 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 prefix matching, e cada modelo tem seu próprio cache. Trocar de modelo faz com que a próxima requisição releia todo o histórico, sem cache.

Modo "Opus plan": esse modo usa Opus na fase de planejamento e Sonnet na execução. Recomendei em vídeos de otimização de tokens, e há uma razão. Mas é importante entender que cada troca de plano é, na essência, uma troca de modelo, o que implica reconstruir o cache. A longo prazo, ajuda a prolongar o limite, mas é importante saber o que acontece por baixo.

Editar o CLAUDE.md no meio da sessão é 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 anteriormente 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 diariamente 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 laptop, os números podem não coincidir exatamente. Cada dispositivo tem sua própria visualização de estatísticas.

Resumo

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

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