Dicas de economia escondidas no código-fonte do Claude Code — reduza sua conta de API pela metade ao terminar

Dificuldade: Média | Duração: 25 minutos | Aprendizado: dominar 7 técnicas de economia no nível do código-fonte, reduzindo a conta de API em 30–60%

Perfil do público-alvo

Engenheiros full-stack que estão usando ou planejam usar profundamente o Claude Code, especialmente desenvolvedores individuais e pequenas equipes que se preocupam com o controle de custos de API. Se sua compreensão do Claude Code ainda está na fase de “instalar e usar”, este artigo vai mostrar quantos parâmetros ajustáveis ficam escondidos por trás dele.

Dependências centrais e ambiente

• Node.js 18+
• Claude Code 2.1.88
• Base de TypeScript (basta conseguir ler definições de tipos)
• npm ou pnpm
• Uma ANTHROPIC_API_KEY válida

Árvore completa de estrutura do projeto

# Estrutura do código-fonte do Claude Code (diretórios relacionados)
src/
├── cost-tracker.ts              # Núcleo do rastreamento de custos
├── costHook.ts                  # Hook de saída de custos
├── Tool.ts                      # Fábrica abstrata de ferramentas
├── tools.ts                     # Registro e filtragem de ferramentas
├── tools/
│   ├── BashTool/                # Ferramenta de execução de shell
│   │   └── BashTool.tsx
│   │   └── readOnlyValidation.ts # Lógica de validação somente leitura
│   ├── FileReadTool/            # Leitura de arquivos
│   ├── FileEditTool/            # Edição de arquivos
│   └── ...
├── services/
│   ├── compact/                 # Serviço de compressão de contexto
│   │   └── compact.ts
│   └── tools/
│       └── toolOrchestration.ts # Particionamento de concorrência de ferramentas
├── skills/
│   └── loadSkillsDir.ts         # Carregamento de skills
├── types/
│   └── permissions.ts           # Definição de modos de permissão
├── upstreamproxy/               # Proxy para upstream (nível enterprise)
│   ├── upstreamproxy.ts
│   └── relay.ts
└── utils/
    └── git.ts                   # Ferramentas de Git / Worktree

---

I. Como a conta do Claude Code fica mais cara

Antes de falar em economizar, vamos entender primeiro como o dinheiro é gasto. A conta de API do Claude Code é impulsionada principalmente por três fatores:

1. Total de tokens de contexto

Em cada conversa, o Claude Code empacota mensagens históricas, resultados de chamadas de ferramentas e conteúdo de arquivos para enviar à API. Quanto maior o contexto, maior o preço por solicitação. Em cost-tracker.ts, o consumo de cada session é rastreado com precisão:

// src/cost-tracker.ts
interface ModelUsage {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;    // Leitura do cache (mais barato)
  cacheCreationInputTokens: number; // Criação do cache (custo único)
  webSearchRequests: number;
  costUSD: number;
}

Aqui há dois pontos-chave: cacheReadInputTokens é cerca de 10 vezes mais barato que tokens de input comuns, e cacheCreationInputTokens é uma despesa única ao criar o cache — isso determina diretamente a estratégia de compressão que vem a seguir.

2. Frequência de chamadas de ferramentas

Em média, cada conversa dispara dezenas de chamadas de ferramentas. Cada chamada de ferramenta gera uma solicitação de API (streaming no uso da tool). Quanto mais ferramentas você usa e quanto mais frequentemente as chama, mais rápido o contexto “incha”.

3. Número de agents em concorrência

Ao iniciar um sub-AGENT com AgentTool, ou no modo Coordinator ao despachar vários Workers ao mesmo tempo, cada execução ocorre em uma sessão independente — e o custo dobra diretamente.

O Claude Code tem embutido cost-tracker.ts para rastrear esses consumos em tempo real. Ao sair, ele persiste os dados na configuração do projeto:

// src/costHook.ts
// Salva e imprime automaticamente um resumo quando o processo sai
process.on('exit', () => {
  if (hasConsoleBillingAccess()) {
    console.log(formatTotalCost()); // Saída com detalhamento por modelo
  }
  saveCurrentSessionCosts(getFpsMetrics?.());
});

---

