Nota do editor: Muitas pessoas que usam o Claude Code sentem que os tokens são consumidos muito rapidamente e que sessões longas facilmente esgotam o limite. Mas, do ponto de vista dos engenheiros da Anthropic, o que realmente afeta o custo não é a quantidade de código que você escreve, mas se o sistema está reutilizando continuamente o contexto já processado.

O ponto central deste artigo é como economizar Token por meio de mecanismos de cache. O autor reutilizou mais de 300 milhões de Token em uma semana, com um volume diário de cache de 91 milhões. Como o custo dos Token em cache é apenas 10% do custo dos Token de entrada normais, isso significa que 91 milhões de Token em cache equivalem a aproximadamente 9 milhões de Token normais em cobrança. A longa duração das conversas do Claude Code não se deve ao fato de o modelo funcionar gratuitamente, mas sim à reutilização bem-sucedida de grande parte do contexto repetido.

A chave para o cache de prompts é "não interromper o cache". O Claude Code armazena em camadas o prompt do sistema, as definições de ferramentas, o CLAUDE.md, as regras do projeto e o histórico de conversas; desde que o prefixo das solicitações subsequentes permaneça consistente, o Claude pode acessar diretamente o cache em vez de processar novamente todo o contexto. A Anthropic também monitora internamente a taxa de reutilização do cache de prompts, pois isso afeta não apenas os créditos do usuário, mas também diretamente os custos do serviço do modelo e a eficiência operacional.

Para usuários comuns, não é necessário entender todos os detalhes subjacentes; basta adotar alguns hábitos essenciais: não deixe a sessão inativa por mais de 1 hora; faça o handoff da sessão ao alternar tarefas; evite alternar frequentemente entre modelos; coloque documentos grandes nos Projects, em vez de colar repetidamente na conversa.

Este artigo não fala tanto sobre uma dica de token de economia, mas sim sobre um método de uso do Claude Code mais próximo do pensamento de engenheiros: tratar o contexto como gestão de ativos, permitir que o cache seja reutilizado continuamente e reduzir cálculos repetitivos em conversas longas.

The following is the original text:

Eu economizei 300 milhões de tokens esta semana, 91 milhões em um único dia, mais de 300 milhões na semana.

Eu não alterei nenhuma configuração. É apenas o cache do prompt funcionando normalmente em segundo plano.

Mas quando realmente compreendi o que é cache e como evitar "quebrar" o cache, minhas sessões duraram muito mais sob o mesmo limite de uso. Por isso, aqui está um guia introdutório de 80/20 sobre cache de prompts do Claude Code, sem detalhes aprofundados no nível da API.

TL;DR

O custo dos tokens em cache é apenas 10% do custo dos tokens de entrada comuns. 91 milhões de tokens em cache correspondem a um custo faturado real equivalente a cerca de 9 milhões de tokens.

O TTL do cache da versão assinada do Claude Code é de 1 hora; o padrão da API é de 5 minutos; o Sub-agent é sempre de 5 minutos.

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

Alternar modelos durante a sessão irá corromper o cache, incluindo o modo "opus plan".

Como é cobrado o cache?

Cada token armazenado em cache custa 10% do valor de um token de entrada comum.

Então, quando meu painel mostra que 91 milhões de tokens foram atingidos em cache em um determinado dia, a cobrança real é aproximadamente equivalente ao processamento de 9 milhões de tokens. É por isso que, em comparação com a ausência de cache, o uso prolongado do Claude Code faz parecer que as sessões são extensas quase que “gratuitamente”.

Há dois números no painel que merecem atenção especial:

Cache create: Custo único gerado ao gravar o conteúdo no cache. Ele começará a ter efeito na próxima conversa.
Leitura do cache: Tokens reutilizados do cache do Claude, como seu CLAUDE.md, definições de ferramentas, mensagens anteriores, etc. Custo 10 vezes menor em comparação ao processamento como entrada nova.

Se o número de Cache read for alto, significa que você está utilizando o cache de forma eficaz; se esse número for baixo, significa que você está pagando repetidamente pelo mesmo conjunto de contextos.

Thariq, da Anthropic, disse uma frase que me marcou: “Na verdade, monitoramos a taxa de acerto do prompt cache, e quando a taxa cai muito, acionamos um alerta ou até declaramos um incidente de nível SEV.”

Ele também escreveu um excelente artigo X. Quando a taxa de acerto no cache é alta, quatro coisas ocorrem simultaneamente: o Claude Code parece mais rápido, o custo dos serviços da Anthropic diminui, seu crédito de assinatura parece mais duradouro e sessões de codificação prolongadas tornam-se mais realistas.

Mas se a taxa de acerto for muito baixa, todos perderão.

Portanto, os incentivos de ambas as partes são na verdade alinhados: a Anthropic deseja que sua taxa de acerto no cache seja maior, e você também deseja que essa taxa seja maior. O que realmente pode atrapalhar são apenas alguns hábitos aparentemente insignificantes, mas que silenciosamente reiniciam o cache.

Como o cache cresce em cada rodada de conversa?

The cache relies on prefix matching, that is, "prefix matching".

Não precisa se aprofundar em detalhes técnicos; você só precisa entender um ponto: desde que o conteúdo anterior a uma determinada posição seja exatamente igual ao conteúdo já armazenado em cache, o Claude pode reutilizar esses tokens em cache.

Uma nova sessão, mais ou menos assim se desenrola:

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

Primeira conversa: ainda não há cache. O prompt do sistema, o contexto do seu projeto (por exemplo, CLAUDE.md, memória, regras) e sua primeira mensagem serão processados novamente e gravados no cache.

