Você pede ao Claude Code uma correção pequena. No fim, ele altera cinco linhas — mas usa uma fatia bem maior do seu limite do que você esperava. Em outro dia, ele implementa algo bem mais complexo e a sessão rende muito mais.
Isso parece aleatório, mas não é. O custo de uma sessão depende menos do tamanho do diff e mais do caminho percorrido até chegar nele.
A Anthropic explica essa dinâmica no artigo Maximizing the value of your Claude Code sessions. A ideia central é ótima: usar tokens com eficiência não significa simplesmente usar menos. Significa gastar contexto e raciocínio no problema certo.
Vamos abrir o capô e entender como fazer isso na prática.
Sua conversa vira uma mochila
Quando você inicia uma tarefa, o Claude Code não recebe apenas a última mensagem. A sessão pode carregar instruções do sistema, CLAUDE.md, histórico da conversa, arquivos lidos e saídas de comandos. A documentação do Claude Code chama esse conjunto de janela de contexto.
Imagine uma mochila. No começo, ela está leve. O agente lê dois arquivos, roda testes e encontra um log: tudo isso entra na mochila. A cada nova etapa, ele continua trabalhando com o que já estava ali.
Algumas coisas são úteis — a regra de negócio, o teste que falhou, a decisão arquitetural. Outras viram peso morto — 400 linhas dizendo que testes passaram, uma investigação abandonada ou arquivos lidos apenas para localizar o código correto.
Na inferência, isso acontece em duas fases. O prefill processa a entrada; o decode gera a saída token por token. O curso de LLMs da Hugging Face explica bem essa diferença. Chamadas de ferramentas e tokens de raciocínio também entram na conta, mesmo quando você vê apenas um resumo curto no terminal.
Cache ajuda, mas não faz contexto pesado desaparecer
O Claude Code usa prompt caching. Se o começo de uma nova requisição for idêntico ao anterior, parte desse processamento pode ser reaproveitada.
Uma forma simplificada de pensar no custo é:
custo = entrada nova + escrita de cache + leitura de cache + saída
Essas parcelas têm preços diferentes, que também variam conforme o modelo. Ler conteúdo do cache costuma ser mais barato do que processá-lo novamente como entrada nova.
Agora imagine que você carregou 20 mil tokens de logs e ainda fará outras dez chamadas. Esse bloco poderá participar das dez entradas seguintes: 200 mil tokens acumulados de contexto. Isso não significa que todos serão cobrados como entrada nova — o cache pode atender boa parte deles —, mas o material continua ocupando espaço na janela e disputando atenção com o problema atual.
É como deixar todas as ferramentas espalhadas na bancada depois de encontrar a chave de fenda certa. Elas ainda estão ali, mesmo que você não vá mais usá-las.
Um bom prompt funciona como um atalho
Considere um bug simples de checkout: produtos custam R$ 20, há desconto de 10% e frete de R$ 5. O resultado esperado é R$ 23, mas o sistema retorna R$ 22,50. A pista é clara: provavelmente o desconto está sendo aplicado também ao frete.
Um pedido útil seria:
Em @src/checkout/calculate-total.ts e @tests/checkout/calculate-total.test.ts, investigue este caso: produtos = 20, desconto = 10%, frete = 5; esperado = 23, obtido = 22,50. O desconto deve incidir apenas sobre os produtos. Verifique também a regra de arredondamento, crie um teste de regressão e rode os testes do checkout. Se a causa estiver fora desses arquivos, siga a chamada e explique o que encontrou.
A referência com @ inclui o arquivo na mensagem, como orienta a documentação de boas práticas. Isso pode evitar uma busca ou uma chamada de leitura. Só não fique anexando o mesmo arquivo novamente a cada mensagem: ele já faz parte da conversa.
Modelo, esforço e comandos: escolha antes de acelerar
O bug do desconto é determinístico. Já uma cobrança duplicada que aparece quando dois workers processam o mesmo evento exige investigar concorrência, retries, transações e idempotência. São problemas com níveis de incerteza bem diferentes.
O modelo define a capacidade disponível. O esforço controla quanto raciocínio será aplicado, quando esse recurso é suportado. A documentação de configuração explica os níveis e trade-offs.
Antes de começar, confira /model e /effort. Trocar essas configurações no meio da conversa pode invalidar o cache. Ainda assim, se um bug aparentemente simples revelar uma condição de corrida, aumentar a capacidade pode valer a nova leitura do contexto.
Cuide também dos comandos. Um test runner tagarela pode despejar centenas de linhas na sessão. Para o exemplo do checkout, comece pelo teste específico e use um reporter conciso, se o projeto suportar:
npx vitest run tests/checkout/calculate-total.test.ts --reporter=dotO CLAUDE.md segue a mesma lógica. Coloque nele apenas regras persistentes: comandos que o agente não conseguiria adivinhar, convenções específicas do projeto e decisões arquiteturais importantes. Tutoriais enormes e regras vencidas entram na mochila em todas as sessões. Use /context em uma conversa nova para enxergar o que já está carregado.
/clear, /compact ou /rewind?
Esses comandos resolvem problemas diferentes:
| Situação | Melhor ponto de partida |
|---|---|
| Você terminou um bug e vai começar outra tarefa | /clear |
| A investigação continua, mas já existe muito material acumulado | /compact com instruções específicas |
| Os últimos turnos seguiram uma hipótese errada | /rewind para voltar ao ponto anterior |
Se você descobriu uma condição de corrida, não peça apenas “resuma a conversa”. Diga o que precisa sobreviver:
Preserve a reprodução com dois workers, os testes envolvidos e a evidência de que não existe uma restrição de unicidade. Mantenha as hipóteses descartadas e o motivo. A próxima etapa é validar a transação antes de alterar o retry.
O checkpointing também exige atenção: voltar a conversa ou os arquivos não desfaz efeitos externos. Se a sessão chamou uma API, alterou um banco ou publicou algo, confirme o estado real antes de continuar.
Subagente não é funcionário grátis
Subagentes são ótimos para trabalhos que geram muito material. Eles operam em outra janela de contexto e devolvem uma síntese ao agente principal, conforme explica a documentação.
Imagine milhares de linhas de um incidente de cobrança duplicada. Um subagente pode montar a timeline dos workers enquanto a conversa principal preserva apenas as evidências relevantes para decidir a correção.
Uma boa delegação seria:
Analise os logs do evento indicado. Não altere código. Retorne a timeline das tentativas, os trechos que demonstram processamento simultâneo e as lacunas que ainda impedem confirmar a causa. Inclua referências para o material original.
Mas existe um preço: o subagente também usa tokens, começa sem parte do contexto e pode precisar reler arquivos. Para corrigir o desconto do checkout, seria burocracia. Para filtrar milhares de eventos, pode ser uma ótima divisão de trabalho.
O teste que realmente importa
Na próxima sessão, observe três coisas:
- O agente precisou procurar algo que você já sabia onde estava?
- Algum arquivo ou comando continuou no contexto depois de perder utilidade?
- A solução veio com evidências — teste, build, diff ou reprodução — ou apenas com a frase “corrigido com sucesso”?
Esse pequeno diagnóstico ensina mais do que tentar decorar uma lista de comandos. Se houve busca desnecessária, melhore o ponto de partida. Se o agente implementou rápido sobre uma hipótese errada, forneça uma reprodução melhor. Se a sessão ficou cheia de material antigo, limpe ou compacte no momento certo.
Claude Code funciona melhor quando contexto é tratado como parte da arquitetura do trabalho. O objetivo não é terminar com a sessão mais barata. É chegar a uma solução correta, verificável e com o mínimo possível de trabalho desperdiçado.