Como Reduzir os Custos de Tokens do Claude Code: Guia Prático da Anthropic para Sessões Eficientes

Introdução

A Anthropic publicou um guia prático para desenvolvedores que desejam obter mais valor de cada sessão do Claude Code.

A mensagem central é simples: a mesma tarefa de codificação pode custar valores muito diferentes dependendo de como você gerencia a sessão.

O Claude Code não é como um editor tradicional com custo fixo por tarefa. Cada solicitação ao modelo tem um custo de inferência, e conversas longas carregam repetidamente arquivos, resultados de ferramentas, saídas de comandos, instruções do sistema e mensagens anteriores. Se esse contexto for mal gerenciado, uma simples correção de bug pode acabar consumindo muito mais tokens do que o necessário.

O artigo original destilou os conselhos em seis hábitos práticos:

1. Execute /clear quando uma tarefa terminar e você for passar para outra.
2. Escolha o modelo e o nível de raciocínio no início da sessão, em vez de alternar repetidamente no meio.
3. Use @ para referenciar arquivos diretamente, em vez de fazer o Claude procurá-los.
4. Adicione sinalizadores silenciosos a comandos que, de outra forma, produzem grandes volumes de saída.
5. Execute /compact antes de uma pausa longa, enquanto o cache de prompt existente ainda está ativo.
6. Envie trabalhos de investigação grandes e ruidosos para um subagente, para que seu contexto intermediário não se acumule na conversa principal.

O próprio resumo da Anthropic também recomenda executar /context em uma sessão nova para ver o que já está carregado, incluindo CLAUDE.md e definições de ferramentas MCP.

Essas sugestões fazem mais sentido quando você entende o que acontece com um token dentro de uma sessão do Claude Code.

O Ciclo de Vida de um Token

O Claude Code pode ser usado por meio de planos pagos do Claude ou pelo uso de API com medição. Para usuários individuais, o Claude Pro custa atualmente US$ 20 por mês com cobrança mensal, enquanto o Claude Max começa em US$ 100 por mês e também oferece um nível de uso mais alto. O uso da API é cobrado separadamente, de acordo com o modelo e o volume de tokens.

A documentação de custos do Claude Code da Anthropic afirma que, em implantações empresariais, o uso médio é de cerca de US$ 13 por desenvolvedor por dia ativo e aproximadamente US$ 150–250 por desenvolvedor por mês, embora os custos reais variem substancialmente com o modelo, o código-base, o fluxo de trabalho e o nível de automação.

A mesma tarefa pode custar várias vezes mais se o Claude precisar procurar em arquivos desnecessários, executar comandos verbosos ou carregar repetidamente contexto irrelevante.

Para entender por que isso acontece, ajuda separar

cada solicitação em duas fases.

Prefill: Lendo a Entrada

Durante o prefill, o modelo lê a solicitação e seu contexto em uma única passada.

Essa entrada pode incluir:

• Definições de ferramentas
• O prompt do sistema
• CLAUDE.md
• Sua mensagem atual
• Histórico de conversas anteriores
• Arquivos que o Claude leu
• Saídas de comandos e ferramentas já adicionadas à sessão

Tudo isso conta como tokens de entrada.

Decode: Produzindo a Saída

Durante o decode, o modelo gera sua resposta token por token.

Isso inclui tokens de raciocínio, chamadas de ferramentas e o texto que você eventualmente vê. Diferentemente do prefill, a decodificação é sequencial: uma resposta de 200 tokens exige que o modelo gere 200 tokens um após o outro.

É por isso que os tokens de saída costumam ser muito mais caros que os de entrada. Para os modelos Claude atuais discutidos aqui, o preço da saída é cinco vezes o preço base da entrada.

Os preços padrão atuais da API são:

MTok significa um milhão de tokens.

A outra grande variável é o nível de esforço. Grande parte da saída gerada em uma sessão de codificação agêntica pode ser raciocínio. Um esforço maior permite que o modelo gaste mais tokens pensando em um problema difícil, enquanto um esforço menor pode ser mais adequado para tarefas rotineiras.

A regra prática é simples: use um modelo mais forte e maior esforço quando o problema for genuinamente difícil ou ambíguo, não automaticamente para toda tarefa pequena.

