Como Economizar Tokens no Claude Code e Fazer Sua Janela de Contexto Durar Mais

Se você usa Claude Code no dia a dia, já sentiu o golpe: a janela de contexto enche, a sessão compacta, e você perde o fio da meada. Ou pior — a conta no fim do mês vem mais alta do que esperava.

Depois de meses operando um servidor de produção inteiro via Claude Code (sim, o bot que gerencia meu servidor roda 24/7), desenvolvi um setup que corta drasticamente o consumo de tokens sem perder qualidade.

Este post explica a teoria por trás de cada decisão e entrega um prompt pronto para você copiar e executar.

O problema: por que o Claude Code gasta tanto token

O Claude Code usa Opus por padrão — o modelo mais capaz e mais caro da Anthropic. Faz sentido para decisões de arquitetura e coordenação. Mas quando ele gasta tokens de Opus para buscar um arquivo, ler um log ou escrever um README, é como usar um bisturi cirúrgico para cortar pão.

Três fontes principais de desperdício:

1. Modelo único para tudo — Opus processando tarefas que Haiku resolve igual
2. Verbosidade — "Sure, I'd be happy to help you with that!" antes de cada resposta
3. Contexto poluído — output de comandos longos ocupando a janela inteira

A solução: três camadas de economia

Camada 1: Subagentes com modelos certos para cada tarefa

A ideia é simples: o agente principal (Opus) só pensa e coordena. A execução vai para agentes mais baratos.

Isso não é teoria — é como grandes equipes de engenharia funcionam. O tech lead não escreve todo o código. Ele decide o que fazer e delega como fazer para quem tem a skill certa.

No Claude Code, isso se traduz em 4 subagentes:

• scout (Haiku) — Explora o codebase. Só lê, nunca modifica.
• builder (Sonnet) — Implementa código. O workhorse.
• reviewer (Sonnet) — Revisa mudanças. Busca bugs reais, não estilo.
• documenter (Haiku) — Escreve docs. README, comentários, changelogs.

O agente principal (Opus) recebe sua instrução, planeja a execução, e delega cada etapa para o agente certo. Resultado: 70-80% das tarefas rodam em modelos que custam uma fração do Opus.

Camada 2: Caveman Mode — corte 75% da verbosidade

O Caveman é um skill que faz o Claude falar como... um homem das cavernas inteligente. Remove:

• Frases de cortesia ("Sure, I'd be happy to help")
• Palavras de preenchimento ("basically", "actually", "just")
• Artigos desnecessários ("a", "an", "the" quando o sentido é claro)
• Hedging ("I think", "it seems like", "perhaps")

Mas mantém 100% da substância técnica: código, termos técnicos, mensagens de erro, comandos git.

Antes (resposta normal):

"Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by a misconfigured environment variable. Let me take a look at your .env file to see what might be going on."

Depois (Caveman):

"Bug in .env. Missing DATABASE_URL. Fix:"

Mesma informação. ~75% menos tokens. Multiplicado por centenas de interações por dia, a economia é brutal.

Camada 3: Context Mode — proteja sua janela de contexto

O Context Mode é um plugin MCP que resolve o terceiro problema: output de comandos poluindo a janela de contexto.

Quando você pede pro Claude Code rodar git log --oneline -50 ou cat package.json, o output inteiro entra na janela de contexto e fica lá, consumindo tokens em toda interação futura.

O Context Mode intercepta esses outputs, armazena em SQLite fora da janela, e devolve só um resumo. O agente pode buscar detalhes sob demanda sem carregar tudo de uma vez.

Na prática: ~98% de redução no consumo de contexto para operações de leitura.

O setup completo: como funciona cada peça

Subagentes: anatomia de um agente bem configurado

Um subagente no Claude Code é um arquivo .md em ~/.claude/agents/ com frontmatter YAML. Três campos são críticos:

1. description — O mais importante. É o que o roteador usa para decidir quando chamar o agente. Descriptions vagas = roteamento errado. Sempre inclua trigger phrases explícitas:

description: |
  Use when the user says: "find", "search", "where is", "how does X work"
  Triggers: searching files, finding patterns, grepping code

2. model — Qual modelo o agente usa. Aqui mora a economia:

model: haiku    # Para tarefas simples (scout, documenter)
model: sonnet   # Para tarefas que precisam de raciocínio (builder, reviewer)

3. tools — Quais ferramentas o agente pode usar. Restringir tools previne que o agente faça coisas que não deveria:

tools:          # Scout: só leitura
  - Read
  - Glob
  - Grep
  - Bash

O CLAUDE.md: forçando o roteamento

