Como economizar tokens no Claude Code: /context, /compact, subagentes e cache

Pra economizar tokens no Claude Code, mantenha o contexto pequeno. Rode /context pra ver o que ocupa espaço. Use /clear ao trocar de tarefa e /compact com instruções nas pausas entre tarefas. Mande leituras pesadas, como testes e logs, pra um subagente. Escolha o modelo no começo da sessão, porque cada modelo tem o próprio prompt cache e trocar no meio reprocessa tudo. E corte o que carrega antes do primeiro prompt: CLAUDE.md comprido e servidores MCP que você não usa.

A regra está na documentação de custos do Claude Code: o custo em tokens cresce com o tamanho do contexto. Cada mensagem reenvia a conversa inteira. O prompt cache barateia a parte que se repete, mas não zera.

O que testei e o que não testei. O /context roda sem login no modo não interativo (claude -p "/context"), então as tabelas de contexto deste guia são saídas reais do Claude Code 2.1.296. /compact, /usage e o comportamento do cache precisam de sessão logada. Pra esses, a fonte é a documentação, e as saídas estão marcadas como exemplo. A parte conceitual de context engineering está em harness, RAG e context engineering.

Como ver o que está gastando tokens com /context?

Dentro da sessão, rode /context. Ele mostra o uso por categoria e sugere onde cortar. Fora da sessão, claude -p "/context" imprime a mesma tabela em markdown. Esta é a saída numa pasta vazia, sem CLAUDE.md e sem MCP:

$ claude -p "/context"
## Context Usage

**Model:** claude-opus-5-5
**Tokens:** 15.7k / 1m (2%)

### Estimated usage by category

| Category                | Tokens | Percentage |
|-------------------------|--------|------------|
| System prompt           | 1.9k   | 0.2%       |
| System tools            | 11.9k  | 1.2%       |
| System tools (deferred) | 15.1k  | 1.5%       |
| Skills                  | 2k     | 0.2%       |
| Free space              | 951.3k | 95.1%      |
| Autocompact buffer      | 33k    | 3.3%       |

Repare que as linhas (deferred) ficam fora do total: a soma de System prompt, System tools e Skills dá os 15.7k, salvo arredondamento. Elas são ferramentas adiadas, que só entram de fato quando o Claude precisa delas. Os números variam com versão, modelo e configuração.

Quanto custa um CLAUDE.md grande?

O CLAUDE.md entra no contexto no início de toda sessão. Criei na mesma pasta um CLAUDE.md sintético de 302 linhas, cada uma com uma regra de uma frase, e rodei de novo:

$ wc -l CLAUDE.md
302 CLAUDE.md

$ claude -p "/context"
...
**Tokens:** 29.2k / 1m (3%)
...
| Memory files            | 12.3k  | 1.2%       |
...
### Memory Files

| Type    | Path                   | Tokens |
|---------|------------------------|--------|
| Project | /tmp/ctx-lab/CLAUDE.md | 12.3k  |

São 12.3k tokens a mais em toda sessão, antes de você digitar nada. A documentação recomenda manter o CLAUDE.md abaixo de 200 linhas e mover instruções de fluxos específicos, como revisão de PR ou migração de banco, pra skills, que só carregam quando chamadas. O detalhe de como fazer está em como escrever um CLAUDE.md e como criar uma Skill.

Quando usar /clear, /compact ou /rewind?

Os três reduzem o contexto, cada um de um jeito:

Antes do /clear, rode /rename pra achar a sessão depois com /resume. Pro /compact, diga o que preservar:

/compact Foque nos testes que falharam e nas mudanças em auth.ts

Ou deixe a instrução fixa no CLAUDE.md. Este é o exemplo da documentação:

# Compact instructions

When you are using compact, please focus on test output and code changes

O que sobrevive ao /compact?

Segundo a página de context window: o CLAUDE.md da raiz e a memória automática voltam do disco. Até cinco arquivos lidos ou editados voltam, os modificados mais recentemente primeiro. Regras com paths: e CLAUDE.md de subpastas só voltam quando o Claude ler de novo um arquivo que as dispara. Se uma regra tem que valer depois da compactação, ponha no CLAUDE.md da raiz.

O /compact não sai de graça. Pra gerar o resumo, o Claude Code manda uma requisição com a conversa inteira. Com o cache quente, essa leitura sai pela tarifa de cache e custa uma fração do tamanho do contexto. Depois de uma pausa maior que a vida do cache, ela é reprocessada do zero. Por isso a documentação sugere compactar entre tarefas, em vez de esperar a compactação automática no meio de uma.

Como o prompt cache afeta o custo?

O modelo não lembra nada entre requisições, então o Claude Code reenvia tudo a cada mensagem. O cache casa o começo da requisição, o prefixo, com o que a API processou há pouco e cobra essa releitura pela tarifa de cache. O casamento é exato: se algo muda no começo, tudo o que vem depois é reprocessado. A explicação completa está na página de prompt caching.

O que invalida o cache, pela documentação:

• Trocar de modelo com /model. Cada modelo tem o próprio cache.
• Mudar o effort level, na maioria dos modelos.
• Ligar o fast mode.
• Conectar ou remover um servidor MCP quando as ferramentas carregam de cara, sem tool search.
• O próprio /compact, por design.
• Acumular muitas imagens, até o Claude Code precisar remover as mais antigas.
• Atualizar o Claude Code. A primeira sessão depois da atualização monta o cache do zero.

O que mantém o cache: editar arquivos do repositório, trocar o modo de permissão, chamar skills e comandos, usar /rewind e disparar um subagente. Editar o CLAUDE.md no meio da sessão também não quebra o cache, mas a edição só passa a valer depois de /clear, /compact ou reinício.

Quanto tempo o cache dura?

Cada requisição que acerta o cache reinicia o relógio. Se você usa API key e faz pausas longas, dá pra pedir 1 hora pra conversa principal com a setting promptCacheTtl ou a variável CLAUDE_CODE_PROMPT_CACHE_TTL=1h (Claude Code 2.1.242 ou mais novo):

{
  "promptCacheTtl": "1h"
}

A escrita no cache de 1 hora é cobrada a uma tarifa maior. Só compensa se você realmente fica parado mais de cinco minutos entre mensagens.

Como saber se o cache está funcionando?

Rode /usage. Desde a versão 2.1.251, o bloco Session ganha uma linha Prompt cache (main). Exemplo da documentação, não é uma saída minha:

Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · 1 expected rebuild (compaction or tool-result clearing) · warm (1h TTL, last activity 40s ago)

Muitos misses em sequência indicam que algo no prefixo está mudando. Desde a 2.1.260, a linha tenta apontar a causa, por exemplo likely cause: tool definitions changed.

Subagentes economizam tokens?

Eles economizam contexto da conversa principal, que é outra coisa. A tática da documentação é mandar pra um subagente o que gera muita saída: rodar a suíte de testes, buscar documentação, processar log. A saída verbosa fica no contexto dele e só o resumo volta pra você. O exemplo de prompt da documentação:

Use a subagent to run the test suite and report only the failing tests with their error messages

Só que as requisições do subagente também contam no seu uso, e ele não lê o cache da conversa principal, porque o prefixo dele é outro. Pra gastar menos, a documentação sugere um modelo menor pro subagente, como model: haiku na configuração dele. Use como tática pontual, pra leitura pesada.

O que mais reduz tokens no Claude Code?

• Escolha o modelo no começo. A documentação diz que o Sonnet resolve a maior parte das tarefas de código e custa menos que o Opus. Trocar no meio da sessão zera o cache.
• Baixe o esforço em tarefa simples. Tokens de thinking são cobrados como saída. Use /effort ou ajuste em /model.
• Desligue no /mcp os servidores que você não usa, e prefira um CLI como gh ou aws quando ele existir, porque o CLI não adiciona lista de ferramentas. A configuração de MCP está em como configurar MCP no Claude Code.
• Filtre saída com hooks. Um hook PreToolUse pode trocar npm test por uma versão que só mostra as falhas. Veja como configurar hooks no Claude Code.
• Seja específico no prompt. "Adicione validação de input na função de login em auth.ts" faz o Claude ler menos arquivos que "melhore este código".
• Use o plan mode (Shift+Tab) em tarefa complexa e aperte Esc assim que o Claude for pro lado errado.

Uma medição sobre o tool search, numa pasta com quatro servidores MCP HTTP configurados. Desligar o tool search quase dobrou o contexto inicial:

$ claude -p "/context"                          # tool search ligado (padrão)
**Tokens:** 20.3k / 1m (2%)

$ ENABLE_TOOL_SEARCH=false claude -p "/context"
**Tokens:** 39k / 1m (4%)
| System tools            | 28.3k  | 2.8%       |
| MCP tools               | 2.2k   | 0.2%       |

A maior parte do salto veio das ferramentas internas do próprio Claude Code, que também deixam de ser adiadas. As ferramentas MCP somaram 2.2k. Deixe o tool search no padrão.

Por que o uso sobe numa sessão longa?

A documentação lista os motivos mais comuns:

• Contexto longo: cada mensagem carrega a conversa inteira, então uma pergunta de uma linha numa sessão aberta o dia todo paga pela conversa toda, mesmo pela tarifa de cache.
• Cache frio: a primeira mensagem depois de uma pausa maior que a vida do cache reprocessa tudo.
• Tarefas agendadas, subagentes e teammates: cada um manda as próprias requisições.
• Compactação: o /compact de um contexto grande é, ele mesmo, uma requisição grande. Se você quer recomeçar, o /clear não custa nada.

Perguntas frequentes

Leia também

• Claude Code é um harness, o guia principal de Claude Code
• Harness, RAG e context engineering, o conceito por trás de manter o contexto pequeno
• Como configurar MCP no Claude Code
• Como escrever um CLAUDE.md que o agente segue
• Como configurar hooks no Claude Code

Quer reduzir o custo dos agentes de IA do seu time? Fale com a Capiva.