II. Dicas de economia 1: Compactar contexto com o Compact, economize 30–50%

O Claude Code inclui um serviço compact que “compacta” as conversas históricas em resumos, mantendo o contexto dentro de um tamanho razoável. Os parâmetros-chave do código-fonte são bem claros:

// src/services/compact/compact.ts
const POST_COMPACT_TOKEN_BUDGET = 50_000;           // Limite total de tokens após compressão
const POST_COMPACT_MAX_TOKENS_PER_FILE = 5_000;      // Por arquivo: no máximo 5K tokens
const POST_COMPACT_MAX_TOKENS_PER_SKILL = 5_000;      // Por Skill: no máximo 5K tokens
const POST_COMPACT_SKILLS_TOKEN_BUDGET = 25_000;      // Limite total: 25K para todas as Skills somadas
const POST_COMPACT_MAX_FILES_TO_RESTORE = 5;          // Após compressão: no máximo restaurar 5 arquivos

O processo de compressão tem três etapas: gatilho → resumo por API → anexar novamente arquivos-chave. Primeiro ele dispara hooks pre_compact, chama a API de compressão (uma solicitação de API separada), depois dispara hooks post_compact e, por fim, anexa novamente os arquivos lidos mais recentemente.

Dica prática: ajustar o limite de disparo controla a frequência da compressão e, portanto, o custo.

// settings.json — em .claude/ na raiz do projeto
{
  "compact": {
    "autoCompactThreshold": 0.85  // Dispara quando o contexto chega a 85% (valor padrão)
  }
}

Baixar o limite (por exemplo, 0.7) faz a compressão acontecer com mais frequência: cada compressão custa menos, mas a qualidade do resumo pode cair um pouco. Aumentar o limite (0.95) faz o oposto.

---

III. Dicas de economia 2: Use bem ferramentas Read-only para evitar desperdício

Cada ferramenta do Claude Code tem um método isReadOnly() — ele determina se a ferramenta gera efeitos colaterais. O orquestrador de tools usa essa flag para decidir se pode executar em concorrência:

// src/Tool.ts — por padrão, as ferramentas são conservadoras (fail-closed)
const TOOL_DEFAULTS = {
  isConcurrencySafe: (_input) => false,  // por padrão, não é segura para concorrência
  isReadOnly: (_input) => false,          // por padrão, tem efeitos colaterais
  isDestructive: (_input) => false,        // por padrão, não é destrutiva
};

O ponto-chave aqui é o BashTool. Ele traz uma lógica detalhada de classificação de comandos:

// src/tools/BashTool/BashTool.tsx
// Lista branca de comandos somente leitura — estes comandos podem ser executados em concorrência com segurança, sem modificar qualquer estado
const BASH_SEARCH_COMMANDS = ['find', 'grep', 'rg', 'ag', 'ack', 'locate', 'which', 'whereis'];
const BASH_READ_COMMANDS   = ['cat', 'head', 'tail', 'less', 'more', 'wc', 'stat', 'file', 'strings', 'jq', 'awk', 'cut', 'sort', 'uniq', 'tr'];
const BASH_LIST_COMMANDS   = ['ls', 'tree', 'du'];
const BASH_SEMANTIC_NEUTRAL_COMMANDS = ['echo', 'printf', 'true', 'false', ':'];

Dica prática: quando você envia um comando ls -la para consultar a estrutura de um diretório, o Claude Code entende que é uma operação somente leitura e agrupa isso com outras operações somente leitura para executar em concorrência, reduzindo o tempo de espera. Mas se você executar rm -rf node_modules, isso será reconhecido como destrutivo: precisa ser tratado em série e, a cada vez, você será solicitado a confirmar.

Entendendo essa lógica, você pode organizar seus comandos de forma proativa para disparar uma otimização melhor de concorrência:

# Boa prática: operações somente leitura podem ser combinadas em um único comando, reduzindo chamadas de tool
find . -name "*.ts" | head -20 && wc -l src/**/*.ts

# Má prática: misturar operações destrutivas com comandos somente leitura
find . -name "*.log" && rm -rf logs/  # esta será bloqueada em série

---

IV. Dicas de economia 3: O sistema de Skills reduz Prompt repetido e economiza Prompt Tokens