Segunda conversa: Todo o conteúdo da primeira conversa já foi armazenado em cache. O Claude precisa apenas processar sua nova resposta e a próxima mensagem. O custo desta rodada será muito menor.

Terceira conversa: lógica idêntica. As conversas anteriores ainda estão armazenadas em cache; apenas a interação mais recente precisa ser processada novamente.

O cache em si pode ser dividido em três camadas:

Artigo do X 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. Esta camada é armazenada em cache globalmente.

Camada de projeto (Project layer): inclui CLAUDE.md, memory, regras do projeto. Esta camada é armazenada em cache por projeto.

Camada de conversa (Conversation): inclui respostas e mensagens que aumentam a cada rodada de conversa.

Se qualquer conteúdo no nível do sistema ou do projeto mudar no meio da sessão, todo o conteúdo precisa ser recarregado do zero. Essa é a operação mais “cara”. Imagine: você já chegou à 16ª mensagem, e de repente o prompt do sistema é alterado, ou a sessão é pausada por uma hora — todos os tokens desde a 1ª mensagem precisam ser processados novamente.

Confusão de 1 hora e 5 minutos

Este é o local mais fácil de ser mal interpretado.

Versão assinada do Claude Code: TTL padrão é de 1 hora.

API do Claude: TTL padrão é de 5 minutos. Você pode pagar um custo maior para aumentá-lo para 1 hora.
Sub-agent em qualquer plano: sempre 5 minutos.

Chat web do Claude.ai: não há registro oficial. Pode ser o mesmo que a versão assinada, mas ainda não confirmei.

Há alguns meses, muitas pessoas reclamaram que os créditos da assinatura do Claude estavam sendo consumidos muito rapidamente. Na época, alguns acreditavam que a Anthropic havia reduzido silenciosamente o TTL de 1 hora para 5 minutos sem notificar os usuários. Mas isso não é verdade; o TTL do Claude Code ainda é de 1 hora.

O problema é que a documentação do Claude Code e da API são separadas, e esses dois elementos são completamente diferentes, o que causou muita confusão.

Se você estiver executando grandes fluxos de trabalho de Sub-agent ou usando diretamente a API, esse número de 5 minutos é importante. Mas para 95% dos usuários do Claude Code, o que realmente importa é apenas a janela de 1 hora.

Três hábitos que cobrem 95% dos usuários

Estes são os elementos que acho realmente úteis no uso diário.

Se você estiver inativo há mais de uma hora, o conteúdo anterior já expirou no cache. Sua próxima mensagem reconstruirá o cache. Neste caso, em vez de continuar recuperando uma sessão antiga já "fria", é geralmente mais barato fazer uma transição clara e iniciar uma nova sessão.

/s2>/compact ou /clear já invalidam o cache, então é melhor aproveitar este momento para redefinir realmente.

Criei uma habilidade de transferência de sessão para substituir /compact. Ela resume o que já concluímos, quais decisões ainda estão em aberto, quais arquivos são mais importantes e de onde devemos continuar em seguida. Depois, executo /clear e coloco esse resumo, permitindo que continuemos como se nada tivesse sido interrompido.

O comando compact às vezes também é lento. Já essa habilidade de handoff geralmente é concluída em menos de um minuto.

O mecanismo de cache no Claude.ai não possui uma explicação oficial detalhada, mas os Projetos claramente utilizam otimizações diferentes das linhas de conversa normais. Portanto, se você precisar colar documentos grandes, é melhor colocá-los em um Projeto, em vez de inseri-los diretamente na conversa.

Quais operações podem destruir silenciosamente o cache?

Há algumas coisas que redefinirão todo o cache sem aviso claro.

Alternar modelo: como o cache depende de correspondência de prefixo e cada modelo tem seu próprio cache, ao alternar o modelo, a próxima solicitação lerá novamente o histórico completo sem nenhum acerto no cache.

Modo "Opus plan": esta configuração usa o Opus durante a fase de planejamento e o Sonnet durante a fase de execução. Eu já recomendei isso em alguns vídeos de otimização de tokens, e há uma razão para isso. Mas é importante entender que cada mudança de plano é, essencialmente, uma troca de modelo, o que significa que o cache precisa ser recriado. A longo prazo, ainda assim ajuda a estender o crédito da sessão, mas você precisa saber o que está acontecendo por baixo dos panos.

É possível editar CLAUDE.md durante a sessão: essa modificação não entrará em vigor imediatamente, mas somente após a próxima reinicialização. Portanto, o cache atualmente em execução não será afetado.

As capturas de tela que apresentei anteriormente são de um painel de token.

Este é um repositório GitHub muito simples. Você fornece o link ao Claude Code, que realiza o deploy localmente no localhost; ele então lê todos os seus registros de sessões anteriores, em vez de começar do zero. Assim que você iniciar, poderá ver os dados diários de input, output, cache create e cache read.

No entanto, há um ponto a ser observado: este painel estatístico contabiliza os dados de Token no dispositivo local. Se você mudar de um computador de mesa para um notebook, os números não serão exatamente os mesmos. Cada dispositivo possui seu próprio conjunto de visualizações estatísticas.

Resumo

O cache de prompts é algo que pode ser estudado aprofundadamente. O artigo do Thariq aborda isso de forma mais completa; se quiser ver a visão geral, vale a pena ler.

Mas você não precisa entender todos os detalhes para se beneficiar. Basta dominar os 80/20 mais importantes: o Token em cache é 10 vezes mais barato do que o Token comum; o TTL do Claude Code é de 1 hora; alternar modelos destrói o cache; fazer uma transição clara entre tarefas geralmente é mais vantajoso do que continuar usando uma sessão antiga até ela “expirar”.