Título original: How Anthropic Engineers Actually Save Tokens
Autor original: Nate Herk
Tradução: Peggy, BlockBeats

Prólogo do editor: Muitas pessoas ao usar Claude Code têm a sensação mais direta 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 desta publicação é como economizar Tokens por meio 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 representam uma cobrança equivalente a aproximadamente 9 milhões de Tokens normais. 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 cache de prompt está em "não interromper o cache". O Claude Code armazena em camadas o prompt do sistema, definições de ferramentas, CLAUDE.md, regras do projeto e diálogos históricos; enquanto a solicitação subsequente mantiver o mesmo prefixo, o Claude pode ler diretamente do cache, sem precisar reprocessar todo o contexto. Internamente na Anthropic, também monitoram 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 sua 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 colar 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 na utilização do 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 que minhas sessões durassem mais sob 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. 91 milhões de Tokens em cache, na prática, custam cerca de 9 milhões de Tokens.

A TTL (tempo de vida) do cache na assinatura do Claude Code é de 1 hora; na API, padrão de 5 minutos; e nos Sub-agentes, 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.

Portanto, quando meu painel mostra que em um dia foram utilizados 91 milhões de Tokens em cache, a cobrança real equivale a cerca de 9 milhões de Tokens processados. É por isso que, ao usar Claude Code por longos períodos, parece quase que a conversa é "gratuita" e se prolonga.

No painel, há dois números importantes:

Cache create: custo único ao escrever conteúdo no cache, que começa a atuar na próxima interação.
Cache read: Tokens reutilizados pelo Claude a partir do cache, como seu CLAUDE.md, definições de ferramentas, mensagens anteriores, etc. Em comparação ao reprocessar tudo como entrada, 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, está pagando repetidamente pelo mesmo contexto.

Thariq, da Anthropic, disse algo que me impressionou: "Na verdade, monitoramos a taxa de acerto do prompt cache. Quando ela fica baixa demais, 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, seu limite de assinatura dura mais, e sessões longas de codificação se tornam mais viáveis.

Por outro lado, uma baixa taxa de acerto prejudica a todos.

Assim, os incentivos estão alinhados: a Anthropic quer que sua taxa de acerto seja alta, e você também. O que realmente atrasa 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?

Depende do "prefix matching", ou seja, "correspondência de prefixo".

Sem entrar em detalhes técnicos complexos, basta entender que: enquanto o conteúdo anterior a uma determinada posição for exatamente igual ao conteúdo já cacheado, o Claude pode reutilizar esses Tokens.

Uma sessão nova geralmente funciona assim:

Segundo a documentação do Claude Code, uma sessão nova costuma seguir este fluxo:

Primeira rodada: não há cache ainda. Os prompts do sistema, o contexto do projeto (como CLAUDE.md, memória, regras), e sua primeira mensagem são processados novamente e armazenados 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. Assim, o custo dessa rodada é muito menor.

Terceira rodada: o mesmo princípio. o diálogo anterior permanece no cache, e apenas a última interação precisa ser reprocessada.

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

Segundo Thariq, no artigo do X:

Camada do sistema (System layer): inclui comandos básicos, definições de ferramentas (read, write, bash, grep, glob) e estilos 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 alteração 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 muda o prompt do sistema ou fica uma hora parado — tudo desde a primeira mensagem precisa ser reprocessado.

Confusão entre 1 hora e 5 minutos

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

Claude Code assinatura: TTL padrão de 1 hora.

Claude API: TTL padrão de 5 minutos. Pode ser aumentado a um custo maior para 1 hora.
Para Sub-agentes de qualquer plano: sempre 5 minutos.

Chat no site do Claude.ai: não há documentação oficial 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 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 produtos são totalmente diferentes, o que causa confusão.

Se você roda muitos fluxos de trabalho com Sub-agentes 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

A seguir, hábitos que considero realmente úteis no uso diário.

Não deixe a sessão inativa por muito tempo

Se ficar mais de uma hora parado, o cache provavelmente expirou. Sua próxima mensagem vai reconstruir o cache do zero. Nessa situação, é melhor fazer uma transferência clara e iniciar uma nova sessão, geralmente com menor custo.

Ao trocar de tarefa, reinicie do zero

/compact ou /clear já destroem o cache, então é melhor usar esses comandos para uma reinicialização limpa.

Criei uma técnica de transferência de sessão, que substitui o /compact. Ela resume o que foi feito, as decisões pendentes, os arquivos mais importantes, e onde continuar. Depois, executo /clear e coloco esse resumo, continuando a conversa sem interrupções.

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

Para grandes documentos, coloque-os em Projects no Claude.ai

O mecanismo de cache do Claude.ai não tem documentação oficial detalhada, mas Projects claramente usa uma otimização diferente das conversas normais. Portanto, se for colar documentos grandes, é melhor colocá-los em Projects, não na conversa direta.

O que pode quebrar o cache silenciosamente?

Algumas ações podem resetar o cache 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 toda a história seja reprocessada na próxima solicitação.

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 trocar de plano é, na essência, trocar 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 conversa é possível: essa alteração não entra em efeito imediatamente, só na próxima reinicialização. Portanto, o cache atual não é afetado.

Meu painel de Tokens gratuitos

A captura de tela anterior vem de um painel de tokens.

https://github.com/nateherkai/token-dashboard

Este é um repositório simples no GitHub. Você fornece o link ao Claude Code, que faz a implantação local no localhost, e ele lê todas as suas sessões passadas, sem começar do zero. Assim, você consegue ver diariamente inputs, outputs, cache create e cache read.

Mas atenção: esse painel mostra os Tokens no 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 de estatísticas.

Resumo

Prompt caching é um tema bastante aprofundado. O artigo do Thariq é mais completo, vale a pena ler se quiser uma visão geral.

Mas você não precisa entender tudo para se beneficiar. Basta dominar o essencial 80/20: Tokens em cache são 10 vezes mais baratos; TTL do Claude Code é 1 hora; trocar de modelo quebra o cache; fazer uma transferência clara entre tarefas costuma ser mais econômico do que deixar uma sessão antiga "expirar" e continuar.

[Link do artigo original]

Clique para conhecer as vagas na BlockBeats

Participe do grupo oficial da BlockBeats no Telegram:
Telegram: https://t.me/theblockbeats
Telegram: https://t.me/BlockBeats_App
Twitter: https://twitter.com/BlockBeatsAsia