Token Optimization

Como reduzir tokens no Claude Code: Guia para cortar 75%

2026-09-02·14 min de leitura min de leitura·LLMPodium Team

### Resposta Rápida: Como fazer o Claude usar menos tokens

Para reduzir o consumo de tokens no Claude Code em até 75%, aplique quatro otimizações centrais: configure um arquivo .claudeignore rigoroso para descartar artefatos de build e lockfiles, aproveite o desconto de 90% na leitura de prompt caching da Anthropic fixando prefixos estáticos, isole subtarefas com subagentes Scout para evitar o Context Rot, e priorize claude-3-7-sonnet ou claude-3-5-haiku para varredura de código antes de escalar para o Opus.

1. Introdução: O dreno silencioso de tokens em agentes de terminal

Agentes autônomos de programação em terminal, como o Claude Code da Anthropic, transformaram os fluxos de trabalho na engenharia de software. Diferente das extensões convencionais de autocompletar em IDEs, o Claude Code opera em um loop de execução autônomo: inspeciona estruturas de diretórios, lê arquivos de milhares de linhas, executa comandos no terminal, interpreta logs do compilador e aplica patches cirúrgicos no código-fonte.

No entanto, essa autonomia traz um custo elevado na API. Sem uma configuração prévia consciente, um comando aparentemente simples como "Refatore o middleware de autenticação para suportar rotação de JWT" pode consumir entre 1,5M e 3,5M de tokens em uma única sessão. Essa inflação resulta de quatro vetores críticos:

  1. Acúmulo e degradação de contexto (Context Rot): Saídas de comandos bash, buscas com grep, traces de erro e arquivos lidos na íntegra permanecem retidos na janela de contexto ativa do agente.
  2. Reingestão sem cache: Modificar mensagens no início da conversa invalida o intervalo de 5 minutos do cache de prompt temporário da Anthropic.
  3. Varredura de artefatos redundantes: Em buscas recursivas com regex, o Claude Code relê pastas de compilação (dist/, target/, .next/), enormes arquivos de dependências (package-lock.json, pnpm-lock.yaml) e dumps de banco de dados.
  4. Sobrealocação de modelos: Usar modelos topo de linha de raciocínio estendido (claude-3-opus ou Sonnet com Thinking no máximo) para tarefas banais como buscar caminhos de arquivos ou listar diretórios.

Com restrições estruturais de engenharia — higiene com .claudeignore, uso disciplinado de prompt caching, isolamento de subtarefas com subagentes e ajustes de CLI — equipes de desenvolvimento reduzem o consumo diário de tokens no Claude Code entre 70% e 80%, aumentando ao mesmo tempo a taxa de resolução de tarefas.

2. Economia quantitativa: Tabela de preços e arquitetura de cache

Para identificar onde os tokens são desperdiçados, analisamos a estrutura de custos da API da Anthropic e os níveis de cache (base 2026):

Modelo Claude Input Base ($/1M) Escrita no Cache ($/1M) Leitura do Cache ($/1M) Output ($/1M) SWE-bench Verified Função Ideal no Terminal
Claude 3.5 / 3.7 Haiku $0.80 $1.00 $0.08 $4.00 41.2% Busca de símbolos, filtros regex, mensagens de commit
Claude 3.7 Sonnet (Standard) $3.00 $3.75 $0.30 $15.00 70.3% Refatoração principal, edição multifile, testes
Claude 3.7 Sonnet (Extended Thinking) $3.00 (in) $3.75 (write) $0.30 $15.00 (pensamento+out) 72.8% Falhas arquiteturais complexas, race conditions
Claude 3 Opus / Opus 4.6 $15.00 $18.75 $1.50 $75.00 74.1% Auditorias críticas de segurança, reestruturação total

O cálculo por trás de 75% de economia em tokens e custos

Considere uma sessão típica de 15 turnos para refatorar um endpoint de API REST em um repositório TypeScript de 150.000 linhas: 

[Sessão Ingênua sem Otimização]
Turno 1: Carrega mapa do repo + package-lock.json + esquema de dados (180.000 tokens)
Turnos 2-5: Dumps de grep, logs de build, leituras completas de arquivos (acumulado de 240.000 tokens/turno)
Taxa de perda de cache: 45% (invalidação frequente por cabeçalhos e ferramentas dinâmicas)
Total de tokens de entrada processados: 3.250.000
Custo real (Sonnet): ~$9.75

