Otimização de custo do Claude Code: checklist com 25 itens

Habilite cache_control no system prompt

Se você usa a API direta, encapsule seu system prompt — ou qualquer bloco grande de contexto repetido entre requisições — em um cache_control: {"type": "ephemeral"}. Tokens em cache custam 10% dos tokens de entrada não cacheados. Num system prompt de 10.000 tokens repetido 50 vezes por dia, isso poupa 4,5 milhões de tokens por dia.

system=[{
  "type": "text",
  "text": seu_system_prompt_grande,
  "cache_control": {"type": "ephemeral"}
}]

Cacheie documentos antes de consultá-los várias vezes

Se você dispara vários prompts contra o mesmo documento (uma seção da base de código, uma especificação, um PDF), cacheie o documento já na primeira requisição. Toda requisição seguinte que acerta o cache paga 10% pelo documento. O ponto de equilíbrio é em 2 requisições; a partir da terceira, já compensa.

Acompanhe a taxa de cache hit nos cabeçalhos da resposta

Leia usage.cache_read_input_tokens em toda resposta da API. Se a taxa de cache hit fica abaixo de 60% numa aplicação pesada em system prompt, é sinal de que o cache expira antes do reuso. O cache efêmero dura 5 minutos; garanta que suas requisições caem dentro dessa janela.

Mantenha o conteúdo cacheado no topo do prompt

O cache é indexado pelo conteúdo e pela posição. Se você coloca conteúdo dinâmico (mensagem do usuário, data atual) antes do system prompt cacheado, o cache não bate. Bloco grande e estático primeiro. Conteúdo dinâmico no fim.

Use cache estendido (TTL de 1 hora) para contextos grandes e estáveis

O cache efêmero padrão dura 5 minutos. Se seu contexto é grande (um índice completo da base) e muda pouco, a Anthropic oferece cache estendido com TTL de 1 hora — custo de cache write um pouco maior, mas custo de cache read por hora menor. Vale a pena para contextos acima de 100 mil tokens.

Cacheie o conteúdo do CLAUDE.md em sessões longas do Claude Code

Em sessões do Claude Code, o conteúdo do CLAUDE.md é prefixado a cada mensagem. Se o seu CLAUDE.md tem 5.000 tokens, são 5.000 tokens cobrados por turno. Mantenha o CLAUDE.md enxuto e considere mover contexto específico do projeto para um arquivo separado, referenciado só quando necessário, em vez de injetado em todo turno.

Use Haiku para classificação e roteamento

O Haiku 3.5 custa US$ 0,25 por milhão de tokens de entrada contra US$ 3,00 do Sonnet 4.5. Em tarefas que são essencialmente correspondência de padrão (classifique este erro, categorize esta issue, este texto bate com estes critérios?), o Haiku entrega qualidade equivalente a um doze avos do preço. Audite seus subagentes — qualquer um com no máximo 3 turnos e saída no estilo classificação deveria rodar em Haiku.

Use Sonnet só quando o raciocínio importa

Sonnet vale o preço para: code review, auditoria de segurança, raciocínio multipasso, qualquer coisa que exija sintetizar informação conflitante. Não vale o preço para: geração de documentação, escrita de changelog, extração estruturada de dados ou qualquer coisa de formato determinístico.

Defina max_tokens conservador por agente

A API cobra pelos tokens gerados, não pelos tokens solicitados. Mas pedir um max_tokens alto sem precisar abre espaço para o Claude gerar mais do que o necessário. Em saídas estruturadas (JSON, YAML, tabelas), um max_tokens menor também força o Claude a ser mais conciso. Audite o tamanho real de saída de cada agente e fixe o max_tokens em 120% do p95 observado.

Use streaming em saídas longas; cancele cedo se for o caso

Em streaming, dá para cancelar no meio da resposta quando você já tem o suficiente. Na API, respostas parciais em streaming são cobradas pelos tokens gerados até ali, não pelo max_tokens cheio. Para aplicações em que muitas vezes basta a primeira parte de uma saída longa, streaming + cancelamento antecipado reduz o custo de saída em 40% a 70%.

Evite Opus em tarefas que o Sonnet resolve igual

Opus custa US$ 15 por milhão de tokens de entrada — 5x o Sonnet. A diferença de qualidade entre Opus e Sonnet é grande para trabalho criativo aberto e raciocínio multipasso complexo. Para tarefas de código, saída estruturada e a maior parte dos fluxos de dev, o Sonnet acompanha o Opus em qualidade por um quinto do preço. Faça benchmark antes de cair no Opus por padrão.

Rode /compact antes que sessões longas passem de 50 mil tokens

O comando /compact do Claude Code resume o contexto da sessão e o substitui por uma versão comprimida. Uma sessão de 100 mil tokens vira um resumo de 5 mil. A perda de qualidade é mínima para continuidade da tarefa; a economia é alta. Rode a cada 2 horas em sessões ativas.

Use Grep e Read em vez de deixar o Claude vasculhar a base

