Como reduzir o consumo de tokens em agentes de codificação com IA

Para reduzir o consumo de tokens em um agente de codificação com IA, diminua o que entra no contexto dele. Indique os arquivos que ele deve ler, mantenha um arquivo curto de instruções do projeto, peça um plano antes do código, faça as buscas você mesmo, reinicie as sessões com frequência e desative as ferramentas de que a tarefa não precisa.

A maioria das pessoas chega a este assunto depois que uma sessão atingiu o limite de uso no meio de uma refatoração, ou depois de receber uma fatura que dobrou de valor enquanto o volume de trabalho continuou o mesmo.

Esses hábitos funcionam da mesma forma no Claude Code, no Codex, no Cursor e em agentes semelhantes. Cada seção abaixo explica por que o hábito funciona, traz um exemplo curto que você pode copiar e informa se a evidência vem de uma medição ou de uma prática fundamentada.

Por que reduzir o consumo de tokens em agentes de codificação com IA é importante?

Os tokens custam caro duas vezes: uma na sua fatura ou no seu limite de uso, e outra na qualidade do resultado. Todo arquivo que um agente de codificação com IA lê e todo turno anterior que ele mantém permanecem no contexto, então o token mais barato é aquele que o agente nunca precisa ver. Um contexto menor e mais relevante também oferece ao modelo menos material irrelevante para distraí-lo. Uma sessão enxuta costuma ser mais barata e mais precisa do que uma sessão inchada.

Por exemplo, uma sessão de depuração que começa com “dê uma olhada no repositório” pode carregar dezenas de arquivos não relacionados antes de o agente chegar ao bug real. Você paga por cada um deles, e o modelo precisa raciocinar passando por todos.

Restrinja o que o agente pode ver

Para reduzir as leituras exploratórias de um agente de codificação com IA, diga a ele quais arquivos ler em vez de apontá-lo para o repositório inteiro. Sem isso, o agente precisa procurá-los, e cada arquivo que ele abre pelo caminho acaba no contexto. Quando você nomeia os arquivos, a leitura do agente fica limitada ao que a tarefa realmente exige.

# Before
Why is the checkout total wrong? Look through the repo.

# After
The total in src/cart/total.ts is wrong when a discount code is applied.
Read src/cart/total.ts and src/cart/discounts.ts only. Do not open other files
without asking.

Você também pode limitar, desde o início, o que o agente consegue acessar. Se ele roda em uma máquina dedicada, como em uma configuração de máquina remota para codificação agêntica, clone apenas os repositórios de que a tarefa precisa.

Mantenha um arquivo de instruções do projeto

Um arquivo de instruções do projeto, geralmente chamado AGENTS.md ou CLAUDE.md, evita que o agente de codificação com IA tenha que redescobrir suas convenções a cada sessão. A maioria dos agentes oferece suporte a esse tipo de arquivo. Consulte a documentação do seu agente para saber qual nome de arquivo ele lê. O Claude Code lê o CLAUDE.md, e sua documentação sobre memória explica que, a partir da v2.1.277, ele também lê o AGENTS.md diretamente quando o repositório não tem um CLAUDE.md.

Aqui a evidência é específica. Em um estudo com 124 pull requests em 10 repositórios usando o OpenAI Codex, as execuções com um arquivo AGENTS.md tiveram uma mediana de tempo de execução 28,64% menor e uma mediana de tokens de saída 16,58% menor. A mesma tabela de resultados mostra que a mediana de tokens totais ficou praticamente inalterada — na verdade, cerca de 1% maior com o arquivo. Na prática, o arquivo faz principalmente com que o agente escreva menos e termine mais cedo. Ele não reduz tudo o que o agente lê. O estudo também tem limitações: usou um único agente (o Codex rodando o gpt-5.2-codex), abrangeu apenas PRs pequenos e já mesclados (no máximo 100 linhas alteradas e cinco arquivos cada) e não avaliou completamente se o resultado estava correto.

