Claude Code Avançado: Otimização de Tokens e Domínio do Contexto em Bases de Código Grandes (2026)

- Os comandos e números deste artigo vêm da documentação oficial da Anthropic (consultada em 2026-08-20). O Claude Code é atualizado com muita frequência, então confira claude --version e rode /usage de novo na sua própria máquina para comparar.

Por que o Claude Code queima tokens em uma base de código grande?

Muitos devs ficam frustrados: "uma perguntinha e o meu consumo sobe o dia inteiro". A causa não é a pergunta - é como os modelos de linguagem funcionam: toda requisição reenvia a conversa inteira (system prompt, CLAUDE.md, histórico, arquivos lidos, resultados de ferramentas) como entrada. Quanto mais longa a sessão, mais caro fica cada troca, porque esse contexto que se arrasta atrás não para de crescer.

Três mecanismos se somam para elevar o custo:

• Acúmulo de contexto longo: quanto mais arquivos você puxa para o contexto, mais pesada fica cada rodada seguinte - mesmo que você nunca mais toque nesses arquivos.
• Deterioração de contexto (context rot): segundo o artigo da Anthropic Effective context engineering for AI agents (2025-09-29), à medida que o número de tokens na janela cresce, a capacidade do modelo de recuperar informação importante na verdade cai. Ou seja, um contexto inchado não é só mais caro, ele também deixa o Claude menos preciso.
• Cache misses: o Claude Code faz cache do início do prompt para você não ser cobrada por ele de novo. Mas o cache expira; se você se afasta por muito tempo e volta, o bloco de contexto inteiro é cobrado a preço cheio outra vez.

Sobre o custo base, a documentação "Manage costs effectively" da Anthropic (docs, consultada em 08/2026) informa uma média de mais ou menos ~US$ 13/dev por dia ativo, com a maior parte do uso ficando entre US$ 150-250/mês, e 90% dos usuários abaixo de ~US$ 30/dia. Se você está passando bem disso em uma base grande, quase com certeza há gasto de tokens desperdiçado em alguns pontos previsíveis. Para entender os planos e como funciona a cobrança, veja o nosso guia de preços e planos do Claude Code. E se você está só começando, leia antes o que é o Claude Code para pegar o básico.

Meça primeiro, otimize depois - /context, /usage, statusline

Não otimize no escuro. Antes de mexer em qualquer técnica, tire uma foto do estado atual para saber para onde seus tokens estão indo. Estes dois comandos são o ponto de partida:

/usage # token & cost overview: input, output, cache read/write, cost
/context # breaks down what is taking up your CURRENT context right now

O /usage te dá o retrato do dinheiro: quantos tokens de entrada, de saída, quanto foi lido do cache (barato) versus escrito em um cache novo (caro). Uma proporção alta de leitura de cache é um bom sinal. O /context é o mais valioso dos dois quando você está otimizando: ele separa o system prompt, o CLAUDE.md, as ferramentas de MCP que você declarou e os arquivos que você puxou - mostrando exatamente o que está ocupando espaço.

O /usage tem um formato de saída específico que vale a pena conhecer, por exemplo o bloco Session:

Total cost:            $0.55
Usage by model:
   claude-sonnet-4-6:  1.2k input, 5.3k output, 940.0k cache read, 50.0k cache write ($0.55)

Nos planos Pro/Max/Team/Enterprise, o /usage também mostra um Plan usage breakdown: a Attribution atribui o uso recente a skills, subagents, plugins e servidores MCP individuais - cada um exibido como porcentagem do total; os Behavior flags avisam quando contexto longo ou cache misses respondem por 10% ou mais do uso recente. Pressione d/w para alternar entre a visão de 24 horas e a de 7 dias.

Para aprender sobre como você trabalha (não só quanto você gastou), rode /insights - ele analisa até as suas 200 sessões mais recentes nesta máquina e escreve um relatório HTML em ~/.claude/usage-data/report.html cobrindo pontos de atrito e sugestões para usar o Claude Code de forma mais eficaz. Ele complementa o /usage, não substitui.

Você também deveria habilitar uma leitura de contexto na sua statusline para acompanhar continuamente sem digitar um comando - os detalhes estão no nosso guia de como personalizar a statusline do Claude Code. A regra: só os números de antes/depois te dizem qual técnica realmente valeu o esforço. Rode /context logo antes e logo depois de cada mudança abaixo para medir o delta de verdade.

