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

Nota 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 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 representam aproximadamente o custo de 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 prompt caching está em "não interromper o cache". 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, 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 isso não afeta apenas o limite do usuário, mas também está diretamente relacionado ao custo do serviço do modelo e à 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 de economia de Tokens, oferece uma abordagem mais próxima do pensamento de engenheiro para usar 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 por dia, totalizando mais de 300 milhões em uma semana.

Não alterei nenhuma configuração. Isso é apenas o prompt caching funcionando normalmente em segundo plano.

Mas, ao entender realmente o que é o cache e como evitar "quebrá-lo", minhas sessões podem durar mais com o mesmo limite de uso. Portanto, organizei 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 do cache na assinatura do Claude Code é de 1 hora; na API, padrão de 5 minutos; e o Sub-agent sempre é de 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 é calculado?

Cada Token em cache tem um custo de 10% do Token de entrada.

Portanto, quando meu painel mostra que em um dia foram utilizados 91 milhões de Tokens em cache, o custo real é aproximadamente o equivalente a processar 9 milhões de Tokens. É por isso que, ao usar Claude Code por longos períodos sem cache, a sensação é de que a conversa é quase "gratuita" e se prolonga.

No painel, há dois números importantes:

Cache create: custo único ao escrever conteúdo no cache, que entra em ação 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, custa 10 vezes menos.

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 incidentes 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, seu limite 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 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 profundos, basta entender que: enquanto o conteúdo antes de um ponto específico for exatamente igual ao conteúdo já em cache, Claude pode reutilizar esses Tokens.

Uma sessão nova geralmente funciona assim:

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

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 escritos no cache.

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

Terceira rodada: o mesmo procedimento. 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 Thariq, do artigo no 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, todo o conteúdo precisa ser re-cacheado do zero. Essa é a operação mais "cara". Imagine: você já chegou na mensagem 16, e de repente muda o prompt do sistema ou para por uma hora. 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 de 1 hora.

Claude API: TTL padrão de 5 minutos. Pode-se pagar mais para aumentar para 1 hora.
Sub-agent 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 era consumido muito rápido. Achavam que a Anthropic tinha reduzido o TTL de 1 hora para 5 minutos sem aviso. Mas, na 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 completamente 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 hábitos que considero realmente úteis no uso diário.

Não pause por muito tempo

Se ficar inativo por mais de uma hora, o conteúdo anterior provavelmente expirou do cache. Sua próxima mensagem vai reconstruir o cache. Nesses casos, é melhor fazer uma transição clara e iniciar uma nova sessão, geralmente mais barato.

Ao trocar de tarefa, reinicie do zero

/compact ou /clear já destroem o cache. Então, é melhor usar esses comandos para realmente resetar.

Criei uma técnica 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 técnica de 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 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 sem aviso?

Algumas ações podem resetar o cache completamente, 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 solicitação recomece do zero, 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á razões para isso. Mas é importante entender que trocar de plano é, na essência, trocar de modelo, o que também reinicia 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 é aplicada 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 dados de Tokens no 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 do Thariq explica de forma mais completa, vale a pena conferir 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 custam 10% do normal; TTL do Claude Code é 1 hora; trocar de modelo quebra o cache; fazer uma transição clara entre tarefas costuma ser mais econômico do que deixar uma sessão antiga "expirar" e continuar nela.

[Link para o artigo original]

Clique para conhecer as vagas na律动BlockBeats

Participe do grupo oficial do律动BlockBeats no Telegram:

Telegram assinatura: https://t.me/theblockbeats

Telegram grupo: https://t.me/BlockBeats_App

Twitter oficial: https://twitter.com/BlockBeatsAsia