[Sessão Otimizada: .claudeignore + Prompt Cache + Subagentes]
Turno 1: Resumo AST enxuto (18.000 tokens) -> Em cache a partir do Turno 1
Turnos 2-5: Diffs incrementais, subagente Scout retorna relatório compacto (22.000 tokens/turno)
Taxa de acerto de cache: 92% (leitura a preço reduzido de $0.30/1M)
Total de tokens de entrada processados: 410.000 (redução física de 87.3% nos tokens)
Custo real (Sonnet): ~$0.82 (redução financeira de 91.5%)

3. Pilar 1: Configurar .claudeignore para eliminar contexto inútil

A medida isolada de maior retorno em qualquer repositório é criar um arquivo .claudeignore focado em ambientes de produção.

O Claude Code respeita as regras do .gitignore por padrão, mas o .gitignore comum frequentemente permite a passagem de arquivos pesados que saturam a janela de contexto. Lockfiles, documentação estática, artefatos de compilação e bundles minificados jamais devem entrar no contexto do agente.

Modelo de produção para .claudeignore

Crie este arquivo na raiz do seu repositório: 

# ==============================================================================
# .claudeignore - Matriz de exclusão para economia de tokens em produção
# Evita que o Claude Code leia arquivos volumosos em operações glob e grep
# ==============================================================================

# Lockfiles de dependências (Arquivos JSON/YAML gigantes sem utilidade para AST)
package-lock.json
pnpm-lock.yaml
yarn.lock
bun.lockb
composer.lock
Gemfile.lock
Cargo.lock
poetry.lock

# Artefatos gerados de build e bundles
dist/
build/
out/
.next/
.nuxt/
.astro/
.svelte-kit/
storybook-static/
target/
*.min.js
*.min.css
*.map

# Cobertura de testes, arquivos de log e profiling
coverage/
.nyc_output/
*.lcov
*.log
npm-debug.log*
yarn-debug.log*
pnpm-debug.log*
*.heapsnapshot
*.cpuprofile

# Imagens, mídias e arquivos binários
public/assets/
public/images/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.webp
*.avif
*.ico
*.pdf
*.zip
*.tar.gz
*.wasm

# Documentação interna e especificações de API
docs/
*.mdx
specs/swagger/
*.postman_collection.json

# Variáveis de ambiente e certificados locais
.env*
!.env.example
*.pem
*.key
*.cert

# Migrações de banco de dados e dumps SQL
*.sql
*.dump
prisma/migrations/

O impacto real do .claudeignore

Quando o Claude Code faz uma busca recursiva, um package-lock.json não ignorado (com frequência contendo entre 25.000 e 80.000 linhas) consome sozinho mais de 120.000 tokens em apenas uma leitura. Bloqueando lockfiles e diretórios de build, o volume inicial de contexto cai de cerca de 180k tokens para menos de 15k tokens.

4. Pilar 2: Arquitetura de Prompt Caching e desconto de 90%

O mecanismo de prompt caching da Anthropic armazena os tokens de entrada nos servidores por até 5 minutos (renovado a cada novo acerto). A leitura de tokens em cache custa apenas 10% da tarifa de entrada padrão ($0.30/1M contra $3.00/1M no Sonnet). 

+-------------------------------------------------------------------------+
|                  Ciclo de vida do Prompt Caching na Anthropic           |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
| [System Prompt e Ferramentas] (Prefixo estático - Sempre em cache)      |
+-------------------------------------------------------------------------+
                                     |
                                     v
+-------------------------------------------------------------------------+
| [Mapa de arquitetura do repositório e regras] (Checkpoint em cache)     |
+-------------------------------------------------------------------------+
                                     |
                                     v (Ponto de quebra de cache!)
+-------------------------------------------------------------------------+
| [Instruções dinâmicas do usuário e histórico] (Cauda não armazenada)    |
+-------------------------------------------------------------------------+

Três mandamentos para preservar o cache de prompts

  1. Nunca insira timestamps dinâmicos no contexto do sistema: Evite datas correntes ou IDs de sessão mutáveis em CLAUDE.md. A alteração de um único caractere no prefixo invalida todos os tokens cacheados subsequentes.
  2. Encadeie solicitações na janela de 5 minutos: O TTL do cache é de 300 segundos. Se pausar por 6 minutos para revisar o código, a próxima chamada incorrerá na tarifa cheia de escrita ($3.75/1M).
  3. Ordene as instruções das mais estáticas para as mais dinâmicas: O motor do Claude Code posiciona diretrizes estáveis no início do payload da API. Garanta que o arquivo CLAUDE.md permaneça determinístico.