Grupo 1 - Gestão proativa de contexto (/clear, /compact, resume)

Essa é a alavanca mais barata e de maior impacto que existe. A maior parte dos tokens desperdiçados vem de arrastar contexto velho e sem relação para uma tarefa nova.

/clear entre tarefas sem relação. Acabou de corrigir um bug no módulo de autenticação e agora vai escrever testes para o módulo de pagamento? Digite /clear. Ele reseta o contexto para o começo - o custo da "cauda da conversa" volta para perto de US$ 0 na nova tarefa. Esse é o hábito de economia de tokens mais importante e que a maioria das pessoas pula.

/compact quando você precisa manter o fio da meada. Quando você quer continuar a mesma linha de trabalho mas o contexto inchou, o /compact comprime a conversa em um resumo. Importante: use um compact direcionado para não perder exatamente o que você precisa:

/compact Keep the database schema decisions and the files changed in the payment module; drop the long debug logs

Você pode predefinir "Compact instructions" no CLAUDE.md para que todo compact mantenha as mesmas prioridades. O Claude Code também tem auto-compact: quando o contexto chega perto do limite, ele compacta sozinho para a sessão não quebrar. Conveniente, mas um aviso honesto - o auto-compact pode descartar detalhes, então para tarefas sensíveis rode um compact manual direcionado em vez de deixar por sorte.

Retome a partir do resumo. Ao reabrir uma sessão grande, escolha retomar a partir do resumo em vez de recarregar o histórico inteiro - você começa com alguns milhares de tokens em vez de dezenas de milhares. Para se aprofundar nesse mecanismo, leia o nosso guia de gerenciar contexto e memória no Claude Code.

Grupo 2 - Escolha o modelo certo & ajuste o extended thinking

Nem toda tarefa precisa do modelo mais forte. Veja como distribuir por custo (preços de referência da API: Opus 5 US$ 5/US$ 25 por 1M de tokens entrada/saída; Sonnet 5 US$ 2/US$ 10; Haiku 4.5 US$ 1/US$ 5):

• Sonnet para a maior parte da programação. O Sonnet 5 dá conta da imensa maioria da escrita e edição de código por uma fração do custo do Opus.
• Guarde o Opus para arquitetura & problemas difíceis. Troque com /model no meio da sessão quando bater em algo que exige raciocínio profundo, e depois volte para o Sonnet.
• Haiku para subagents simples. Para um subagent que faz trabalho puramente mecânico (grep, resumir, formatar), defina model: haiku na definição dele.

O extended thinking é uma faca de dois gumes para os tokens. O "pensamento" é cobrado como tokens de saída - e a saída custa várias vezes mais que a entrada. Em tarefas simples e repetitivas, pensar demais é só queimar dinheiro. Como controlar:

/effort # tune the reasoning effort to fit the task
MAX_THINKING_TOKENS=8000 # cap thinking tokens (environment variable)

Você também pode desligar o extended thinking no /config. Uma ressalva honesta: desligar o pensamento prejudica tarefas de raciocínio profundo (design de algoritmos, depuração em várias camadas) - isso é um trade-off, não uma regra de "sempre desligado para economizar". Só reduza ou desligue quando a tarefa genuinamente não precisar de muito raciocínio.

Grupo 3 - Enxugue a sobrecarga de MCP & de ferramentas

Correção: o Claude Code agora adia as definições de ferramentas MCP por padrão - só os nomes das ferramentas ficam no contexto de cara, e a descrição completa mais o schema de parâmetros só carregam quando o Claude de fato usa aquela ferramenta. Então o verdadeiro "imposto" de contexto são duas coisas: (a) versões antigas do Claude Code ou sessões com a busca de ferramentas desativada ainda carregam tudo de cara; e (b) um servidor com um número muito grande de ferramentas ainda pesa só pelos nomes, mais um custo único na primeira vez que uma ferramenta é chamada. Use o /context para inspecionar isso.