Cache de Prompt É a Maior Alavanca de Custo

O cache de prompt é uma das partes mais importantes do modelo de custo do Claude Code.

Toda solicitação do Claude Code começa com uma grande quantidade de material repetido: definições de ferramentas, o prompt do sistema, CLAUDE.md e o histórico de conversa acumulado até o momento.

Se o início de uma nova solicitação corresponder exatamente a uma solicitação recente, o servidor pode reutilizar o estado previamente calculado em vez de processar todo o prefixo compartilhado novamente.

Uma leitura de cache custa apenas 0,1× o preço normal do token de entrada.

As gravações de cache são mais caras que a entrada normal porque o servidor precisa armazenar o estado calculado. Uma gravação padrão de cache de cinco minutos custa 1,25× o preço base de entrada, enquanto uma gravação de cache de uma hora custa 2×. O ponto importante é que a gravação ocorre uma vez, enquanto os acertos subsequentes de cache podem reutilizar repetidamente o prefixo a um décimo do custo normal de entrada.

Imagine que uma conversa já contém 50.000 tokens de histórico. Sem um acerto de cache, o modelo teria que fazer o prefill de todo esse histórico à taxa normal de entrada na próxima solicitação. Com um cache válido, o prefixo compartilhado é lido a 0,1× a taxa base e apenas o novo

o material anexado precisa ser processado ao preço integral de entrada.

Ao longo de um longo loop de agente, essa diferença pode se tornar substancial.

O Que Quebra o Cache?

O cache precisa corresponder continuamente desde o início da solicitação. Se algo mudar perto do início desse prefixo — ou alterar parte da chave do cache — o histórico restante não pode mais ser reutilizado da mesma forma.

O artigo de origem destaca seis casos comuns.

1. Alterar o modelo com /model
2. Cada modelo tem um cache separado. Mudar de um modelo para outro significa que o próximo turno precisa pré-processar a conversa existente novamente para o novo modelo.
3. Alterar o esforço de raciocínio com /effort
4. O nível de esforço faz parte da chave do cache. Alterá-lo no meio de uma sessão pode forçar a conversa a ser processada novamente.
5. Ativar o Modo Rápido
6. O Modo Rápido também altera a chave do cache. A Anthropic recomenda ativá-lo no início se você planeja usá-lo. Desativar o Modo Rápido novamente não incorre na mesma penalidade de cache.
7. Executar /compact
8. A compactação reescreve a conversa em um resumo mais curto. A conversa antiga não corresponde mais, então o cache da conversa anterior não pode simplesmente continuar.
9. Deixar o cache expirar
10. Nas assinaturas do Claude Code, a Anthropic afirma que o cache de prompt expira após uma hora de inatividade. Com uma chave de API, o TTL padrão é de cinco minutos, a menos que o cache de uma hora seja explicitamente ativado.
11. Retomar uma sessão antiga
12. Uma sessão antiga geralmente não terá mais um cache ativo, e o prompt do sistema é reconstruído quando o Claude Code é iniciado. A próxima solicitação, portanto, muitas vezes exige um pré-processamento completo do zero.

Isso não significa que você nunca deve alterar modelos, esforço ou compactar uma conversa. Significa que há momentos mais baratos para fazer isso: no início de uma sessão ou logo após /clear, em vez de no meio de um contexto longo e caro.

Há também um caso menos óbvio no modo opusplan. A Anthropic observa que entrar ou sair do modo de planejamento pode alternar modelos, então cada transição pode invalidar o cache do modelo relevante.

Por Que /compact É Mais Barato Antes de uma Pausa

/compact resume a conversa atual em uma versão muito mais curta.

Como produzir esse resumo exige ler o contexto existente, é mais barato compactar enquanto a conversa ainda está disponível através do cache de prompt. Se você esperar até depois de uma longa pausa e o cache tiver expirado, o Claude pode precisar ler a conversa inteira ao custo normal de entrada antes de poder resumi-la.

É por isso que a Anthropic recomenda compactar antes de você se afastar do teclado por um período prolongado.

Sua Sessão Está Silenciosamente Ficando Maior

O cache de prompt torna o contexto repetido mais barato, mas não impede que o próprio contexto cresça.