5. Pilar 3: Emprego de subagentes e isolamento de subtarefas

Uma das maiores armadilhas de custo em terminais é a armadilha da sessão monolítica. Em um único diálogo ininterrupto, o desenvolvedor instrui o Claude a reproduzir um bug, escrever testes, refatorar módulos, executar testes de integração e redigir a documentação.

Ao alcançar o 12º turno, a janela de contexto está saturada de centenas de linhas de logs de testes com falhas, avisos de build e códigos desatualizados. Todas as solicitações seguintes reenviam todo esse peso morto para a API.

Arquitetura de dois níveis: Scout e Executor

Separe a fase exploratória da modificação ativa do código: 

[Demanda do desenvolvedor]
       |
       v
+---------------------------------------------+
|  Nível 1: Subagente Scout (Somente Leitura) |
|  - Executado em claude-3-5-haiku / smol     |
|  - Usa Glob, Grep e leitura por faixas      |
|  - Condensa 500.000 tokens em resumo de 2KB |
+---------------------------------------------+
       |
       v (Entrega de contexto compacto)
+---------------------------------------------+
|  Nível 2: Agente Executor Primário          |
|  - Executado em claude-3-7-sonnet           |
|  - Recebe CAMINHOS EXATOS e símbolos AST    |
|  - Aplica patches cirúrgicos por linhas     |
+---------------------------------------------+

Prática de isolamento de tarefas no Claude Code

Divida trabalhos extensos em etapas isoladas no terminal: 

# Ineficiente: Conduz a uma expansão descontrolada do contexto
claude "Encontre todos os endpoints com auth depreciada, migre para OAuth2, ajuste os testes e documente"

# Eficiente: Varredura isolada -> Execução precisa
# Passo 1: Reconhecimento com consumo mínimo
claude --model claude-3-5-haiku -p "Liste apenas os caminhos de arquivos e números de linha com o middleware de auth antigo em formato JSON." > auth-audit.json

# Passo 2: Modificação cirúrgica em contexto limpo
claude --model claude-3-7-sonnet "Refatore os endpoints listados em auth-audit.json para o middleware OAuth2. Não altere nenhum outro arquivo."

6. Pilar 4: Escolha de modelo — Qual Claude gasta menos tokens?

Diferentes modelos da família Claude apresentam gastos de tokens muito distintos para o mesmo tipo de tarefa:

  • Orçamento de Thinking (Raciocínio): Modelos com Extended Thinking geram milhares de tokens internos de raciocínio cobrados como tokens de saída ($15.00/1M no Sonnet).
  • Prolixidade em chamadas de ferramentas: Determinados modelos produzem longos preâmbulos antes de acionar ferramentas, consumindo tokens extras.
  • Eficiência de localização: Modelos mais inteligentes encontram referências com 1 ou 2 comandos grep exatos, enquanto modelos inferiores tendem a ler arquivos inteiros sem necessidade.

Comparação do consumo de tokens por tipo de tarefa

Tipo de Tarefa Claude 3.5 Haiku Claude 3.7 Sonnet (Normal) Claude 3.7 Sonnet (8k Thinking) Claude 3 Opus
Localizar símbolo no repositório 12k tokens / $0.01 14k tokens / $0.04 24k tokens / $0.18 18k tokens / $0.27
Correção de bug em função 28k tokens / $0.03 22k tokens / $0.07 35k tokens / $0.24 30k tokens / $0.45
Refatoração de 5 arquivos Taxa de erro alta 140k tokens / $0.48 190k tokens / $1.25 220k tokens / $3.30
Race condition complexa Não soluciona 320k tokens (falha) 240k tokens (resolve) / $1.60 280k tokens / $4.20

Matriz de recomendação

  • Modelo principal do dia a dia: Use claude-3-7-sonnet em modo padrão para 80% das tarefas cotidianas de programação.
  • Reconhecimento e scripts rápidos: Utilize claude-3-5-haiku para exploração de diretórios, regex, scripts em bash e filtragem de logs.
  • Raciocínio estendido pontual: Ative o thinking (thinking: { budget_tokens: 4000 }) estritamente para desafios algorítmicos complexos ou erros de compilação persistentes.

7. Configurações avançadas em .claude/config.json

O Claude Code permite ajustes precisos de comportamento pelo arquivo ~/.claude.json (global) ou .claude/config.json (por repositório).

Configuração de alta eficiência .claude/config.json