• Desative os servidores que você não está usando: /mcp para ver e gerenciar os servidores conectados; desligue o que você não precisa na sessão atual.
• Prefira CLIs a MCP quando der. Para tarefas que já têm uma ferramenta de linha de comando - gh (GitHub), aws, gcloud - deixe o Claude chamar a CLI direto pelo Bash em vez de montar um servidor MCP equivalente. Uma CLI não carrega o custo permanente de "listagem de ferramentas" no contexto.
• Inteligência de código para linguagens tipadas. Para TypeScript/Java/Go, um plugin de "go to definition" deixa o Claude pular direto para uma definição em vez de fazer grep e ler uma pilha de arquivos - cortando de forma significativa os tokens de leitura de arquivo em uma base grande.

Para entender o MCP e quando usá-lo ou não, veja o texto sobre hooks no Claude Code no próximo grupo - esses dois mecanismos muitas vezes trabalham juntos para reduzir contexto.

Grupo 4 - Descarregue o trabalho pesado em hooks & skills

Esse é o grupo com o maior retorno que menos gente aproveita. A ideia: não deixe a saída volumosa fluir direto para o contexto do Claude - filtre ou resuma primeiro, na camada de script.

Um hook para filtrar a saída dos testes. Uma rodada de uma suíte grande de testes pode imprimir dezenas de milhares de linhas - mas o Claude só precisa saber o que FALHOU. Um hook de PreToolUse/pós-processamento que mantém só as linhas FAIL/ERROR pode puxar a contagem de tokens de dezenas de milhares para centenas (segundo a documentação "Manage costs effectively"). Exemplo de esqueleto de um script de filtro:

#!/usr/bin/env bash
# filter-test-output.sh - keep only failing lines, cut the noisy log
npm test 2>&1 | grep -E "(FAIL|ERROR|✕|Error:|Expected|Received)" | head -n 100

Uma skill de "codebase-overview". Em vez de fazer o Claude ler 20 arquivos para entender a estrutura do projeto toda vez, empacote uma skill que descreve a arquitetura, as convenções e onde ficam os módulos principais. Uma skill carrega sob demanda, então não fica permanentemente no contexto - mas, quando necessário, dá contexto instantâneo em vez de uma enxurrada de leituras de arquivo.

Mantenha o CLAUDE.md enxuto. A documentação da Anthropic recomenda manter o CLAUDE.md abaixo de ~200 linhas. Tudo neste arquivo carrega em toda requisição, então lotá-lo é um imposto de tokens permanente. Mova instruções especializadas (um procedimento de deploy, as convenções de um módulo) para uma skill sob demanda, e deixe no CLAUDE.md só o que você realmente usa em toda sessão.

Grupo 5 - Subagents & recuperação just-in-time para bases de código grandes

Em um monorepo, o inimigo número um é deixar um único contexto "varrer" o repositório inteiro. A solução é isolar a leitura pesada para longe do contexto principal.

Delegue a pesquisa a um subagent. Quando você precisa levantar "onde a funcionalidade X está implementada", entregue isso a um subagent. Ele lê um monte de arquivos no próprio contexto e devolve só um resumo - segundo o artigo de engenharia da Anthropic, normalmente apenas ~1.000-2.000 tokens em vez de despejar o conteúdo completo dos arquivos no contexto principal. Veja o passo a passo detalhado no nosso guia de subagents no Claude Code.

Recuperação just-in-time com referências @. Não deixe o Claude adivinhar e sair fazendo grep às cegas. Aponte direto para o que ele precisa, quando ele precisa:

@src/payment/checkout.ts # load exactly one file when needed
@src/payment/ # load exactly one directory

Plan mode para evitar retrabalho caro. Pressione Shift+Tab para entrar no plan mode: o Claude planeja antes de editar. Revisar um plano é bem mais barato do que deixá-lo editar errado um monte de arquivos e depois ter que refazer o trabalho - e cada loop de refação custa tokens. Se ele for para o lado errado, use /rewind (ou pressione Esc duas vezes) para voltar a um checkpoint anterior em vez de descrever tudo do zero de novo.

O princípio que amarra esse grupo inteiro, emprestado da Anthropic: mire em tokens mínimos de alto sinal - coloque o mínimo possível no contexto, mas exatamente as partes mais valiosas. Essa é também a cura para a deterioração de contexto mencionada no início do artigo.

Grupo 6 - Advisor: uma segunda opinião sem rodar o modelo forte o dia inteiro

