Otimização de tokens no Claude Code: reduza custo com /usage sem perder qualidade

Otimizar tokens no Claude Code não é apenas pagar menos. Quando o contexto cresce demais, as respostas ficam mais lentas, decisões antigas entram na tarefa atual e Claude relê logs, diffs e notas que já não ajudam. O objetivo correto é manter a mesma qualidade de engenharia com menos contexto irrelevante.

Em junho de 2026, o ponto de entrada prático é /usage. A referência oficial de comandos descreve /usage como o comando para session cost, plan usage limits e activity stats. /cost e /stats existem como aliases, mas /usage é mais claro em documentação e regras de equipe. Em planos Pro, Max, Team e Enterprise, a tela também pode atribuir uso a skills, subagentes, plugins e servidores MCP.

O método aqui tem quatro camadas: observar, reduzir contexto base, separar trabalho ruidoso e medir fluxos repetíveis. Um hook é um script ou endpoint executado em um evento fixo do ciclo do Claude Code; um subagente é um contexto separado para uma tarefa estreita; harness é a estrutura que torna o trabalho do agente repetível e seguro.

flowchart LR
  A["Observar: /usage e /context"] --> B["Reduzir: CLAUDE.md e entradas focadas"]
  B --> C["Separar: hooks / skills / subagentes"]
  C --> D["Medir: OpenTelemetry e regras de equipe"]

Comece por /usage

Não é preciso rodar /usage depois de todo prompt. Use quando a sessão fica lenta, depois de uma saída grande de ferramenta, antes de um handoff e no fim de um workflow que será repetido. Combine com /context para descobrir se o custo vem da tarefa atual, histórico antigo, memory ou ferramentas.

A parte de billing precisa de cuidado. O Session cost em /usage é uma estimativa local baseada em tokens. Usuários de API devem confirmar cobrança real no Claude Console. Em assinaturas, o valor em dólar da sessão não deve ser lido como cobrança direta; barras de uso do plano e atribuição de atividade são mais úteis no dia a dia.

# Dentro do Claude Code
/usage
/context

# Quando a conversa está longa mas o trabalho continua
/compact Preserve changed files, failing tests, decisions, and unresolved questions.

# Ao mudar para uma tarefa sem relação
/clear

/compact resume estado importante para continuar. /clear inicia um novo contexto. Limpar cedo demais perde decisões; nunca limpar faz tarefas novas pagarem por contexto velho.

Mantenha curta a memória sempre carregada

Tokens não vêm só do texto recém-digitado. Também contam histórico, CLAUDE.md, auto memory, logs, saídas de ferramentas, servidores MCP e notas de investigação. Separe a informação em três grupos.

Tipo	Melhor lugar	Exemplo
Sempre necessário	CLAUDE.md curto	Build, testes, restrições fortes
Necessário nesta tarefa	Conversa e `/compact`	Arquivos alterados, testes falhando, decisões abertas
Descartável após leitura	Saída filtrada	Logs longos, diffs gerados, buscas amplas

A documentação oficial de memory explica que CLAUDE.md é carregado como contexto. Quanto maior o arquivo, maior o custo fixo de cada sessão. Imports podem organizar instruções, mas não economizam tokens se o conteúdo continua sendo carregado no início.

# CLAUDE.md

## Project commands
- Build: npm run build
- Test: npm run test
- Type check: npm run typecheck

## Fast navigation
- API code: src/api/
- UI components: src/components/
- Tests: tests/

## Avoid by default
- Do not scan node_modules/, dist/, coverage/, or generated clients.
- Do not paste full logs. Ask for the failing command and relevant lines.

## Compact instructions
When compacting, preserve changed files, failing tests, decisions, credentials policy, and next actions.

Checklists longos de review, regras de tradução, runbooks de migração ou playbooks de release ficam melhor como skills ou documentos separados. Uma skill é carregada quando chamada; CLAUDE.md entra no contexto desde o início.

Filtre antes de Claude ler

O desperdício mais comum é colar o log inteiro ou o diff inteiro. Claude precisa de evidência, não de dump. Guarde o artefato completo no disco e entregue primeiro as linhas que podem mudar a próxima decisão.

# Não cole todo o log de produção: use request ID e erros próximos
tail -n 800 logs/app.log | grep -E -n -C 4 "request_id=abc123|ERROR|WARN"

# Veja o tamanho do PR antes do diff completo
git diff --stat
git diff -- src/auth.ts tests/auth.test.ts

# Guarde a saída completa e mostre a Claude só a área de falha
npm test 2>&1 | tee test.log
grep -E -n -C 6 "FAIL|ERROR|Error|failed|Assertion" test.log | head -160

Isso não esconde informação. Só define o primeiro recorte que Claude lê. Se não bastar, você adiciona mais linhas ou outro arquivo.

Use hooks com cautela

Se o mesmo filtro aparece sempre, transforme em hook. O hook não deve esconder falhas nem aprovar comandos arriscados em silêncio. Comece com ask, revise o comando reescrito e teste localmente.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/filter-test-output.sh"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

case "$cmd" in
  npm\ test*|pnpm\ test*|pytest*|go\ test*)
    filtered="$cmd 2>&1 | grep -E -n -C 6 '(FAIL|ERROR|Error|failed|Assertion)' | head -160"
    jq -n --arg command "$filtered" '{
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "ask",
        permissionDecisionReason: "Run test command with filtered output",
        updatedInput: { command: $command }
      }
    }'
    ;;
  *)
    echo '{}'
    ;;
esac

O exemplo exige jq. Para equipe, salve também o log completo e preserve o exit code original. O hook só vale quando reduz ruído sem reduzir evidência.

Separe trabalho verboso

Subagentes ajudam quando o processo é longo mas a conversa principal só precisa de uma conclusão curta: verificar docs oficiais e devolver fatos alterados, checar dez arquivos localizados e devolver bloqueios, ou rodar um teste falho e resumir o primeiro stack trace acionável.

Não crie subagentes por reflexo. Cada um tem seu próprio contexto, memory, ferramentas e custo. Use para proteger o contexto de decisão, não para paralelizar trabalho vago. O mesmo vale para skills: tire playbooks longos e raros do CLAUDE.md.

Meça uso de equipe

Para uma pessoa, /usage e /context costumam bastar. Em times, OpenTelemetry transforma custo, tokens, modelo, duração e atividade de ferramentas em dados comuns. Comece com console exporter antes de ligar collector ou dashboard.

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=console
export OTEL_LOGS_EXPORTER=console
export OTEL_METRIC_EXPORT_INTERVAL=10000
export OTEL_LOGS_EXPORT_INTERVAL=5000

claude

Meça qualidade junto. Se os tokens caem 30%, mas aumentam correções e defeitos de review, o processo piorou.

Casos de uso

Investigação de logs

Passe request ID, erros recentes, timestamps, comportamento esperado e linhas próximas. Comece pequeno e amplie só se faltar evidência.

Code review

Forneça git diff --stat, arquivos alterados, saída de testes e foco da revisão. Divida PRs grandes em segurança, performance e compatibilidade.

Publicação multilíngue

Mantenha decisões do artigo canônico na sessão principal. Tradução, links, description e CTAs podem ser verificados em contextos separados.

Dia de treinamento

Em workshops, a concorrência de uso aumenta. Regras como “ler cinco arquivos primeiro”, “máximo de 160 linhas de falha” e “justificar ampliar escopo” estabilizam custo e ritmo.

Falhas a evitar

Documentar só /cost. Use /usage e cite /cost e /stats como aliases.
Cortar evidência. Reprodução, saída esperada, comando falho e decisões devem ficar.
Transformar CLAUDE.md em caderno operacional. Fluxos raros cabem em skills.
Ativar MCP demais. Revise /mcp e use CLI quando bastar.
Esconder falhas com hooks. Guarde o log completo e mostre um recorte filtrado.
Achar que subagentes sempre custam menos. Eles isolam ruído, mas têm contexto próprio.

Script curto de handoff

Este script Node.js sem dependências resume arquivos alterados, tamanho do diff e linhas de falha de teste.

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";

function git(args) {
  return execFileSync("git", args, { encoding: "utf8" }).trim();
}

const testLogPath = process.argv[2];
const changedFiles = git(["diff", "--name-only"])
  .split(/\r?\n/)
  .filter(Boolean);
const diffStat = git(["diff", "--stat"]);
const testLog = testLogPath && existsSync(testLogPath)
  ? readFileSync(testLogPath, "utf8")
  : "";
const failures = testLog
  .split(/\r?\n/)
  .filter((line) => /(FAIL|ERROR|Error|failed|Assertion)/.test(line))
  .slice(0, 80);

console.log("# Claude handoff brief\n");
console.log("## Changed files");
console.log(changedFiles.length ? changedFiles.map((file) => `- ${file}`).join("\n") : "- None");
console.log("\n## Diff stat");
console.log(diffStat || "No diff");
console.log("\n## Test failures");
console.log(failures.length ? failures.map((line) => `- ${line}`).join("\n") : "- No matching failure lines");

node scripts/claude-brief.mjs test.log > claude-brief.md

Documentação oficial verificada

Commands para /usage, /context, /compact e /clear.
Manage costs effectively para custos, MCP, hooks, skills, subagentes e esforço de modelo.
How Claude remembers your project para CLAUDE.md e auto memory.
Hooks reference e Monitoring para PreToolUse e OpenTelemetry.

Resultado testado

Nesta reescrita, usei o artigo japonês como canônico e conferi a documentação oficial antes de atualizar os dez locales. O maior ganho prático foi separar memory permanente, estado da tarefa e logs descartáveis. Um brief curto com arquivos alterados, linhas de falha e status de verificação gerou respostas melhores que colar a saída completa dos testes.

Para prompts e material reutilizável, comece em ClaudeCodeLab products. Para rollout de equipe, permissões, política de review, telemetria e treinamento, use Claude Code training and consultation.