O problema dos tokens no Claude Code

Quem usa o Claude Code no dia a dia sabe que o consumo de tokens pode surpreender. Uma sessão de debug que parecia simples vira 50 mil tokens em alguns turnos, e no final do mês a conta não bate com o que você esperava gastar.

Tokens são a unidade de cobrança do Claude Code: cada palavra enviada e recebida, incluindo o contexto acumulado da conversa, conta. E o detalhe que muita gente ignora é que o contexto cresce a cada mensagem, então o que você escreveu no começo da sessão continua sendo cobrado em cada novo turno.

A boa notícia é que existem práticas simples e configurações nativas que reduzem o consumo de forma significativa sem comprometer a qualidade das respostas. Neste post você vai ver 8 dicas concretas que, juntas, podem cortar o gasto de tokens pela metade.

Como o consumo de tokens funciona no Claude Code

Antes das dicas, entender o mecanismo ajuda a aplicar melhor cada técnica. O Claude Code funciona com uma janela de contexto: tudo que foi dito na sessão atual fica disponível para o modelo ler a cada novo turno. Isso inclui suas mensagens, as respostas do Claude, saídas de ferramentas e o conteúdo de arquivos lidos.

O contexto tem um limite físico (cerca de 200 mil tokens no Claude 3.x), mas o custo cresce linearmente com o tamanho. Uma sessão que começa com 1.000 tokens de contexto e vai a 40.000 cobra 40x mais por turno no final do que no começo. É o efeito bola de neve.

O prompt caching do Claude Code ameniza isso: quando o contexto não muda (prefixo idêntico), partes já processadas são reutilizadas a custo reduzido. Mas ele só ativa quando a sessão está estável, então movimentar muito o contexto anula o benefício. Entender isso já muda como você usa a ferramenta.

Dica 1 - Use /compact regularmente

O comando /compact é a ferramenta mais poderosa para controlar o consumo de tokens. Ele comprime o histórico da conversa em um resumo enxuto e reinicia o contexto a partir desse resumo, descartando o verboso acumulado.

O momento ideal para usar é sempre que você concluir uma etapa significativa do trabalho: terminou de implementar uma feature, corrigiu um bug, finalizou uma análise. Antes de começar a próxima tarefa, execute /compact e o contexto fica limpo e pequeno novamente.

O erro comum é esperar até o contexto estar enorme. Nesse ponto a compressão já perdeu eficiência e você já pagou caro por todos os turnos anteriores. Use /compact cedo e frequentemente, especialmente em sessões longas.

Dica 2 - Escolha o modelo certo para cada tarefa

O Claude Code permite trocar de modelo durante a sessão com /model haiku, /model sonnet ou /model opus. Cada modelo tem custo diferente e capacidades diferentes. Usar Opus para ler um arquivo ou fazer um grep é desperdício puro.

A regra prática é simples: use Haiku para leituras, buscas, edições de 1 a 3 linhas e verificações de status. Use Sonnet para features, bugs, refatoração e análise técnica. Reserve Opus para decisões arquiteturais complexas ou quando Sonnet falhou duas vezes seguidas.

Haiku custa cerca de 20 vezes menos que Opus por token. Se 70% das suas interações são leituras e buscas, migrar essas para Haiku já reduz o custo total em mais de 50% sem qualquer perda de qualidade nas tarefas complexas.

Dica 3 - CLAUDE.md enxuto e objetivo

O arquivo CLAUDE.md é carregado em todo turno da sessão. Cada linha que você colocar ali é cobrada em cada mensagem que você enviar durante toda a sessão. Um CLAUDE.md de 500 linhas numa sessão de 30 turnos custa 15.000 tokens extras só de contexto fixo.

A otimização aqui é manter o CLAUDE.md com apenas o que o modelo realmente precisa para tomar decisões: regras de negócio críticas, proibições absolutas, paths de arquivos importantes e convenções técnicas específicas do projeto. Documentação geral, explicações longas e histórico de decisões não pertencem ao CLAUDE.md.

Uma boa prática é revisar o CLAUDE.md a cada semana e remover o que não mudou comportamentos no último período. Se uma regra está lá mas o modelo nunca violou sem ela, provavelmente é ruído. O arquivo ideal tem menos de 100 linhas e zero redundância.

Dica 4 - Escreva prompts cirúrgicos

Prompts vagos custam caro. Quando você escreve 'revise o código' o modelo precisa ler tudo, analisar tudo e responder com muita coisa. Quando você escreve 'no arquivo src/auth.ts linha 47 o token não está sendo invalidado ao fazer logout, corrija apenas essa função', o modelo vai direto ao ponto.

O princípio é: quanto mais específico o prompt, menos contexto o modelo precisa processar e menos tokens ele gasta na resposta. Inclua sempre: arquivo exato, função ou linha quando relevante, o problema específico e o resultado esperado. Evite pedir 'melhore' sem critério, 'revise' sem escopo ou 'análise' sem objetivo.