Quando o Claude explora a base sem direção, ele lê muitos arquivos para entender o contexto. Direcioná-lo aos arquivos certos primeiro ("leia app/api/users.ts e o modelo User") corta o contexto em uma ordem de grandeza. Use Grep para encontrar arquivos relevantes antes de pedir leitura.

Mantenha o CLAUDE.md abaixo de 300 linhas

Cada linha do CLAUDE.md é um token prefixado a toda mensagem da sessão. Um CLAUDE.md de 3.000 linhas adiciona cerca de 4.500 tokens por turno. Um de 300 linhas adiciona 450. O post sobre o CLAUDE.md de 3.000 linhas mostra como estruturar o arquivo para gastar pouco token sem perder cobertura.

Restrinja o acesso a ferramentas dos subagentes ao mínimo necessário

Um subagente com acesso a todas as ferramentas vai usar todas elas. Um subagente com acesso só a [Read, Grep] não consegue subir um Bash e carregar um log de 10 MB no contexto. Restringir ferramentas é proteção de custo e de segurança ao mesmo tempo.

Passe diffs, não arquivos completos, para agentes de revisão

Ao rodar um agente de code review, passe a saída de git diff HEAD~1 em vez do conteúdo completo dos arquivos. Um arquivo de 2.000 linhas com 40 linhas alteradas custa 2.000 tokens se você passa o arquivo e 200 se passa o diff. Para fluxos de revisão, o diff quase sempre basta.

Use a Batch API em qualquer workload sem urgência de tempo

A Batch API da Anthropic custa 50% menos por token que a API em tempo real. Aceita até 10 mil requisições por lote, processadas em até 24 horas. Se o seu caso de uso não precisa de resposta em menos de 60 segundos, Batch API é a escolha certa. Análise de documentos, geração de testes, escrita de changelog — tudo elegível para batch.

Deduplique requisições antes de enviar à API

Se sua aplicação pode mandar o mesmo prompt duas vezes (consulta idêntica de usuário, mesma análise de documento), confira a requisição contra um hash local antes de chamar a API. Um SHA-256 de (modelo + system_prompt + user_message) identifica duplicatas. Cacheie a resposta indexada pelo hash. Uma taxa de duplicatas de 5% numa aplicação de alto volume vira economia importante no fim do mês.

Agrupe requisições parecidas em um único prompt multi-parte

Se você precisa fazer a mesma operação em 20 documentos (resumir, classificar, extrair), uma única requisição multidocumento muitas vezes sai mais barata que 20 requisições individuais, porque o system prompt é pago uma vez só. Teste contra a sua matemática real de tokens — lotes muito grandes podem ultrapassar o limite de contexto e forçar divisão de qualquer jeito.

Implemente coalescência de requisições para consultas concorrentes idênticas

Em aplicações de alto tráfego, vários usuários podem disparar a mesma chamada de API ao mesmo tempo (mesmo relatório, mesma análise). Coalescência: quando há uma requisição em andamento, requisições idênticas posteriores aguardam a primeira resposta e a compartilham. Economiza chamadas de API proporcionalmente aos picos de tráfego.

Agende jobs de batch em horários de baixa demanda para prioridade na Batch API

O tempo de processamento da Batch API varia com a carga da Anthropic. Submeter lotes em horários de baixo tráfego (UTC 02:00 a 08:00) costuma render conclusão mais rápida sem custo adicional. Para lotes com janela de 24 horas, submeter à meia-noite e receber pela manhã é um padrão confiável.

Defina limites de orçamento por sessão e por dia via hooks PreToolUse

Um hook PreToolUse roda antes de toda chamada de ferramenta. Trinta linhas de hook que leem o custo acumulado da sessão em ~/.claude/projects/ e travam a execução acima de US$ 10 evitam cenários Tokenocalypse. O hook dispara antes da chamada de API sair da sua máquina; não existe ponto de fiscalização mais rígido.

Defina limites de max_turns em todos os subagentes

Um subagente sem limite de max_turns pode rodar indefinidamente. Defina max_turns: 10 na maioria e max_turns: 5 nos com tarefa simples e bem delimitada. Um subagente fora de controle a 50 turnos custa de 5 a 10 vezes o que um bem limitado custaria na mesma tarefa.

Logue e alerte sobre anomalias de custo, não só sobre o total mensal

Alertas mensais de cobrança pegam Tokenocalypses depois do estrago. Alertas diários (e-mail ou webhook do Slack quando o gasto diário passa de 2x da linha de base) pegam a tempo de intervir. O console da Anthropic permite alertas por gasto diário acima de um limite. Configure.

Mate sessões zumbis antes que elas se acumulem

Uma sessão do Claude Code aberta e abandonada ainda gera cobrança quando um subagente faz uma chamada de ferramenta. Liste sessões ativas com claude sessions list e mate as que você não está usando. Em máquina compartilhada entre devs, sessão zumbi é uma fonte de custo significativa e invisível.