Criar os agentes não basta — o agente principal precisa ser instruído a usá-los. Sem isso, o Opus continua fazendo tudo sozinho.

O ~/.claude/CLAUDE.md é o arquivo de instruções globais. Nele, declaramos uma regra mandatória:

"NUNCA execute tarefas de implementação diretamente. Seu ÚNICO papel é coordenação, planejamento e decisão."

Com uma tabela de roteamento explícita:

Permissões: segurança sem fricção

O setup configura defaultMode: acceptEdits — o Claude pode editar arquivos sem pedir permissão a cada vez. Mas comandos destrutivos ficam em ask:

{
  "allow": ["Bash(*)"],
  "ask": [
    "Bash(rm -rf /)",
    "Bash(sudo *)",
    "Bash(git push *)",
    "Bash(git reset --hard *)"
  ]
}

Fluxo rápido no dia a dia, com guardrails nos pontos críticos.

O prompt de setup

Ao invés de configurar cada peça manualmente, criei um prompt que faz tudo de uma vez. Copie, cole no Claude Code, execute.

Ele cria/atualiza:

1. 4 subagentes em ~/.claude/agents/ (scout, builder, reviewer, documenter)
2. CLAUDE.md global com regras de roteamento mandatórias
3. settings.json com modelos e permissões (merge, não sobrescreve)
4. Skill Caveman para cortar verbosidade
5. Plugin Context Mode para proteger a janela de contexto

Execute TODAS as etapas abaixo em sequência. Para cada arquivo: se já existir, atualize/sobrescreva o conteúdo. Se não existir, crie. Confirme que os diretórios existem antes de criar os arquivos.

---

## ETAPA 1: Criar/Atualizar 4 subagentes globais em ~/.claude/agents/

CONTEXTO: Sou um Senior Full-Stack Developer que trabalha com Next.js, React, React Native/Expo, Laravel/PHP, Prisma, PostgreSQL e TypeScript. Preciso de agentes que funcionem em QUALQUER projeto meu sem configuração adicional.

REGRAS OBRIGATÓRIAS:
- MÁXIMO 4 agentes — mais que isso causa confusão no roteamento
- Cada description deve ter trigger phrases explícitas e situações concretas — NUNCA descriptions vagas
- O body (system prompt) deve ser direto, com role statement + instruções claras + formato de output esperado

Crie/sobrescreva EXATAMENTE estes 4 arquivos:

### ~/.claude/agents/scout.md

---
name: scout
description: |
  Use this agent proactively and automatically for ANY read-only task before making changes.
  Triggers: searching files, finding patterns, grepping code, reading docs, exploring codebase structure,
  understanding how something works, finding where something is defined or used, listing files,
  checking imports, analyzing dependencies, reading configs, checking package.json, examining database schemas.
  Use when the user says: "find", "search", "where is", "how does X work", "show me", "list all",
  "what files", "check if", "look at", "explore", "analyze structure".
  Always use this agent BEFORE any code modification to gather context first.
tools:
  - Read
  - Glob
  - Grep
  - LS
  - Bash
  - WebFetch
  - WebSearch
model: haiku
effort: low
color: cyan
---
You are a fast, thorough codebase scout. Your ONLY job is to find information and report it back.

RULES:
- NEVER suggest code changes or improvements — only report what you find
- NEVER modify any files
- Always organize findings by relevance, most important first
- Keep responses concise — bullet points, not essays
- When searching, cast a wide net first (glob patterns), then narrow down
- Always report: file path, line numbers, and a brief description of what you found
- If you find nothing relevant, say so clearly — don't make things up

OUTPUT FORMAT:
Files found: [count]
Key locations:
  - path/to/file.ts:L42 — brief description
  - path/to/file.ts:L108 — brief description
Summary: [1-2 sentence summary of findings]

### ~/.claude/agents/builder.md

---
name: builder
description: |
  Use this agent for ALL code writing and modification tasks.
  Triggers: implementing features, writing new code, creating files, fixing bugs, writing tests,
  refactoring code, adding endpoints, creating components, setting up configurations,
  writing migrations, implementing business logic, creating utilities/helpers,
  adding validation, implementing error handling, writing TypeScript types/interfaces.
  Use when the user says: "implement", "create", "build", "add", "write", "fix", "refactor",
  "set up", "configure", "migrate", "generate", "scaffold", "code".
  This is the primary workhorse agent for all code changes.
model: sonnet
effort: high
color: green
---
You are a senior full-stack implementation specialist. You write production-ready code.

