Como Reduzir os Custos de Tokens de Agente em Fluxos de Trabalho CLI

Sou Dora. No mês passado, rodei um único npm test pelo Claude Code e observei a sessão consumir aproximadamente 12.000 tokens de entrada antes que o agente dissesse uma palavra sequer. A saída do teste tinha 400 linhas. Talvez 30 delas importassem. O restante — avisos de depreciação, ruído de dependências, os pontos de progresso do Jest — tudo foi direto para o contexto do modelo. Paguei por cada byte.

Foi então que parei de tratar tokens como “algo que o modelo gerencia” e comecei a tratá-los como um orçamento que estava ativamente vazando. Se você executa fluxos de trabalho CLI agênticos no Claude Code, Gemini CLI ou algo similar, esse é provavelmente seu maior custo — e a solução não é um modelo melhor, é uma higiene melhor. A própria documentação de gerenciamento de custos da Anthropic é clara: os custos de tokens escalam com o tamanho do contexto, e a maior parte da otimização acontece antes de o modelo ver os dados. Este artigo é sobre como reduzir os custos de tokens de agentes em fluxos de trabalho CLI sem perder o sinal de depuração que você precisa.

Onde os Fluxos de Trabalho CLI Desperdiçam Tokens

Antes de corrigir qualquer coisa, precisei descobrir onde estavam os vazamentos. Dois padrões se destacaram, e aparecem em quase todo fluxo de trabalho CLI que auditei desde então.

Comandos Verbosos e Saídas Irrelevantes

Comandos de terminal foram projetados para humanos percorrendo uma tela, não para LLMs lendo byte por byte. git status imprime códigos ANSI que o modelo não precisa. npm install despeja mil linhas de árvore de dependências que o modelo já conhece. next build ecoa seu próprio progresso por quinze segundos. Nada disso justifica seu espaço na janela de contexto.

Os números são piores do que parecem no papel. Uma única execução de cargo test em um projeto Rust médio pode produzir 8.000–15.000 tokens de saída. A maior parte disso é ruído de compilação. Quando o agente lê tudo para encontrar uma única asserção com falha, você pagou tarifas de nível Opus pelo privilégio de transmitir um log de build.

É também por isso que projetos comunitários como rtk e tokf existem — eles ficam entre o shell e o agente, filtram o texto padrão antes que ele atinja o contexto e relatam economias de 70–90% em comandos comuns. Quer você use um wrapper ou não, o princípio se mantém: saída bruta de terminal não é dado pronto para LLM.

Acúmulo de Contexto e Releituras Repetidas

O segundo vazamento é mais sutil. Cada chamada de ferramenta que o agente faz — leitura de arquivo, grep, comando bash — fica no histórico da conversa. Na décima rodada, o modelo está reprocessando nove rodadas de saídas obsoletas em cada solicitação. O próprio post-mortem de abril da Anthropic sobre problemas de qualidade do Claude Code descreve exatamente essa dinâmica: um bug de cache fez com que o histórico de raciocínio se acumulasse entre as rodadas, e o uso de tokens inflou 10–20x antes que alguém percebesse. Mesmo sem bugs, esse é o comportamento padrão. Sessões longas são sessões caras.

Verifiquei uma das minhas próprias sessões de uma semana atrás. O agente havia lido o mesmo package.json quatro vezes. Nenhuma dessas releituras adicionou informação — o arquivo não havia mudado. Eram apenas artefatos do agente não saber o que já sabia.

Passo 1: Comprimir Saídas Ruidosas

A correção mais barata, de longe, é impedir que lixo entre no contexto desde o início. Três regras, nessa ordem:

Filtre na fonte, não depois. Em vez de npm test, o agente executa npm test —silent 2>&1 | grep -E “(FAIL|PASS|Error)”. Em vez de git status, executa git status —short. Em vez de cargo build, executa cargo build —quiet 2>&1 | tail -20. Nada disso é inteligente. É apenas disciplina. O agente recebe o teste com falha, os arquivos modificados, o erro real — nada mais.

Limite a saída das ferramentas no nível do harness. O Claude Code permite definir um tamanho máximo de saída de ferramenta. Reduzi o meu para 8.000 caracteres por chamada. Quando um comando excede esse limite, o agente recebe um aviso de truncamento e decide se deve refinar a consulta. Essa única configuração me poupou mais tokens do que todas as outras mudanças combinadas.