Mantenha o arquivo curto. O Claude Code carrega o CLAUDE.md no contexto no início de cada sessão, então você paga por cada linha em todas as conversas. A Anthropic recomenda ficar abaixo de 200 linhas e observa que o Claude segue instruções curtas e específicas com mais consistência do que instruções longas ou vagas.

# AGENTS.md

## Project
Web API for order processing. Entry point: src/server.ts.

## Structure
- src/routes/: HTTP handlers, one file per resource
- src/services/: business logic; handlers never touch the DB directly
- tests/: mirrors src/; test files end in .test.ts

## Conventions
- Run `npm test` before proposing changes; run `npm run lint` on touched files
- Use the logger in src/lib/log.ts, never console.log
- Do not edit generated files in src/generated/

Peça um plano antes do código

Pedir um plano ao agente de codificação com IA antes que ele escreva código permite identificar uma direção errada antes que ele tenha lido e reescrito arquivos. Descartar um plano não custa quase nada. Uma implementação errada já gastou tokens em cada arquivo que tocou antes de você perceber. O plano também fornece uma lista de arquivos que você pode enxugar antes de qualquer trabalho começar.

Before writing any code: list the files you intend to read and change, and
the steps you will take, in under 10 bullets. Wait for my approval.

Se o plano incluir um arquivo irrelevante, remova-o da lista antes de aprovar.

Faça as buscas você mesmo e entregue os resultados

Quando você mesmo executa o grep e cola as linhas encontradas, o agente paga apenas por essas linhas. Pedir ao agente que encontre a mesma coisa pode custar cada arquivo que ele abrir pelo caminho. Ferramentas como git grep e git diff são rápidas e não consomem tokens, então deixe que elas façam a busca e entregue ao modelo apenas os resultados.

# Find every call site yourself
git grep -n "applyDiscount(" -- '*.ts'

# See only what changed, not whole files
git diff --stat
git diff -- src/cart/total.ts

Em seguida, cole a saída: “Aqui estão os 4 pontos de chamada de applyDiscount: [linhas coladas]. Atualize-os para passar o argumento de moeda.”

O Spotify criou uma versão automatizada desse hábito. A configuração deles envia as leituras de arquivos em massa do Claude Code para um modelo auxiliar mais barato e entrega ao Claude apenas o resumo. Um engenheiro do Spotify testou essa abordagem em um monorepo Java em quatro cenários. Em cada um, ele comparou os tokens que o Claude usaria para ler os arquivos diretamente com os tokens usados para ler o resumo do modelo auxiliar, e a economia nas leituras em massa ficou, em média, em torno de 90%. Esse número se aplica àquela base de código específica, considera apenas o contexto do Claude, e não os tokens do modelo auxiliar, e abrange somente os cenários de leitura em massa. O post do Spotify Engineering também lista as limitações: edições ainda exigem leituras diretas, porque os resumos não trazem números de linha confiáveis; o raciocínio e a depuração continuam com o Claude; e cada delegação adiciona latência.

Mantenha as sessões curtas e recomece do zero

Inicie uma nova sessão entre tarefas em vez de deixar uma única conversa crescer indefinidamente. Uma conversa longa carrega todo o histórico a cada nova mensagem, então continuar uma conversa desatualizada faz você continuar pagando por um contexto de que não precisa mais. O guia de custos do Claude Code, da Anthropic, afirma que, quando o gasto em um plano de API ou de provedor de nuvem fica acima do esperado, a causa mais comum é uma sessão que nunca foi limpa ou o Opus mantido como modelo padrão. O guia inclui limpar a sessão entre tarefas não relacionadas entre os hábitos de maior impacto.

# End of session 1
Summarize in under 15 lines: what we changed, what we decided, what is left.
Write it to NOTES.md.

# Start of session 2 (new chat/session)
Read NOTES.md, then continue with the first remaining item.

O resumo preserva suas decisões. A nova sessão descarta o histórico que levou até elas.

Desative ferramentas e integrações de que a tarefa não precisa