O advisor combina o seu modelo principal com um segundo, em geral mais forte - o Claude decide quando consultá-lo, tipicamente antes de se comprometer com uma abordagem, diante de um erro recorrente, ou antes de declarar uma tarefa concluída, e não a cada rodada. Essa é uma técnica genuína de otimização de tokens: sai significativamente mais barato do que rodar o modelo forte a sessão inteira.

Habilite com /advisor opus (ou outro modelo), defina advisorModel nas suas configurações, ou passe --advisor para uma única sessão. Desligue com /advisor off.

Mecânica de custo: cada chamada é cobrada pela tarifa do modelo advisor, por cima do uso do seu modelo principal. Nos planos de assinatura, o uso do advisor conta nos limites do seu plano como tudo o mais - exceto que um advisor Fable 5 é cobrado dos créditos de uso nos planos em que isso se aplica. Alternar o advisor no meio da sessão não invalida o cache de prompt do modelo principal (só a leitura que o próprio advisor faz da conversa fica fora do cache).

Ressalva honesta: este é um recurso experimental, disponível só pela API direta da Anthropic - não no Amazon Bedrock, na Agent Platform do Google Cloud, nem no Microsoft Foundry - e o comportamento/preço pode mudar.

Armadilhas de tokens: times de agentes, workflows dinâmicos & sessões o dia todo

Essas duas inflam o seu consumo de um jeito difícil de perceber.

Times de agentes ~7x tokens - mas só quando os colegas rodam em plan mode. Rodar um "time" de vários agentes em paralelo parece poderoso, mas a documentação "Manage costs effectively" avisa que ele usa cerca de ~7x os tokens de uma sessão padrão quando os colegas rodam em plan mode - porque cada colega mantém a própria janela de contexto e roda como uma instância separada do Claude. Quando não usar: tarefas sequenciais, escopo pequeno, ou quando o seu orçamento de tokens está apertado. Se tiver que usar, rode os colegas no Sonnet e encerre o time assim que terminar.

Workflows dinâmicos também podem inflar o consumo se ficarem sem limite. Digite a palavra-chave ultracode em um prompt (ou simplesmente peça em linguagem comum para "usar um workflow para isso") e o Claude escreve e roda um workflow dinâmico que orquestra vários subagents - até 1.000 agentes por execução, com até 16 rodando ao mesmo tempo. Acompanhe o progresso com /workflows. Um aviso de "Large workflow" aparece quando uma execução agenda mais de 25 agentes ou os tokens projetados passam de 1,5 milhão (o limite de 25 agentes é substituído por qualquer diretriz de tamanho que você definir no /config - o padrão é medium, abaixo de 15 agentes) - ele é só um alerta e não interrompe a execução. Honestamente: não há uma cifra oficial em dólares para uma execução completa de workflow; teste em uma fatia pequena antes de rodar tudo. Veja a mecânica completa em workflows dinâmicos no Claude Code.

Sessões o dia todo. Deixar uma única sessão rodando de manhã até a noite é receita para queimar tokens: o contexto longo incha, e o cache não para de dar miss toda vez que você se afasta. Sobre cache, a documentação observa que a duração é de 1 hora nos planos de assinatura versus 5 minutos com créditos de uso/API; você pode habilitar o cache de 1 hora com uma variável de ambiente:

ENABLE_PROMPT_CACHING_1H=1

Bons hábitos: /clear ao trocar de trabalho, fechar a sessão em pausas longas, retomar a partir do resumo quando voltar. (Uma nota pequena para o seu sossego: os tokens de background das tarefas automáticas do Claude Code são muito baratos - a documentação cita < US$ 0,04/sessão, então não se preocupe com essa parte.)

Tabela-resumo - técnica versus economia de tokens

Ordenada por ROI de tokens (alta alavancagem / baixo esforço no topo). Onde a coluna "economia" tem uma fonte da Anthropic, citamos o número verificado; as partes medidas em uma base real ficam para a Jasmine preencher a partir da sessão de teste dela.

Acelere com um kit pronto (AgentKit)

Muitas das técnicas acima - a skill de "codebase-overview", subagents especializados, hooks de filtragem de saída - são eficazes mas dão trabalho de verdade para construir e ajustar por conta própria. Se você prefere ter um conjunto pronto de skills, subagents e hooks otimizados para contexto para o Claude Code, o kit AgentKit para Claude Code empacota esse ferramental para você não ter que escrever do zero.