Toda vez que o Claude lê um arquivo, o conteúdo do arquivo é adicionado à conversa. Toda vez que ele executa um comando, a saída também pode ser adicionada. A partir desse ponto, os turnos posteriores continuam carregando esse material.

O turno 40 não é apenas a solicitação mais recente. Ele também carrega grande parte do que aconteceu nos turnos de 1 a 39.

É por isso que sessões longas podem acumular custos muito mais rápido do que os desenvolvedores esperam. Mesmo quando o histórico antigo é

em cache, carregar repetidamente contexto irrelevante não é gratuito, e também consome espaço na janela de contexto.

O Claude Code possui uma proteção para saídas extremamente grandes do Bash. A documentação atual da Anthropic afirma que quando a saída de um comando excede 30.000 caracteres, o Claude Code escreve a saída em um arquivo e mantém apenas uma prévia curta e o caminho na conversa.

O caso complicado é quando a saída é ruidosa, mas ainda abaixo desse limite.

Uma suíte de testes que imprime centenas de linhas de testes bem-sucedidos pode permanecer abaixo de 30.000 caracteres. Se for esse o caso, essas linhas podem permanecer na conversa e continuar sendo enviadas em turnos posteriores.

A Anthropic, portanto, recomenda manter ativamente o contexto de trabalho enxuto.

1. Referencie Arquivos com @

Se você sabe qual arquivo o Claude precisa, referencie-o diretamente.

Em vez de pedir ao Claude para localizar um arquivo pelo nome, use uma menção com @ para que o arquivo seja anexado à mensagem desde o início.

Compare estes prompts conceitualmente:

Os testes estão falhando.

O Claude pode precisar pesquisar o repositório, inspecionar vários arquivos e coletar vários resultados de ferramentas antes de chegar ao problema real.

Uma solicitação mais específica elimina parte dessa exploração:

Corrija o teste com falha em utils.test.ts.

E uma referência @ pode evitar a chamada separada de Leitura:

Corrija o teste com falha em @utils.test.ts.

O arquivo ainda ocupa contexto de qualquer forma. A economia vem de evitar buscas e leituras desnecessárias.

Também evite anexar o mesmo arquivo repetidamente em uma única conversa. Uma vez que um arquivo entrou no contexto, mencioná-lo novamente pode adicionar outra cópia.

1. Adicione Flags Silenciosas a Comandos Ruidosos

A saída repetida de comandos pode silenciosamente dominar uma sessão.

Para comandos que você executa constantemente, coloque uma versão concisa no CLAUDE.md para que o Claude saiba da invocação de menor ruído desde o início.

Por exemplo:

execute um único arquivo de teste com npx vitest run  --reporter=dot

Um reporter dot pode retornar apenas um resultado compacto em vez de centenas de linhas de saída detalhada.

Esta é uma pequena mudança de configuração, mas ao longo de muitos turnos pode economizar uma grande quantidade de contexto repetido.

1. Isole Trabalho de Alta Saída em um Subagente

Um subagente tem sua própria janela de contexto.

Ele tem seu próprio prompt de sistema, ferramentas e CLAUDE.md, mas não herda toda a conversa principal. Ele pode inspecionar logs, executar comandos, pesquisar histórico ou ler um arquivo grande e retornar apenas a resposta à sessão pai.

Isso é útil para tarefas como:

• “Revise este log de build e me diga o que está errado.”

• “Pesquise neste arquivo grande e relate a seção relevante.”

• “Execute a suíte de testes completa e retorne as falhas importantes.”

• “Inspecione o histórico do Git e resuma a alteração que introduziu esse comportamento.”

As leituras de arquivos intermediárias e as saídas de comando desaparecem quando o subagente termina. Apenas a resposta retornada por ele entra na sessão principal.

Há uma compensação: como o subagente não herda a conversa do pai, ele pode precisar reler material que a sessão principal já conhece. Para tarefas pequenas, essa sobrecarga pode tornar um subagente menos eficiente. Vale a pena quando a tarefa isolada é ruidosa o suficiente para que você não queira que o processo dela permaneça no contexto principal.

1. Use /clear Quando a Tarefa Mudar