O Claude Code suporta um sistema de Skills. Essencialmente, é um conjunto de trechos de prompt reutilizáveis. Quando você cria uma pasta skills/ na raiz do projeto e coloca nela arquivos Markdown, o Claude Code vai carregá-los automaticamente:

your-project/
└── skills/
    └── my-workflow/
        └── SKILL.md   # Formato do diretório: skill-name/SKILL.md

O arquivo de Skill tem frontmatter com metadados:

---
name: my-skill
description: Fluxo padrão para refatorar componentes React
whenToUse: Use quando precisar refatorar componentes ou dividir componentes grandes
paths: ["src/**/*.tsx", "src/**/*.ts"]  # Ativa apenas ao corresponder a esses caminhos
allowedTools: [Read, Edit, Bash]       # Limita ferramentas disponíveis
arguments: [filePath, scope]
executionContext: inline               # inline ou fork
---
# Corpo da Skill — aqui você escreve seu prompt padrão de refatoração

Por que economiza? toda vez que você inicia uma nova conversa, o Claude Code precisa colocar no system prompt toda a descrição das ferramentas, regras e contexto. Skills permitem padronizar fluxos comuns, reduzindo o consumo de tokens ao você digitar repetidamente as mesmas instruções — você economiza o tamanho do prompt que você normalmente copiaria/colaria manualmente.

O campo paths é a alma do mecanismo de ativação condicional: essa Skill só aparece na lista de candidatos quando os caminhos correspondem. Isso evita “poluição” do contexto com Skills irrelevantes:

// src/skills/loadSkillsDir.ts
// Ativação condicional usando match estilo gitignore
activateConditionalSkillsForPaths(filePaths, cwd) {
  // Ao acessar arquivos src/**/*.tsx, as Skills relacionadas a React são ativadas
}

---

V. Dicas de economia 4: Particionamento de concorrência reduz retries e poupa consumo de Rate Limit

O Claude Code não executa todas as chamadas de ferramentas em série. Ele tem um partionador inteligente: agrupa as tools que “podem rodar ao mesmo tempo” em um lote e trata as que “precisam ficar na fila” separadamente:

// src/services/tools/toolOrchestration.ts
// Lê o limite de concorrência; padrão é 10
function getMaxToolUseConcurrency() {
  return parseInt(process.env.CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY ?? '10', 10);
}

// Particiona chamadas de tools: sequências de somente leitura em um lote; caso contrário, começa um novo batch
function partitionToolCalls(toolUseMessages, toolUseContext): Batch[] {
  return toolUseMessages.reduce((acc, toolUse) => {
    const isConcurrencySafe = tool.isConcurrencySafe(parsedInput.data);
    if (isConcurrencySafe && acc[acc.length-1]?.isConcurrencySafe) {
      acc[acc.length-1].blocks.push(toolUse); // concorrência segura, faz merge
    } else {
      acc.push({ isConcurrencySafe, blocks: [toolUse] }); // novo lote
    }
    return acc;
  }, []);
}

Dica prática: se suas ferramentas MCP suportam concorrência, declare explicitamente isConcurrencySafe: true no momento da definição. Sem declaração, a ferramenta é considerada serial por padrão. A perda por concorrência reduzida é indireta: quando ferramentas seriais batem no Rate Limit, os retries desperdiçam tokens — e esse impacto acumulado pode ser considerável.

// settings.json — declare segurança de concorrência para suas tools MCP
{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": ["-y", "my-mcp-tool"],
      "isConcurrencySafe": true  // após declarar, pode ser executada em paralelo com outras tools somente leitura
    }
  }
}

O limite de concorrência também pode ser aumentado via variável de ambiente:

# Adequado para máquinas com bom desempenho e com cotas de API suficientes
export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=20

---

VI. Dicas de economia 5: Worktree isola em vez de clonar tudo — reduz contexto compartilhado de colaboração

O Claude Code traz suporte a Worktree. O Git Worktree permite você fazer checkout de múltiplos branches em diretórios diferentes dentro do mesmo repositório, sem precisar clonar várias vezes. O findCanonicalGitRoot do Claude Code reconhece automaticamente caminhos de Worktree:

// src/utils/git.ts
// resolve com segurança a raiz do Worktree
function resolveCanonicalRoot(gitRoot: string): string {
  const gitDirContent = readFileSync(path.join(gitRoot, '.git'), 'utf8');
  // formato do .git: gitdir: /path/to/.git/worktrees/<name>
  const commonDir = extractCommonDir(gitDirContent);
  // validação segura: worktreeGitDir precisa ser um subdiretório de commonDir/worktrees/
  // evita que um repositório malicioso use o .git para escapar do sandbox
  validateWorktreeSecurity(worktreeGitDir, commonDir);
  return mainRepoRoot;
}

Princípio de economia: se a sua equipe tem o hábito de clonar uma cópia do repositório para cada branch de feature, cada clone traz um diretório .git (que pode ter alguns GB) e o Claude Code inclui esse volume no escaneamento do contexto. No modo Worktree, há apenas um .git, e o volume escaneado cai drasticamente.

# Crie um Worktree (em vez de clonar outra cópia)
git worktree add ../feature-sidebar feature/sidebar

# O Claude Code identifica o Worktree automaticamente e compartilha o contexto do repositório principal
# Ao trocar para outro worktree, basta entrar com cd e iniciar o claude
cd ../feature-sidebar && claude

---

VII. Dicas de economia 6: Ajuste do modo de Permission para reduzir interações de confirmação

O Claude Code tem um sistema completo de permissões. São 5 modos que determinam quando as tools precisam da sua confirmação:

// src/types/permissions.ts
type PermissionMode =
  | 'acceptEdits'   // aceita automaticamente edições
  | 'bypassPermissions' // ignora completamente as checagens de permissão (perigoso, mas mais rápido)
  | 'default'       // pergunta de acordo com as regras
  | 'dontAsk'       // não pergunta
  | 'plan'          // modo Plan
  | 'auto';         // a IA classifica e decide automaticamente (quando TRANSCRIPT_CLASSIFIER está habilitado)

Dica prática: para diretórios totalmente confiáveis (seus próprios projetos, com código já versionado no git), você pode refinar a configuração no settings.json:

// ~/.claude/settings.json (nível de usuário) ou .claude/settings.json (nível do projeto)
{
  "permissions": {
    "defaultMode": "auto",
    "allow": [
      { "toolName": "Bash", "ruleContent": "pnpm*" },
      { "toolName": "Read" },
      { "toolName": "Glob" },
      { "toolName": "Grep" }
    ],
    "deny": [
      { "toolName": "Bash", "ruleContent": "rm -rf /" }
    ],
    "ask": [
      { "toolName": "Bash", "ruleContent": "git push" }
    ]
  }
}

O modo auto é um meio-termo entre economia de esforço e segurança — ele usa o classificador de IA para julgar se a operação é segura, evitando janelas de confirmação desnecessárias. A cada confirmação a menos, você economiza também o consumo de tokens do contexto por causa da troca de turno.

---

VIII. Dicas de economia 7: Cache de proxy upstream para empresas — reduz chamadas repetidas de API

O módulo upstreamproxy do Claude Code fornece roteamento de proxy para o Claude Code Connect (CCR, versão enterprise). No código-fonte, vale observar o valor de NO_PROXY_LIST:

// src/upstreamproxy/upstreamproxy.ts
const NO_PROXY_LIST = [
  'localhost', '127.0.0.1', '::1',
  '169.254.0.0/16', '10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16',
  'anthropic.com', 'github.com', '*.github.com',
  // npm / PyPI / Rust registry estão na whitelist; não precisam passar pelo proxy
  'registry.npmjs.org', 'pypi.org', 'files.pythonhosted.org',
  'index.crates.io', 'proxy.golang.org'
];

Dica prática: mesmo que você não use a versão enterprise, entender essa lógica pode ajudar a otimizar sua configuração local. Se você estiver em uma rede corporativa, o Claude Code vai rotear automaticamente o tráfego para o proxy da empresa. No nível do proxy, dá para fazer cache e reutilização de tokens — essa é a base para a economia dos usuários CCR enterprise.

Para serviços MCP auto-hospedados, você pode habilitar cache de resposta na configuração MCP:

// settings.json
{
  "mcpServers": {
    "local-knowledge": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "MCP_CACHE_TTL": "3600"  // cache por 1 hora, reduzindo chamadas repetidas de API
      }
    }
  }
}

---

IX. Solução de problemas comuns

Q1: Mesmo alterando só 1 linha, a conta continua alta?

A conta alta nem sempre vem de operações de edição; pode vir de “inchaço do contexto”. Em conversas longas, mesmo alterando só 1 linha, as mensagens históricas e resultados de ferramentas anteriores ainda ficam no contexto antes da compressão. Como verificar: ao encerrar a sessão, observe a saída de formatTotalCost() para inputTokens e compare com outputTokens. Se o inputTokens for maior, o contexto está mais inchado.

Q2: A qualidade da resposta cai claramente depois da Compactação?

Isso é um problema de granularidade da compressão. Ajuste autoCompactThreshold de 0.85 (padrão) para 0.95 para reduzir a frequência de compressão. Ao mesmo tempo, garanta que decisões importantes de design e informações de contexto sejam registradas de forma clara no começo da conversa — assim a qualidade do resumo após a compressão tende a ser maior.

Q3: o modo bypass é seguro mesmo?

Não é seguro, mas é controlável em um ambiente isolado. Se você realmente precisar usar bypass, sugiro usar permissions.deny como “proteção de contingência”:

{
  "permissions": {
    "defaultMode": "bypassPermissions",
    "deny": [
      { "toolName": "Bash", "ruleContent": "sudo*" },
      { "toolName": "Bash", "ruleContent": "curl*|wget*" }
    ]
  }
}

Q4: Como monitorar o consumo de Tokens por dia?

O Claude Code imprime automaticamente a conta ao final de cada sessão (se você tiver consoleBillingAccess). Uma abordagem mais sistemática é criar um script de rastreamento no nível do projeto:

# Adicione um hook post-checkout em .git/hooks do projeto para registrar
# Mas o mais prático é olhar diretamente em .claude/cost/<session-id>.json

Q5: As Skills consomem Tokens extras toda vez?

Sim, mas é controlável. O consumo de tokens do conteúdo da Skill é contabilizado no orçamento POST_COMPACT_SKILLS_TOKEN_BUDGET (limite de 25K). Quanto mais e mais detalhadas as Skills, maior o contexto; então o princípio para escrever Skills é: correspondência precisa, informação mínima necessária. Use bem o campo paths para carregar a Skill apenas quando arquivos relevantes forem acessados.

Q6: O comportamento do Claude Code fica estranho depois de usar Worktree?

O Worktree tem um mecanismo de validação de segurança. Se o formato do arquivo .git não for padrão, o Claude Code faz fallback para o diretório atual. Verifique se o conteúdo do arquivo .git está no formato gitdir: /absolute/path/to/.git/worktrees/<name>.

---

X. Leitura complementar / caminhos de aprimoramento

1. Escreva suas próprias Skills para reduzir engenharia repetida

Se você percebe que repetidamente escreve prompts do tipo “escreva código seguindo este estilo” em vários projetos, transforme isso em uma Skill e coloque em ~/.claude/skills/ para funcionar globalmente. Um trabalho, múltiplas economias.

2. Use MCP para construir uma toolchain local e substituir chamadas no cloud

Operações que consomem muitos tokens muitas vezes podem ser localizadas: busca de código, consultas de documentos e operações em banco de dados. Empacote essas capacidades em ferramentas MCP locais para reduzir dependência da API do Claude e, ao mesmo tempo, melhorar a velocidade de resposta.

3. Monitore logs do compact para otimizar continuamente a estratégia de contexto

Habilite o modo verbose para observar quando o compact dispara e qual o efeito da compressão. Ajuste continuamente autoCompactThreshold até encontrar o equilíbrio ideal para o tamanho do seu projeto.

claude --verbose 2>&1 | grep -i compact

4. Entenda o classificador de Permission a partir do código-fonte

O modo auto do Claude Code é baseado em um classificador de IA (Transcript Classifier): ele avalia o nível de risco com base no conteúdo da operação. Se você quiser aprofundar, pesquise a definição do tipo YoloClassifierResult dentro de src/types/permissions.ts.