Skip to main content

Dicas de Desenvolvimento e Economia de Tokens

Esse capítulo é o que separa quem usa o Claude Code de forma casual de quem usa com eficiência real. As dicas aqui são uma mistura de boas práticas oficiais da Anthropic e padrões que reduzem custo, aumentam qualidade do output e evitam os problemas mais comuns. Tudo aqui é referenciado da documentação oficial.

Por que economizar token importa​

Token tem três custos. Direto na conta (especialmente se você está na API), no tempo de resposta (mais token = mais latência), e na qualidade. Performance do modelo cai conforme a janela de contexto enche. Acima de 50-60% de uso, ele começa a "esquecer" instruções e cometer mais erros.

Custo médio em deployments enterprise é cerca de $13 por desenvolvedor por dia ativo e $150-250 por dev por mês, com 90% dos usuários abaixo de $30 por dia. Se você está saindo dessa faixa pra cima, provavelmente está deixando contexto inflar sem necessidade.

Princípio 1: Dê uma forma de verificar​

Essa é a dica mais importante de todas, segundo a própria Anthropic. O Claude trabalha dramaticamente melhor quando consegue verificar o próprio trabalho.

Antes vs Depois​

AntesDepois
"implemente uma função que valida emails""escreva validateEmail. casos de teste: user@example.com → true, invalid → false, user@.com → false. rode os testes depois de implementar"
"melhore o dashboard""[paste screenshot] implemente esse design. tire screenshot do resultado e compare com o original. liste diferenças e corrige"
"o build está falhando""o build falha com esse erro: [erro]. corrige e verifica que passa. resolva a causa raiz, não esconde o erro"

Sem critério de verificação, ele entrega algo que parece certo mas não funciona. Você vira o único feedback loop, e cada erro consome seu tempo.

Princípio 2: Explore, planeje, depois codifique​

Deixar o Claude pular direto pro código produz código que resolve o problema errado. Use Plan Mode (Shift+Tab até chegar nele) pra separar exploração de execução:

  1. Explore (Plan Mode): "leia /src/auth e entenda como tratamos sessões e login"
  2. Plan (Plan Mode): "quero adicionar Google OAuth. Quais arquivos precisam mudar? Crie um plano". Pressione Ctrl+G pra abrir o plano no editor e refinar.
  3. Implement (Normal Mode): "implemente o flow de OAuth do plano. Escreva testes e rode tudo"
  4. Commit: "commita com mensagem descritiva e abre PR"

Plan mode não é necessário pra mudanças triviais (fix de typo, log line, rename). É essencial pra mudanças multi-arquivo, código que você não conhece, ou quando a abordagem está incerta.

Princípio 3: Contexto específico no prompt​

Quanto mais preciso, menos correção depois.

AntesDepois
"adiciona testes pra foo.py""escreve teste pra foo.py cobrindo o edge case onde o usuário está deslogado. Sem mocks"
"por que ExecutionFactory tem essa API estranha?""olha o git history de ExecutionFactory e resume como a API chegou nesse formato"
"adiciona um widget de calendário""olha como widgets existentes na home page são implementados. HotDogWidget.php é bom exemplo. Segue o padrão pra implementar um calendar widget que..."
"corrige o bug do login""usuários reportam que login falha depois de session timeout. Olha o auth flow em src/auth/, especialmente token refresh. Escreva um teste que reproduz, depois corrige"

Conteúdo rico​

  • @arquivo em vez de descrever onde o código está. O Claude lê antes de responder.
  • Cole imagens direto (drag and drop ou Ctrl+V).
  • Pipe dados: cat error.log | claude -p "explica".
  • URLs pra docs externas. Use /permissions pra allowlistar domínios frequentes.

Princípio 4: Gerencie contexto agressivamente​

Rastreie consumo​

/cost          # Tokens e custo estimado
/context       # O que está consumindo a janela

Dica: configure uma statusline customizada pra mostrar uso de contexto continuamente.

/clear entre tarefas​

Comando mais subutilizado. Sempre que você muda de tarefa não-relacionada: /clear. Contexto stale gasta tokens em toda mensagem seguinte, mesmo que você não use o conteúdo antigo.

/compact com foco​

Em vez de auto-compaction genérica, force foco específico:

/compact Foque nas mudanças de API e nos arquivos modificados

Você também pode customizar comportamento padrão no CLAUDE.md:

# Compact instructions

Quando compactar, sempre preserve a lista de arquivos modificados e os comandos de teste

/rewind em vez de corrigir​

Se o Claude foi pra direção errada, Esc Esc ou /rewind pra voltar a um checkpoint. Limpa o contexto poluído com tentativas falhas.

Renomear sessão antes de clear​

/rename oauth-implementation
/clear
# depois...
claude --resume oauth-implementation

Sessão preservada, contexto limpo, fácil de achar de novo.

/btw pra perguntas paralelas​

Pergunta rápida que você não quer no histórico:

/btw qual a diferença entre Promise.all e Promise.allSettled?

Resposta aparece em overlay dismissível, não entra no contexto da conversa.

Princípio 5: Escolha o modelo certo​

TarefaModelo
Coding geralSonnet
Arquitetura, decisões complexas, raciocínio multi-stepOpus
Sumarização, classificação simples, subagent leveHaiku

Trocar mid-session: /model. Default em settings: /config. Em subagent: model: haiku no frontmatter.

Sonnet faz a maioria das tarefas de código bem e é significativamente mais barato. Reserve Opus pra quando precisa de fato.

Effort level​

/effort ajusta o quanto o modelo "pensa" antes de responder. Levels: low, medium, high, xhigh, max. Pra tarefas simples, baixe pra low e economize tokens de thinking, que são cobrados como output.

/effort low      # tarefas mecânicas
/effort high     # debugging difícil, refatoração grande

Pra desabilitar thinking completamente: /config. Ou MAX_THINKING_TOKENS=8000 no env.

Princípio 6: Reduza overhead de MCP​

MCP tool definitions são deferidas por padrão (só nomes carregam). Mas se você tem muitos servidores ativos, ainda assim adiciona contexto. Audite com /mcp periodicamente:

  • Desabilite servidores que você não está usando ativamente
  • Prefira CLIs (gh, aws, gcloud, sentry-cli) quando existirem. Não adicionam tool listing nenhuma
  • Code intelligence plugins pra linguagens tipadas dão navegação por símbolo, evitam grep + leitura de múltiplos arquivos candidatos

Princípio 7: Hooks pra preprocessar​

Hook que filtra output verboso é uma das maiores fontes de economia. Em vez do Claude receber 10.000 linhas do npm test, você devolve só as 50 linhas com falhas.

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

if [[ "$cmd" =~ ^(npm test|pytest|go test) ]]; then
  filtered_cmd="$cmd 2>&1 | grep -A 5 -E '(FAIL|ERROR|error:)' | head -100"
  echo "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"updatedInput\":{\"command\":\"$filtered_cmd\"}}}"
else
  echo "{}"
fi

10.000 linhas viram 100. Multiplique por toda chamada de teste numa sessão e a economia é absurda.

Mesma ideia vale pra:

  • Logs grandes: filtre por nível
  • Output de migration: pegue só erro/warning
  • find que retorna milhares de arquivos: limite com head e adicione filtro
  • Diff gigante: filtra por arquivo de interesse

Princípio 8: Mova instruções de CLAUDE.md pra Skills​

CLAUDE.md carrega em toda sessão. Se tem instruções pra workflows específicos (review de PR, migration de banco, deploy), esses tokens estão presentes mesmo quando você está fazendo algo não-relacionado.

Skills carregam sob demanda. Mova instruções especializadas pra .claude/skills/<workflow>/SKILL.md. Mantenha CLAUDE.md em menos de 200 linhas com só o essencial que aplica em toda sessão.

Princípio 9: Delegue pra subagents​

Operações verbosas (testes longos, leitura de muitos arquivos, processamento de logs) consomem contexto do principal. Delegue:

Use um subagente pra investigar como nosso sistema de auth lida com refresh
de token e se temos utilitários OAuth pré-existentes.

O subagente lê 30 arquivos, retorna um sumário de 500 tokens. Sua janela permanece limpa pra implementação.

Use também pra verificação:

Use um subagente pra revisar esse código por edge cases e race conditions.

Princípio 10: Course-correct cedo​

Os melhores resultados vêm de feedback loops apertados. Embora o Claude às vezes resolva tudo na primeira, geralmente é melhor:

  • Esc pra parar mid-action. Contexto preservado, você redireciona
  • Esc + Esc ou /rewind pra restaurar conversa e código a um checkpoint
  • "Undo that" pra reverter mudanças
  • /clear pra resetar entre tarefas não-relacionadas