Este é um dos hábitos mais simples e valiosos.

Quando terminar uma correção de bug e iniciar uma tarefa diferente, execute:

/clear

As leituras de arquivos, saídas de comando, abordagens falhas e contextos temporários da tarefa anterior não precisam mais acompanhar cada turno subsequente.

A própria comparação da Anthropic mostra que manter três tarefas separadas em uma única sessão contínua pode enviar consideravelmente mais tokens do que limpar entre as tarefas.

Se você precisar preservar a sessão antiga para depois, a Anthropic recomenda usar /rename antes de /clear.

Se você ainda está trabalhando na mesma tarefa e só precisa compactar a parte mais antiga da conversa, /compact é a ferramenta mais adequada.

Use /rewind Quando Apenas os Últimos Turnos Deram Errado

Há outra opção útil que é fácil de ignorar:

/rewind

Se a sessão só saiu do trilho nos últimos turnos, rebobinar pode remover esses turnos sem reescrever toda a conversa anterior.

Isso importa para o cache. A Anthropic diz que a parte anterior ao ponto de rebobinar pode permanecer em cache, enquanto o /compact reescreve a conversa e, portanto, tem seu próprio custo.

Então, os três comandos servem a propósitos diferentes:

Gerenciar Tokens Está se Tornando uma Habilidade de Desenvolvedor

Uma vez que esses mecanismos ficam claros, um padrão mais amplo emerge.

A codificação eficiente assistida por IA agora exige um novo tipo de julgamento operacional. Os desenvolvedores precisam saber não apenas como escrever e depurar código, mas também:

• Qual modelo é apropriado para a tarefa
• Quanto esforço de raciocínio é justificado
• O que pertence ao contexto ativo
• Quando uma sessão deve ser limpa ou compactada
• Quais trabalhos devem ser movidos para subagentes
• Quais comandos produzem saída desnecessária
• Que mudanças invalidarão um cache de prompt

Um ano atrás, essas decisões quase não existiam no desenvolvimento de software do dia a dia. Agora, elas podem determinar se dois desenvolvedores pagam valores muito diferentes para concluir essencialmente o mesmo trabalho.

A própria Anthropic ilustra o quão importante isso é em escala.

A empresa relatou em 2026 que mais de 80% do código mesclado no código-fonte da Anthropic foi escrito por Claude, e que o engenheiro típico

estava mesclando cerca de 8× mais código por dia do que em 2024. Em um benchmark interno separado de otimização, um sistema baseado em Claude progrediu de aproximadamente 3× de aceleração em 2025 para cerca de 52× em abril de 2026.

Nesse nível de uso de IA, a eficiência de inferência não é um detalhe contábil irrelevante.

A lição mais profunda do guia da Anthropic, portanto, não é apenas "gaste menos tokens". É entender para onde os tokens estão indo e garantir que sejam gastos em raciocínio útil, alterações de código e trabalho com ferramentas, em vez de histórico obsoleto e saída evitável.

Perguntas Frequentes

Por que o Claude Code fica mais caro durante sessões longas?

Cada novo turno carrega o histórico de conversa relevante, incluindo mensagens, arquivos, chamadas de ferramentas e saída de comandos. O cache de prompt torna prefixos repetidos muito mais baratos, mas o contexto crescente ainda consome tokens e capacidade da janela de contexto.

Quanto o cache de prompt do Claude pode economizar?

Uma leitura do cache de prompt é cobrada a 0,1× o preço normal do token de entrada base, o que representa uma redução de 90% para essa parte em cache da entrada. Gravações de cache custam mais do que entradas normais, mas leituras repetidas de cache podem compensar rapidamente o custo inicial da gravação.

Devo usar /clear ou /compact no Claude Code?

Use /clear quando estiver mudando para uma tarefa diferente e não precisar mais do contexto atual. Use /compact quando estiver na mesma tarefa, mas quiser que o Claude resuma o histórico de conversa mais antigo em um contexto de trabalho menor.

O que o /rewind faz no Claude Code?

O /rewind permite que você volte a uma mensagem anterior e remova os turnos seguintes do contexto ativo. É útil quando apenas a parte mais recente da conversa seguiu na direção errada e você não precisa compactar ou limpar toda a sessão.