{
  "$schema": "https://json.schemastore.org/claude-code-config.json",
  "model": "claude-3-7-sonnet",
  "maxThinkingTokens": 2048,
  "autoCompactContext": true,
  "contextCompactionThreshold": 0.65,
  "allowedTools": [
    "Edit",
    "Bash",
    "Glob",
    "Grep",
    "Read"
  ],
  "toolLimits": {
    "bashOutputMaxLines": 150,
    "readFileMaxLines": 300
  },
  "enableTelemetry": false
}

Análise dos parâmetros fundamentais

  1. maxThinkingTokens: 2048: Limita o consumo no modo de raciocínio. Sem essa trava, problemas simples podem gastar entre 8k e 16k tokens ($0.12 - $0.24) por turno.
  2. autoCompactContext: true: Executa a condensação automática do histórico quando a janela atinge 65% de capacidade (contextCompactionThreshold: 0.65).
  3. bashOutputMaxLines: 150: Evita que testes ou comandos de instalação despejem 5.000 linhas de stdout diretamente no contexto do modelo.

8. Padrões táticos de prompts no terminal

A forma como você comanda o agente pode ser responsável por até 40% do total de tokens gastos:

Padrão 1: Leitura restrita a faixas de linhas

Em vez de permitir a leitura de arquivos completos, defina os intervalos específicos: 

# Ineficiente: Lê 1.800 linhas (cerca de 14.000 tokens)
"Leia src/auth/session.ts e veja por que a validação do token está falhando"

# Eficiente: Lê apenas 60 linhas (cerca de 450 tokens)
"Inspecione as linhas 120-180 de src/auth/session.ts onde verifyJwt() está declarada"

Padrão 2: Restrição de saídas de comandos

Ao rodar testes ou builds, ordene relatórios concisos: 

# Ineficiente: Envia milhares de linhas de testes aprovados para o contexto
"Execute npm test e corrija o erro"

# Eficiente: Contém a saída
"Execute npm test -- --reporter=dot ou use grep para isolar as falhas. Não exiba logs de testes bem-sucedidos."

Padrão 3: Limpeza deliberada de contexto (/compact e /clear)

Utilize os comandos nativos do Claude Code:

  • /compact: Compacta imediatamente o histórico, substituindo detalhes passados por um resumo técnico enxuto.
  • /clear: Limpa integralmente a memória do contexto antes de começar uma nova tarefa, sem reiniciar o terminal.

9. Matriz comparativa das estratégias de economia

Estratégia de Otimização Economia Típica de Tokens Complexidade Risco para o Código Princípio de Ação
.claudeignore rigoroso 40% – 60% Baixa (5 min) Zero Descarta lockfiles, mídias e diretórios de build
Compactação (/compact) 30% – 50% Imediata (comando) Baixo Remove logs de terminal obsoletos e código antigo
Reconhecimento por subagentes 35% – 55% Média Muito baixo Separa a leitura pesada da edição precisa de código
Teto no orçamento Thinking 20% – 35% Baixa (configuração) Baixo-Médio Evita loops de raciocínio desnecessários
Patches ancorados por linha 15% – 25% Baixa (hábito) Baixo Substitui reescrita de arquivos por diffs cirúrgicos
Alinhamento do Prompt Cache 10% – 20% (Custo) Média Zero Congela prefixos estáveis para garantir o desconto de 90%

10. Conclusão e checklist de implementação em 5 etapas

Reduzir o consumo de tokens em 75% no Claude Code não compromete a qualidade do código entregue. Pelo contrário: um contexto limpo e bem direcionado reduz alucinações e dispersão, resultando em respostas mais rápidas e seguras.

Checklist de implementação em 5 passos:

  1. [ ] Adicione o .claudeignore: Coloque o template na raiz do projeto e descarte lockfiles e pastas de build.
  2. [ ] Ajuste o config.json: Limite os tokens de pensamento a 2048 e habilite o autoCompactContext em 0.65.
  3. [ ] Aloque os modelos corretamente: Use claude-3-7-sonnet para criar e alterar código, claude-3-5-haiku para buscas e reserve o raciocínio estendido para bugs complexos.
  4. [ ] Controle as saídas do terminal: Execute testes com flags enxutas (--reporter=min, filtros com grep) mantendo o stdout abaixo de 100 linhas.
  5. [ ] Limpe o contexto com frequência: Execute /compact ou /clear entre tarefas para erradicar o Context Rot.

Ao incorporar essas disciplinas no seu terminal diário, você desfruta de toda a capacidade dos agentes autônomos enquanto reduz substancialmente seus custos mensais de API.

← Todos os artigos
0 / 4
Comparar agora →