Use um proxy CLI quando a ferramenta upstream não fica quieta. Alguns comandos não têm uma flag silenciosa útil — next build, webpack, qualquer coisa baseada em Java. Para esses, um wrapper que remove texto padrão conhecido vale o tempo de configuração. Ferramentas da família rtk/tokf lidam com isso genericamente; você também pode escrever uma função bash de 30 linhas para os três comandos que mais te incomodam.

Há uma troca real aqui. Compressão agressiva pode ocultar sinais de depuração. Quando um build falha por um motivo que o filtro remove — um aviso de depreciação que se tornou um erro, um problema de configuração obscuro enterrado na linha 847 — o agente recebe um quadro mais curto e menos útil. Aconteceu comigo duas vezes. Em ambas as ocasiões, a correção foi afrouxar uma regra de filtro, não abandonar a estratégia.

Passo 2: Limitar o Contexto Antes que Ele Chegue ao Modelo

A filtragem de saída cuida dos tokens novos que entram a cada rodada. A disciplina de contexto cuida dos tokens acumulados já dentro da sessão. Problemas diferentes.

Os dois comandos que importam, ambos diretamente das melhores práticas do Claude Code da Anthropic, são /clear e /compact. /clear redefine a sessão completamente — útil ao mudar para uma tarefa não relacionada. /compact resume o histórico anterior preservando decisões-chave e o estado atual — útil quando a tarefa continua, mas a exploração inicial não é mais relevante. O Claude Code faz compactação automática ao se aproximar dos limites de contexto, mas esperar esse gatilho geralmente é tarde demais. A essa altura, você já pagou a tarifa inflada por várias rodadas.

Meu hábito atual: executo /compact em cada fronteira natural de tarefa, com uma instrução como /compact Focus on the failing test and the recent file edits. A instrução importa. Sem ela, a compactação resume tudo de forma aproximada. Com ela, o agente mantém as partes que importam para a próxima fase.

Para agentes baseados em API (não a assinatura CLI), a documentação de edição de contexto da Anthropic descreve um mecanismo mais rigoroso: clear_tool_uses_20250919 limpa automaticamente os resultados antigos de ferramentas quando o contexto ultrapassa um limite. O agente retém a conversa, mas perde as saídas brutas que já processou. Para tarefas agênticas de longo horizonte, esse é o padrão correto.

Uma coisa que vale destacar: um CLAUDE.md inflado é um imposto permanente. Ele carrega a cada rodada, a cada sessão, para sempre. Reduzi o meu de ~280 linhas para ~90. A contagem de tokens por rodada caiu visivelmente e o comportamento do agente não mudou de nenhuma forma que eu pudesse medir.

Passo 3: Redesenhar as Ferramentas do Agente para Menor Desperdício

Os dois primeiros passos são táticos. Este é estrutural, e é onde vivem as economias duradouras.

Projete ferramentas que emitam saída amigável para LLMs. A CLI Spec conduzida pela comunidade faz esse argumento melhor do que eu poderia: comandos destinados a agentes devem suportar uma flag —output, separar dados (stdout) de diagnósticos (stderr) e fornecer paginação em vez de despejar JSON ilimitado. Se você está construindo CLIs internas que seus agentes vão chamar, siga essa especificação. Se estiver usando CLIs externas que não seguem, envolva-as.

Prefira ferramentas estreitas a amplas. Uma função git_status_summary que retorna três campos estruturados é melhor do que deixar o agente executar git status bruto e analisar a saída. Cada camada de análise que o modelo precisa fazer é uma camada onde tokens são gastos em tradução em vez de raciocínio. Converti quatro dos meus comandos mais usados em wrappers Python finos que retornam JSON. O uso de tokens por ida e volta nessas operações caiu aproximadamente 60%.

Use ​subagentes​​ para trabalho intenso em leitura. O recurso de subagentes do Claude Code executa um contexto separado para tarefas como “escanear o repositório e resumir o fluxo de autenticação”. Os resultados voltam como um resumo compacto — não os 40 arquivos que o subagente realmente leu. A conversa principal nunca vê os dados brutos. Para tarefas intensivas em exploração, esse é o maior ganho estrutural disponível.