Prompts específicos também reduzem o número de turnos necessários. Um prompt vago frequentemente gera uma resposta que levanta mais dúvidas, criando dois ou três turnos extras. Um prompt preciso resolve de primeira e a sessão termina mais cedo, com menos contexto acumulado.

Dica 5 - Leitura cirúrgica de arquivos

Toda vez que o Claude Code lê um arquivo com a ferramenta Read, o conteúdo inteiro entra no contexto. Um arquivo de 800 linhas lido para encontrar uma função de 10 linhas custa 790 linhas desnecessárias. E esse custo persiste em todos os turnos seguintes até o /compact.

O hábito correto é usar Grep primeiro, Read depois. Grep retorna apenas as linhas que combinam com o padrão, sem custo de contexto proporcional ao arquivo. Depois de encontrar a linha exata, use Read com offset e limit para ler apenas as 30 linhas ao redor do ponto de interesse.

A mesma lógica vale para Glob: encontre o arquivo exato antes de abri-lo. Nunca leia um arquivo inteiro sem uma pergunta específica para responder. Se você precisa de mais de 50% do arquivo para a tarefa, aí faz sentido ler completo. Senão, sempre cirúrgico.

Dica 6 - Use o sistema de memória para não repetir contexto

Se você começa toda sessão explicando o projeto do zero, está desperdiçando tokens em contexto que poderia estar salvo. O Claude Code tem um sistema de memória persistente (MEMORY.md e arquivos de memory) que carrega automaticamente nas sessões seguintes.

Salve no memory as informações que você vai precisar repetir: arquitetura do projeto, credenciais de ambiente, decisões técnicas fixas, padrões de código adotados, endpoints da API. Na próxima sessão, o modelo já começa com esse conhecimento sem você precisar reexplicar nada.

Mas atenção ao tamanho: o memory é carregado a cada sessão, então o mesmo princípio do CLAUDE.md se aplica. Memory enxuto e relevante. Tudo que é histórico pontual (o que foi feito hoje, lista de commits) não vai no memory, vai no history. Separar bem os dois economiza muito contexto fixo por sessão.

Dica 7 - Agrupe tarefas relacionadas numa sessão só

Abrir uma sessão nova para cada pequena tarefa parece mais organizado, mas no Claude Code cada nova sessão recarrega todo o contexto fixo (CLAUDE.md, memory, instruções do sistema). Se você faz 10 pequenas sessões no dia, paga esse overhead 10 vezes.

O contrário também é verdadeiro: uma sessão que fica aberta por horas acumula contexto sem /compact e fica cara. O ponto de equilíbrio é agrupar tarefas relacionadas numa mesma sessão, fazendo /compact entre cada bloco de trabalho. Você paga o overhead de inicialização uma vez e usa o prompt caching a seu favor dentro da sessão.

Um bom fluxo é: abrir a sessão, trabalhar numa feature, /compact, trabalhar no bug relacionado, /compact, trabalhar nos testes, /compact, fechar. Três /compact dentro de uma sessão custam muito menos do que três sessões separadas.

Dica 8 - Limite a verbosidade das respostas

O Claude Code por padrão tende a ser explicativo. Ele detalha o que vai fazer, explica cada passo, resume o que foi feito no final. Para aprender, isso é ótimo. Para o dia a dia de produção, é tokens extras em cada resposta.

Você pode orientar comportamentos mais secos diretamente no CLAUDE.md do projeto com instruções como: sem preâmbulo, sem resumo ao final, reportar apenas erros e resultado, sem narrar passos intermediários. O Claude Code segue essas instruções de forma consistente e as respostas ficam 30 a 50% menores na média.

Outra prática: quando você só quer confirmar algo, use perguntas fechadas. Ao invés de 'Como está o arquivo X?', use 'O arquivo X tem a função Y? Responda só sim ou não'. Resposta de 2 palavras ao invés de 10 linhas. Para verificações rápidas, a diferença no custo é enorme.

Vale a pena adotar essas práticas?

Sim, e o impacto é mensurável rápido. As dicas de maior retorno imediato são /compact frequente, escolha de modelo por complexidade e prompts específicos. Juntas essas três já reduzem o consumo em 40 a 60% na maioria dos fluxos de trabalho.

As outras dicas (CLAUDE.md enxuto, leitura cirúrgica, memory bem organizado, agrupamento de sessões e controle de verbosidade) têm impacto mais gradual mas composto: conforme o projeto cresce, elas evitam que o custo escale proporcionalmente.

O próximo passo é auditar sua sessão atual: abra o Claude Code, olhe o tamanho do contexto no canto da tela e tente aplicar ao menos as três primeiras dicas ainda hoje. A economia começa no mesmo dia.