Uma observação para evitar confusão: o AgentKit aqui (agentkit.best, CLI ak) é um kit para Claude Code / Codex / Copilot - completamente diferente do AgentKit da OpenAI. Você pode conferir o AgentKit (20% de desconto pelo link) e julgar por si mesma; esta é uma sugestão opcional, não uma exigência - toda técnica deste artigo pode ser feita na mão.

Perguntas frequentes (FAQ)

Quando eu uso /compact versus /clear?

Use /clear quando você troca para uma tarefa sem relação - ele reseta o contexto e corta o custo da "cauda da conversa" para perto de zero. Use /compact quando você quer continuar a mesma linha de trabalho mas o contexto inchou; ele comprime o histórico em um resumo mantendo o seu fio da meada.

O Claude Code compacta automaticamente?

Sim. Quando o contexto chega perto do limite, o Claude Code faz auto-compact para a sessão não quebrar. Conveniente, mas pode descartar detalhes, então para tarefas importantes rode você mesma um /compact direcionado em vez de deixar por sorte.

Usar o Opus é bem mais caro?

Sim - pelos preços de referência da API, o Opus 5 (US$ 5/US$ 25 por 1M entrada/saída) é cerca de 2,5x mais caro que o Sonnet 5 (US$ 2/US$ 10). Deixe o Sonnet cuidar da maior parte da programação e só troque com /model para o Opus em arquitetura ou problemas difíceis.

Como eu vejo os tokens que estou usando?

Digite /usage para ver o total de tokens de entrada/saída, leitura/escrita de cache e custo; digite /context para ver quais componentes estão ocupando o seu contexto atual (CLAUDE.md, ferramentas MCP, arquivos lidos). Meça com esses dois antes e depois de cada mudança.

Em uma base de código grande, por onde eu começo a otimizar?

Comece medindo com /context, depois priorize as duas alavancas mais baratas: /clear entre tarefas e enxugar o CLAUDE.md para abaixo de ~200 linhas. Depois disso, passe a cortar MCP em excesso, usar subagents para pesquisa, e um hook para filtrar a saída dos testes.

Desligar o extended thinking é prejudicial?

Pode ser. Desligar o pensamento economiza tokens de saída mas reduz a qualidade em tarefas de raciocínio profundo (design de algoritmos, depuração em várias camadas). Só reduza com /effort ou MAX_THINKING_TOKENS=8000 em tarefas simples, e mantenha o pensamento no trabalho que precisa de raciocínio.

A ferramenta advisor custa tokens extras?

Sim - cada chamada é cobrada pela tarifa do modelo advisor, por cima do uso do seu modelo principal, e conta no /usage como qualquer coisa. Mas o Claude só chama o advisor nos pontos de decisão (comprometer-se com uma abordagem, um erro recorrente, antes de declarar concluído), não a cada rodada, então normalmente ainda sai mais barato do que rodar o modelo forte a sessão inteira.

Quantos tokens os workflows dinâmicos usam?

Não há cifra oficial em dólares. O runtime tem limites rígidos para conter o custo desgovernado - até 1.000 agentes no total, com no máximo 16 rodando ao mesmo tempo. O aviso de "Large workflow" em 25 agentes/1,5 milhão de tokens é só um alerta, não interrompe a execução; teste em uma fatia pequena antes de rodar tudo.

Conclusão + próximos passos

A fórmula para otimizar tokens no Claude Code cabe em uma corrente: medir → cortar contexto → escolher modelo → descarregar em hooks/skills → subagents para bases grandes → advisor em vez de trocar o modelo a sessão inteira. Não faça tudo de uma vez; meça com /context e /usage, escolha as 2-3 alavancas de maior ROI da tabela, aplique e meça de novo. Lembre que a economia depende da sua base de código e dos seus hábitos - meça na sua própria máquina.

Leia a seguir: gerenciar contexto e memória para se aprofundar em compactação, preços e planos do Claude Code para escolher o plano que cabe no seu uso, e workflows dinâmicos no Claude Code se você precisa orquestrar vários agentes em uma tarefa grande. Se você prefere usar um ferramental pronto a otimizar na mão, confira a nossa review do AgentKit para Claude Code.