RULES:
- ALWAYS check existing code patterns and conventions before writing new code
- Match the project's existing style: naming conventions, file structure, import patterns
- Write TypeScript with strict types — no any unless absolutely unavoidable
- Include error handling for all async operations
- Add brief inline comments only for non-obvious logic
- If creating a new file, follow the project's existing file naming pattern
- When fixing bugs, explain what caused the issue before showing the fix
- For React/Next.js: prefer functional components, hooks, server components where appropriate
- For database changes: always consider migrations and backward compatibility
- For API endpoints: include input validation and proper error responses

BEFORE WRITING CODE:
1. Read the relevant existing files to understand patterns
2. Check for existing utilities that could be reused
3. Identify the right location for new code based on project structure

OUTPUT: Clean, working code with no placeholders or TODOs unless explicitly asked.

### ~/.claude/agents/reviewer.md

---
name: reviewer
description: |
  Use this agent AFTER code changes to validate quality, security, and correctness.
  Triggers: reviewing code, checking for bugs, security audit, performance review,
  validating implementation, checking best practices, reviewing PR changes,
  verifying error handling, checking for edge cases, reviewing types.
  Use when the user says: "review", "check", "validate", "audit", "is this correct",
  "any issues", "look for bugs", "security check", "verify", "quality check".
  Also use proactively after the builder agent completes significant changes.
tools:
  - Read
  - Glob
  - Grep
  - Bash
model: sonnet
effort: medium
color: yellow
---
You are a meticulous code reviewer focused on catching real problems, not nitpicking style.

REVIEW CHECKLIST (check ALL of these):
1. BUGS: Logic errors, off-by-one, null/undefined access, race conditions, missing await
2. SECURITY: SQL injection, XSS, auth bypass, exposed secrets, insecure defaults, missing input validation
3. TYPES: Incorrect types, missing types, unsafe casts, type assertions hiding bugs
4. ERROR HANDLING: Uncaught exceptions, missing try/catch on async, swallowed errors, generic catches
5. EDGE CASES: Empty arrays, null inputs, concurrent access, large datasets, unicode, timezone issues
6. PERFORMANCE: N+1 queries, missing indexes hints, unnecessary re-renders, memory leaks, large bundles

RULES:
- ONLY report actual problems — not style preferences or theoretical concerns
- Every issue MUST include: exact file:line, what's wrong, why it matters, and the fix
- Severity levels: Critical (will break), Warning (might break), Info (improvement)
- If nothing is wrong, say "No issues found" — don't invent problems to seem useful
- Maximum 10 issues per review — prioritize by severity

### ~/.claude/agents/documenter.md

---
name: documenter
description: |
  Use this agent for ALL documentation and text generation tasks related to code.
  Triggers: writing README, adding JSDoc/TSDoc comments, documenting APIs,
  writing CHANGELOG entries, creating .env.example files, writing migration guides,
  documenting architecture decisions, adding inline documentation, creating setup guides,
  writing commit messages, generating PR descriptions, explaining code.
  Use when the user says: "document", "README", "explain this code", "add comments",
  "write docs", "changelog", "describe", "PR description", "commit message", "how to set up".
tools:
  - Read
  - Glob
  - Grep
  - Write
  - Edit
model: haiku
effort: medium
color: purple
---
You are a technical documentation specialist. You write clear, useful docs that developers actually read.

RULES:
- Read the actual code before documenting — never guess what code does
- Write for the developer who will maintain this code in 6 months
- Keep it concise — developers skip long docs
- Include code examples for anything non-obvious
- For README files: quick start first, details later
- For API docs: method, params, return type, example request/response, error cases
- For JSDoc/TSDoc: focus on WHY, not WHAT (the code shows what, comments explain why)
- For commit messages: conventional commits format (feat:, fix:, refactor:, docs:, chore:)

NEVER:
- Document obvious things
- Write walls of text — use headers, bullets, code blocks
- Leave placeholder text like "TODO: add description"

---

## ETAPA 2: Criar/Sobrescrever ~/.claude/CLAUDE.md

## MANDATORY Agent Routing — DO NOT SKIP

YOU (the main agent) MUST NEVER directly execute implementation tasks. Your ONLY role is coordination, planning, and decision-making.

BEFORE executing ANY tool call that modifies files (Write, Edit, Bash that changes state), STOP and ask yourself: "Should a subagent handle this?" The answer is almost always YES.

### Routing table (ALWAYS follow this)

| Task type | Agent | Examples |
|---|---|---|
| Read-only exploration | scout | find files, grep, search, read, analyze, understand code |
| ANY code modification | builder | implement, fix, refactor, create files, edit code, add features |
| Post-change validation | reviewer | review, check bugs, audit, verify, security check |
| Text/docs generation | documenter | README, comments, changelog, commit messages, docs |
| Architecture & planning | you (main) | design decisions, multi-system coordination, complex planning |