Combine o modelo com o trabalho. Opus 4.7 é impressionante e caro. A maior parte do trabalho CLI — edições de arquivo, correções de teste, refatorações de rotina — funciona bem no Sonnet, a aproximadamente 40% do custo por token do Opus. Vale saber: o novo tokenizador do Opus 4.7 pode produzir até 35% mais tokens para texto idêntico em comparação com modelos anteriores, o que amplia a diferença de custo.

A ressalva honesta: meça antes de otimizar, depois meça novamente. Estabeleci uma linha de base com /cost (API) ou /usage (assinatura) por uma semana antes de mudar qualquer coisa, depois remeди após cada mudança. Duas das minhas “otimizações” não produziram nada mensurável. Sem uma linha de base, você está adivinhando.

Perguntas Frequentes

Por que os fluxos de trabalho de terminal consomem tantos tokens?

Porque a saída do terminal foi projetada para humanos, e os agentes pagam byte por byte. Um comando de build típico emite milhares de linhas de progresso, avisos e texto padrão que o modelo não precisa. Combine isso com o histórico de conversa que nunca é redefinido e os resultados de ferramentas que se acumulam entre as rodadas, e você tem sessões que consomem orçamentos de contexto antes que o trabalho real comece.

Quanto a compressão de saída pode ajudar?

Nas minhas medições, a filtragem no nível de comando mais os limites de saída reduziram os tokens de entrada por rodada em 40–60% em execuções de teste, builds e operações git. Wrappers comunitários como rtk relatam reduções de 80–90% em comandos específicos, embora esses números assumam saída verbose no pior caso. Os ganhos reais dependem de quais comandos seu agente executa com mais frequência. Audite os cinco principais, corrija esses, e a maior parte das economias aparece imediatamente.

O que as equipes devem otimizar primeiro?

Nessa ordem: limites de saída de ferramentas, disciplina com /clear e /compact, seleção de modelo. Os limites de saída são uma mudança de configuração única com custo contínuo zero. A higiene de sessão é um hábito, mas é gratuita depois de incorporada. A seleção de modelo é o ganho mais fácil de ignorar — executar tudo no Opus quando a maioria das tarefas funciona bem no Sonnet é um vazamento silencioso e significativo.

Quando a otimização de tokens prejudica a qualidade da depuração?

Quando você comprime além do ponto em que o agente consegue ver o que quebrou. Um stack trace truncado, um aviso de depreciação filtrado, uma flag —quiet que oculta o erro real — todos esses me custaram tempo real. O padrão que sigo: comprima agressivamente em comandos de rotina (git status, npm install, execuções de teste bem-sucedidas), mantenha saída verbose para operações com falhas conhecidas ou desconhecidas. Se você se pegar reexecutando um comando sem filtros para depurar, o filtro estava errado, não a estratégia.

Conclusão

Os custos de tokens em fluxos de trabalho CLI não são um problema de modelo. São um problema de encanamento. A maior parte dos gastos desaparece na lacuna entre o que os comandos de terminal emitem e o que o modelo realmente precisa para raciocinar — e essa lacuna é corrigível com filtragem de saída, disciplina de contexto e ferramentas que respeitam o agente do outro lado.

Estou executando a configuração acima há cerca de seis semanas. O consumo diário de tokens no Claude Code caiu aproximadamente 55%, a latência do agente melhorou como efeito colateral de contextos menores, e o fluxo de trabalho parece menos ruidoso para depurar. Nenhum desses números é universal — sua linha de base e seus cinco principais comandos terão uma aparência diferente. Mas o padrão se mantém: controle o que entra no contexto, controle o que permanece no contexto, e deixe o modelo gastar seu orçamento em raciocínio em vez de ler logs de build.

É onde meus dados terminam. A camada de compressão continua evoluindo, e as mudanças de tokenizador da Anthropic significam que esses números têm prazo de validade. Vale a pena refazer a linha de base a cada trimestre.

Posts anteriores：

• What Is RTK Token Efficiency?
• Agentic Workflow Tool Wiring Patterns & Pitfalls
• MCP in Production: Model Context Protocol Workflows
• Claude Code Agent Harness Architecture
• Claude Code vs Cursor 2026