Cada integração habilitada aumenta o que o agente carrega e pode acionar. Se a tarefa não precisa de uma integração, desative-a. Os servidores MCP costumam ser os principais culpados. O Claude Code agora adia o carregamento das definições completas das ferramentas MCP até que o Claude precise de uma delas, então um servidor ocioso custa menos do que antes, mas os nomes e as instruções das ferramentas continuam no contexto. O guia de custos do Claude Code, da Anthropic, ainda recomenda executar /mcp e desligar os servidores que você não está usando. Um servidor de banco de dados, um servidor de automação de navegador e uma integração de tickets que você conectou no mês passado acrescentam peso a uma sessão que só mexe em CSS.

Para uma refatoração de um único arquivo, abra as configurações do seu agente e desligue os servidores de banco de dados, navegador e rastreamento de issues. Reative-os quando uma tarefa precisar deles. Se não tiver certeza do que cada servidor expõe, o guia do ecossistema MCP explica como clientes e servidores se encaixam. Se você mantém seu próprio servidor, o artigo criando um servidor MCP passo a passo mostra como expor apenas as ferramentas que você define.

Resumo

Conclusão

O custo em tokens cresce com o tamanho do contexto, e um agente como o Claude Code reenvia a conversa inteira a cada requisição, então o contexto que ele lê e relê se acumula rapidamente. Todos os hábitos acima funcionam mantendo esse contexto pequeno e focado na tarefa. Escolha um e, em seguida, cole o prompt e os arquivos que você está prestes a enviar em um contador de tokens para LLMs e conte-os antes e depois da mudança. Sem medição, qualquer economia é apenas um palpite.

Perguntas frequentes

Qual é a diferença entre compactar e limpar uma sessão do agente?

Compactar substitui o histórico mais antigo da conversa por um resumo e mantém a sessão ativa, enquanto limpar descarta o histórico e inicia um contexto novo. No Claude Code, o modelo precisa ler a conversa inteira para resumi-la, então compactar um contexto grande é, por si só, uma requisição grande, enquanto limpar não custa nada. Compacte no meio de uma tarefa quando decisões anteriores ainda forem relevantes e limpe entre tarefas não relacionadas.

Servidores MCP que não estou usando ainda consomem tokens no Claude Code?

Menos do que antes. Por padrão, o Claude Code usa a busca de ferramentas (tool search): na inicialização, o modelo vê os nomes das ferramentas e as instruções de cada servidor, e o schema completo de uma ferramenta só é carregado quando uma tarefa precisa dela. O Claude Code volta a carregar tudo logo no início quando ANTHROPIC_BASE_URL aponta para um host que não é da própria Anthropic, em implantações do Microsoft Foundry hospedadas no Azure e em modelos do Agent Platform do Google Cloud anteriores à geração Claude 4.5. Servidores marcados com alwaysLoad também são carregados por completo. A saída das ferramentas de qualquer servidor continua entrando no contexto.

Mudar para um modelo mais barato reduz o consumo de tokens?

Não. Um modelo mais barato altera o preço de cada token, não a quantidade de tokens. O agente continua lendo os mesmos arquivos e reenviando o mesmo histórico. As duas alavancas se somam: o guia de custos do Claude Code, da Anthropic, aponta escolher o modelo adequado para cada tarefa e limpar a sessão entre tarefas não relacionadas como os hábitos de maior impacto para reduzir gastos.

Como posso verificar o consumo de tokens de dentro do Claude Code?

Execute /usage para ver o custo da sessão, os limites de uso do plano e estatísticas de atividade, e /context para ver um detalhamento do que está ocupando a janela de contexto atual. Nos planos Pro, Max, Team e Enterprise, o /usage também aponta qualquer comportamento, como contexto longo, que represente 10% ou mais do seu uso recente e sugere como reduzi-lo. O valor em dólares é sempre uma estimativa calculada com base no preço de tabela. Em uma assinatura, ele não mostra o que você realmente paga.