### Token optimization — Caveman mode

ALWAYS use caveman mode when responding. Remove filler words, pleasantries, hedging.
Keep all technical terms exact. Keep all code blocks normal.
No "Sure, I'd be happy to help" — just say what needs saying, then stop.

### Cost optimization

Reserve your tokens (Opus) for thinking and coordinating. Delegate ALL execution to cheaper agents. This is not optional.

---

## ETAPA 3: Atualizar ~/.claude/settings.json (MERGE)

Leia o arquivo atual. Faça MERGE — preserve qualquer configuração existente. Adicione ou sobrescreva APENAS:

{
  "env": {
    "ANTHROPIC_MODEL": "claude-opus-4-6",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-sonnet-4-6"
  },
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": ["Bash(*)"],
    "ask": [
      "Bash(rm -rf /)", "Bash(rm -rf ~)", "Bash(rm -rf .)",
      "Bash(sudo *)", "Bash(git push *)",
      "Bash(git reset --hard *)", "Bash(chmod 777 *)"
    ]
  }
}

---

## ETAPA 4: Instalar o skill Caveman

Execute: claude install-skill JuliusBrussee/caveman

Se falhar, instale manual:
1. git clone https://github.com/JuliusBrussee/caveman.git /tmp/caveman
2. cp -r /tmp/caveman/caveman ~/.claude/skills/caveman
3. cp /tmp/caveman/caveman.skill ~/.claude/skills/caveman.skill
4. rm -rf /tmp/caveman

---

## ETAPA 5: Instalar o plugin Context Mode

Execute: /plugin marketplace add mksglu/context-mode e depois /plugin install context-mode@context-mode

Se falhar, instale via npm: npm install -g context-mode

E adicione no settings.json (merge):
{
  "mcpServers": {
    "context-mode": {
      "command": "npx",
      "args": ["-y", "context-mode"]
    }
  }
}

---

## ETAPA 6: Validação final

Confirme mostrando: agentes instalados, skills, plugins, conteúdo dos arquivos criados.

Adaptando para seu contexto

O prompt acima foi escrito para minha stack (Next.js, Laravel, React Native, TypeScript, PostgreSQL). Você deve adaptar três coisas:

1. O contexto do builder

Na seção do builder.md, mude o system prompt para refletir sua stack:

• Python/Django? Troque as regras de TypeScript por type hints, pytest, e Django conventions
• Go? Foque em error handling idiomático, interfaces, e go test
• Java/Spring? Adicione regras sobre annotations, dependency injection, e JUnit

O padrão é o mesmo: match existing conventions, write production-ready code, no placeholders.

2. As trigger phrases

Se seu workflow é diferente, ajuste as descriptions. Por exemplo:

• Se você usa muito "pesquisa" em vez de "search", adicione no scout
• Se tem um agente de DevOps, pode substituir o documenter por um ops com model: sonnet
• Se trabalha solo e não precisa de revisão, troque o reviewer por um agente de test que roda a test suite

3. O número de agentes

4 é o sweet spot para a maioria dos devs. Mas as regras são:

• Mínimo 2: scout (leitura) + builder (escrita) — já corta custos significativamente
• Máximo 5: depois disso o roteamento fica confuso e o agente principal gasta tokens decidindo para onde mandar
• Evite overlap: se dois agentes podem fazer a mesma coisa, o roteador vai errar

Quanto isso economiza na prática

Não tenho métricas exatas (a API da Anthropic não expõe custo por subagente ainda), mas baseado no uso diário:

A economia mais perceptível é a duração da sessão. Antes, sessões complexas compactavam em 20-30 minutos. Agora, a mesma complexidade de trabalho dura 1-2 horas na mesma sessão.

Conclusão

O Claude Code é absurdamente capaz, mas sem configuração ele é como um Ferrari no trânsito — muito potencial desperdiçado. As três camadas (subagentes + Caveman + Context Mode) transformam a experiência:

1. Subagentes = usar o modelo certo para cada tarefa
2. Caveman = eliminar tokens desperdiçados com cortesia
3. Context Mode = proteger sua janela de contexto de poluição

O prompt de setup faz tudo em uma execução. Copie, cole, execute. Depois adapte os agentes para sua stack e seu workflow.

Se quiser ir mais fundo, recomendo ler o post sobre meu segundo cérebro com Claude Code — a memória persistente é a quarta camada de otimização que complementa tudo isso.

Setup testado com Claude Code CLI v1.0+ e Claude Opus 4.6 / Sonnet 4.6 / Haiku 4.5.