Alterar o modelo Claude aumenta o custo de tokens?

Pode aumentar. Cada modelo usa um cache de prompt separado, portanto, alternar modelos no meio de uma conversa longa pode forçar o histórico existente a ser processado novamente ao preço integral de entrada do novo modelo.

Por que devo usar @ ao referenciar um arquivo?

Uma referência de arquivo com @ anexa o arquivo diretamente à mensagem, o que pode evitar que o Claude procure o arquivo ou faça uma chamada adicional de Leitura. O conteúdo do arquivo ainda consome contexto, então o benefício é evitar etapas desnecessárias de descoberta, não tornar o arquivo em si gratuito.

Quando devo usar um subagente do Claude Code?

Use um subagente para trabalhos que produzem muita saída intermediária que você não precisa na conversa principal, como inspecionar logs ou executar uma busca ampla. O subagente trabalha em um contexto separado e envia apenas sua resposta final de volta à sessão principal.

Como posso verificar o que já está consumindo contexto?

Execute /context em uma nova sessão do Claude Code. A Anthropic recomenda usá-lo para inspecionar o contexto de inicialização, como CLAUDE.md e definições de ferramentas MCP, para que você possa remover instruções ou integrações de que não precisa.

Ferramentas Relacionadas

• Claude Code: a ferramenta de codificação agêntica da Anthropic para trabalhar com bases de código a partir do terminal, IDE, web e outros ambientes compatíveis.
• Claude: a principal interface de assistente e entrada de conta da Anthropic.

ponto para planos do Claude que incluem o Claude Code.

• Claude Agent SDK: O SDK expõe o mesmo loop de agente, ferramentas e fundamentos de gerenciamento de contexto usados pelo Claude Code.
• Vitest: Um framework de testes JavaScript usado no exemplo da Anthropic para reduzir a saída de testes ruidosa com --reporter=dot.

Links Relacionados

• Maximizando o Valor das Suas Sessões do Claude Code: Guia oficial da Anthropic de agosto de 2026 que forma a base técnica deste artigo.
• Gerenciamento de Custos do Claude Code: Documentação oficial para rastrear uso, controlar gastos e reduzir o consumo de tokens.
• Preços da API do Claude: Preços atuais de modelos, cache de prompt, modo rápido e API.
• Documentação sobre Cache de Prompt: Explicação oficial sobre TTLs de cache, multiplicadores de gravação, leituras de cache e comportamento de implementação.
• Gerenciamento de Sessões do Claude Code: Guia da Anthropic para escolher entre continuar, retroceder, compactar e limpar uma sessão.
• Escolhendo um Modelo e Nível de Esforço do Claude: Orientação sobre como combinar a capacidade do modelo e o esforço de raciocínio com a dificuldade da tarefa.
• Cache de Prompt é Tudo: Lições de engenharia da Anthropic sobre como preservar a eficiência do cache de prompt em fluxos de trabalho agênticos.
• Quando a IA se Constrói a Si Mesma: Relatório da Anthropic sobre código interno escrito por IA, produção de engenharia e experimentos de otimização orientados por modelos.

Resumo

Os custos do Claude Code são moldados por mais do que apenas o preço do modelo. Comprimento do contexto, esforço de raciocínio, saída de comandos, duração da sessão, acertos de cache, descoberta de arquivos e uso de subagentes podem todos alterar quantos tokens uma tarefa consome.

Os hábitos de maior valor são simples: limpe o contexto quando a tarefa mudar, evite trocas desnecessárias de modelo ou esforço no meio da sessão, mantenha a saída ruidosa curta, referencie arquivos conhecidos diretamente, compacte antes de uma pausa longa e isole trabalhos de alta saída quando um subagente for mais apropriado.

Essas práticas não visam minimizar o uso de tokens a qualquer custo. Elas visam garantir que os tokens pelos quais você paga estejam contribuindo para a tarefa, em vez de carregar repetidamente histórico irrelevante.

O uso eficiente do Claude Code é cada vez mais uma forma de engenharia de contexto: mantenha o contexto relevante, preserve o cache quando ele ajudar e gaste raciocínio onde ele realmente melhora o resultado.