Como economizar tokens no Claude Code, sem mito
Downshift por Tiago Vilas Boas. Atualizado em
Este Downshift é uma ferramenta em Go para agentes de código com IA, não a biblioteca React downshift de autocomplete.
Resumo
Para economizar tokens no Claude Code, a página de custos da Anthropic lista as alavancas que reduzem o consumo: limpar o contexto, escolher o modelo certo, cortar o excesso de MCP, delegar a hooks, baixar o esforço e usar subagentes. Este guia ordena essas alavancas pelo que está documentado e pelo que foi medido, e mostra onde o Downshift, um hook open source de roteamento, entra.
Onde os tokens vão de verdade
O Claude Code reenvia a conversa inteira a cada requisição. O cache de prompt faz essa releitura custar menos, mas o contexto continua crescendo, e uma sessão longa continua pagando por ele. A página de custos da Anthropic aponta as causas mais comuns de uma sessão que gasta mais do que a sua atividade sugere.
- Contexto longo: uma pergunta de uma linha, no fim de uma sessão aberta o dia inteiro, ainda consome o equivalente à conversa toda.
- Cache frio: a primeira mensagem depois de uma pausa maior que a vida útil do cache reprocessa o contexto inteiro.
- Subagentes: cada um envia as próprias requisições, além das da conversa principal.
Antes de mudar qualquer coisa, olhe os seus números. O comando /usage mostra um bloco da sessão e, em quem tem assinatura, uma divisão que sinaliza comportamentos acima de 10% do uso recente. O valor em dólar ali é uma estimativa local a preço de tabela, não uma fatura.
O que a documentação da Anthropic recomenda
A documentação oficial está em inglês e é a fonte desta lista. Cada linha funciona sem instalar nada.
| Alavanca | O que a documentação diz | O que fazer |
|---|---|---|
| Limpar entre tarefas | Contexto antigo gasta tokens em toda mensagem seguinte | Rodar /clear ao mudar de assunto |
| Escolher o modelo | Sonnet resolve a maioria das tarefas de código; Opus fica para decisões complexas; haiku serve para subagentes simples | /model, /config ou model: haiku no subagente |
| Plugins de code intelligence | Navegação por símbolo troca um grep mais várias leituras de arquivo | Instalar o plugin da sua linguagem |
| Hooks e skills | Um hook pode devolver só as linhas que importam de um log enorme | Pré-processar dados antes de o Claude vê-los |
| Esforço e thinking | Tokens de thinking são cobrados como saída | Baixar o esforço em tarefas simples |
| Subagentes para trabalho verboso | A saída longa fica no contexto do subagente | Delegar testes, leitura de docs e de logs |
Subagentes herdam o modelo caro
Delegar trabalho verboso mantém o contexto principal pequeno. A documentação faz uma ressalva: as requisições do próprio subagente também consomem o seu uso. Por isso o modelo em que ele roda importa.
Segundo a documentação, um subagente sem modelo fixado segue o modelo da conversa principal. Renomear uma variável e revisar uma arquitetura podem, então, rodar no mesmo modelo caro. Você pode fixar um modelo por definição de agente ou um modelo para todos os subagentes. Nenhuma das duas escolhas olha para a tarefa.
O cache de prompt e as pausas
Em uma assinatura Claude, a conversa principal pede cache de uma hora. Com chave de API ou provedor de nuvem, o padrão é de cinco minutos. Os subagentes recebem cinco minutos, a menos que você escolha um prazo maior. Quando o cache expira, a mensagem seguinte paga para reconstruí-lo.
A partir da v2.1.251, o /usage traz a linha Prompt cache (main), que mostra as falhas e se o cache está quente. O cache-tax, um mod de terceiros incluído no Downshift, calcula o preço de um envio com cache frio antes de você pagar. Ele foi criado por Karan Bansal (MIT) e o Downshift apenas o distribui.
Contexto menor, melhor
A Anthropic sugere plugins de code intelligence, uma skill que descreva o seu código e prompts específicos. O Downshift acrescenta o DCI, um indexador opcional que empacota só os símbolos afetados por uma mudança, dentro de um limite de bytes. Ele vem desligado. Latência e tamanho da saída foram medidos. A qualidade das respostas, não.
Como economizar tokens: o que está medido e o que não está
- Um teste controlado em 2026-10-15, no Claude Code, com tarefas mecânicas delegadas: US$ 0,67 por execução no grupo de controle e US$ 0,59 no grupo roteado, a preço de tabela. É cerca de 12% de economia estimada, no teste anterior. Uma execução posterior com quatro grupos (2026-10-21, 46 execuções, tarefas mecânicas) mediu cerca de 24% menos tokens por execução aceita com roteamento, intervalo de 95% de +2,1% a +46,7%.
- Os checks passaram 12/12 nos dois grupos. Um operador, três execuções por célula.
- Em tarefas naturais complexas, um benchmark aplicou 0 downshifts e outro, 3 de 34. Ainda não há nada atribuível.
- Cerca de 1 em cada 10 spawns fica sem roteamento, como grupo de controle.
- Ninguém mediu como essas alavancas se combinam neste cenário, e o Downshift também não.
Como medir o seu próprio uso
- Rode /usage e anote a maior fatia de atribuição e qualquer sinalizador de comportamento.
- Leia a linha Prompt cache. Muitas falhas apontam para troca de modelo, mudança de ferramentas ou pausas longas.
- Mude uma coisa por vez e rode /usage de novo.
O Downshift também grava um log local sem prompts, com contagens, hashes e tempos.
Decisões reais de roteamento
Saídas reais do downshift try, capturadas em 2026-10-19, com claude-opus-5-5 como modelo atual. As tarefas aparecem como foram digitadas, duas delas em português. A diferença é uma estimativa a preço de tabela para uma chamada entre dois modelos, não uma economia de sessão ou de mês. Held significa que o modelo pedido continua rodando.
| Tarefa | Tier | Troca de modelo | Diferença estimada | Resultado | Motivo |
|---|---|---|---|---|---|
| renomeie a variável userId para accountId | small | opus -> haiku | ~75% cheaper (est.) | Rewritten | trivial task, no risk, confident |
| refactor the checkout module | mid | opus -> sonnet | ~50% cheaper (est.) | Rewritten | medium task, no risk, confident |
| migre o webhook de pagamento para o novo esquema de autenticação | frontier | stays on opus | none | Stays on frontier | complex task, touches a risk area, confident |
| do the thing | mid | opus -> sonnet | not applied | Held | medium task, no risk, unsure, no clear signal |
Fonte: downshift try output, captured 2026-10-19 (reproduce with the command shown)
Perguntas frequentes
O que posso testar primeiro, sem instalar nada?
Rode /usage e leia a divisão do plano. Use /clear entre tarefas sem relação. Configure model: haiku nos subagentes de trabalho simples, como a documentação sugere. Depois leia a linha Prompt cache antes de mexer em outra coisa.
Essas alavancas se somam?
Não foi medido. O Downshift mediu só o próprio roteamento, em um teste, e não testou a combinação com as outras alavancas.
O Downshift envia os meus prompts para algum lugar?
Não. Os prompts são avaliados em memória e nunca gravados. O log local guarda contagens, hashes e tempos.
Instalar
Rode downshift setup --dry-run antes para ver cada alteração. downshift setup --undo restaura os backups.
curl -fsSL https://raw.githubusercontent.com/tiagovilasboas/downshift/main/install.sh | sh && downshift setupPlugin do Claude Code
/plugin install downshift --marketplace tiagovilasboas/downshiftGuias relacionados
Fontes
- Anthropic docsmedido
code.claude.com/docs/en/costs
lista Reduce token usage, /usage, por que o uso cresce em sessão longa (fetched 2026-10-19) - Anthropic docsmedido
code.claude.com/docs/en/prompt-caching
TTL padrão por tipo de acesso, subagentes e cache (fetched 2026-10-19) - Anthropic docsmedido
code.claude.com/docs/en/sub-agents
ordem de resolução do modelo do subagente (fetched 2026-10-19) - Downshift repomedido
docs/evidence/subagent-routing-ab-2026-10-15.md
números do teste, b2 e b6, 12/12 checks - Downshift repomedido
README.md
grupo de controle, privacidade, DCI opcional - Downshift repomedido
hooks/cache-tax/README.md
crédito ao upstream e requisitos - Downshift CLI outputmedido
downshift try and downshift dci output, captured 2026-10-19 (reproduce with the commands shown)
decisões de roteamento