Regra de ouro: se você corrigiu o Claude duas vezes no mesmo problema, o contexto está poluído com tentativas falhas. /clear e começa de novo com prompt mais específico incorporando o que aprendeu. Sessão limpa com bom prompt quase sempre supera sessão longa com correções acumuladas.

Princípio 11: Use --bare pra scripts​

Pra automações que rodam claude -p, pule overhead de discovery:

claude --bare -p "extraia todos os TODOs do código e formate como markdown"

--bare skip auto-discovery de hooks, skills, plugins, MCP servers, auto memory e CLAUDE.md. Só Bash + Read + Edit. Subida muito mais rápida pra scripts simples.

Princípio 12: Restrinja tools em batch​

Pra operações em loop com claude -p, restrinja tools com --allowedTools:

for file in $(cat files.txt); do
  claude -p "Migra $file de React pra Vue. Retorne OK ou FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

Menos chance de comportamento inesperado quando rodando sem supervisão.

Princípio 13: --exclude-dynamic-system-prompt-sections pra cache​

Pra workloads scripted multi-user, essa flag move seções per-machine (working dir, env info, git status) do system prompt pra primeira mensagem do usuário. Isso melhora reuso de prompt cache entre máquinas/usuários diferentes rodando a mesma task.

claude -p --exclude-dynamic-system-prompt-sections "query"

Princípio 14: Auto mode pra reduzir prompts de permissão​

claude --permission-mode auto -p "fix all lint errors"

Classificador separado revisa comandos antes de rodar. Bloqueia escalação de escopo, infra desconhecida, ações de conteúdo hostil. Deixa trabalho rotineiro passar sem prompt.

Combine com allowlist específica via /permissions pra ferramentas conhecidas e seguras (ex: npm run lint, git commit).

Princípio 15: Faça o Claude te entrevistar​

Pra features grandes, em vez de descrever tudo de uma vez:

Quero construir [descrição breve]. Me entreviste em detalhe usando o
AskUserQuestion tool.

Pergunte sobre implementação técnica, UI/UX, edge cases, preocupações e
trade-offs. Não pergunte óbvio, foca nas partes difíceis que eu posso não
ter considerado.

Continua entrevistando até cobrir tudo, depois escreve um spec completo
em SPEC.md.

Quando o spec estiver pronto, abre uma sessão nova pra executar. Contexto limpo focado em implementação, com spec por escrito pra referência.

Padrões Comuns de Desperdício​

"Kitchen sink session"​

Você começa com uma tarefa, pergunta algo não-relacionado, volta pra original. Contexto cheio de informação irrelevante.

Fix: /clear entre tarefas não-relacionadas.

Correção em loop​

Claude faz errado, você corrige, ainda errado, corrige de novo. Contexto poluído com tentativas.

Fix: depois de duas correções falhas, /clear e prompt melhor.

CLAUDE.md inflado​

Se está longo, o Claude ignora metade porque regras importantes se perdem no ruído.

Fix: pode tudo. Se ele já faz a coisa certa sem a instrução, deleta. Se a instrução tem que ser determinística, vira hook.

"Trust then verify gap"​

Implementação que parece certa, não trata edge cases.

Fix: sempre forneça verificação (testes, scripts, screenshots). Se você não consegue verificar, não faz merge.

Exploração infinita​

Você pede pra "investigar" algo sem escopo. Ele lê centenas de arquivos.

Fix: escope a investigação ou delegue pra subagente.

Resumo Prático​

Pra cada sessão, lembre:

  1. /clear quando muda de tarefa
  2. Plan mode pra mudanças não-triviais
  3. Sempre forneça critério de verificação
  4. Delegue exploração e leitura verbosa pra subagents
  5. Skills > CLAUDE.md pra workflows específicos
  6. Hooks pra filtrar output e impor garantias
  7. Sonnet por padrão, Opus pra raciocínio profundo, Haiku pra subagents leves
  8. Course-correct rápido, não tente "salvar" sessão poluída

A diferença entre $10/dia e $50/dia no mesmo trabalho está exatamente nesses hábitos. E o $10/dia geralmente entrega código melhor, porque está trabalhando com janela limpa.

Próximo: Segurança

Referências: