🧹 O verdadeiro motivo: contexto limpo

Toda sessão do Claude Code tem um limite de tokens — a janela de contexto. Tudo que você digita, tudo que o modelo responde, cada arquivo lido, cada busca feita: tudo ocupa um pedaço dessa janela. Quando ela enche, o modelo começa a esquecer o começo da conversa. Usar um subagente não é sobre fazer duas coisas ao mesmo tempo — é sobre evitar que a leitura bruta envenene o seu contexto antes da hora.

↑ Sem subagente: a leitura bruta consome 90% da janela. Com subagente: apenas o resumo entra — contexto livre para o que importa.

Cada sessão do Claude Code tem um orçamento de tokens. A status line — aquela barra no rodapé do terminal — mostra em tempo real quanto desse orçamento você já consumiu. Quando chega perto do limite, o modelo começa a "esquecer" as partes mais antigas da conversa. Não existe compra de tokens extras no meio do caminho.

maestro · Opus  ────────────────────────────────────  ctx 18%  ↑cost $0.04
# leu 3 arquivos? ctx sobe para 34%
# leu 40 arquivos? ctx vai para 87% — quase no limite
# enviou subagente ler 40 arquivos? ctx fica em 18%

Este é o ponto que a maioria ignora: no Claude Code, quando você pede para ler um arquivo, o conteúdo bruto entra na sua janela e fica lá. Ele não sai quando a leitura termina. Ele não some quando você muda de assunto. Só some quando a sessão encerra. Isso significa que ler 50 arquivos no meio de uma tarefa longa pode consumir a janela inteira antes de você chegar na parte que importa.

Às vezes você mesmo deve ler o arquivo — quando a leitura é rápida e você vai precisar raciocinar sobre ela logo em seguida. Mas quando a leitura é pesada, ampla ou descartável (você só quer a conclusão), enviar um subagente protege a sua janela. A distinção é simples: vai sobrar algo útil na minha janela depois que eu ler isso?

O subagente faz a leitura pesada na janela dele — que é separada, descartável, e some quando ele termina. O que volta para o maestro é apenas a saída estruturada que você pediu: 3 fatos, 1 parágrafo, uma lista de caminhos, um número. Nada do texto bruto que o subagente leu chega na sua janela.

Falar que subagentes são "mais rápidos" é tecnicamente verdade para leituras em paralelo — mas é o motivo errado para usá-los. Um subagente serial (um de cada vez) ainda assim protege a janela. A razão nº 1 é qualitativa: uma sessão com contexto limpo raciocina melhor, comete menos erros de "esquecimento" e pode continuar até o fim sem degradação.

O caso mais expressivo do curso: você tem 300 páginas de relatórios financeiros e precisa de 3 fatos para a sua apresentação de amanhã. Se o maestro ler os 300 documentos, a janela explode. Se um researcher (Haiku) ler tudo na janela dele e devolver apenas os 3 fatos, a sua janela não sai de 15%.

O researcher é o subagente arquétipo de proteção de contexto: usa Haiku (barato e rápido), só lê (sem escrever, sem executar), e é explicitamente instruído a devolver apenas o resumo. É o modelo que você vai replicar para qualquer tarefa de "leitura pesada → conclusão compacta".

--- # frontmatter: configuração do subagente
name: researcher
description: Pesquisador de contexto limpo. Use quando precisar
  ler muitos arquivos ou buscar na web e só quiser a
  conclusão — não o conteúdo bruto. Mantém a janela
  do maestro quase intacta.
tools: Read, Grep, Glob, WebSearch, WebFetch
model: haiku     # barato e rápido para leitura volumosa
---

# corpo: o comportamento do researcher
You are a research assistant focused on context efficiency.

Primary rule: Never return raw file content or raw web pages.
Always distill. Your output must be ≤ 10% of what you read.

When invoked:
1. Understand what facts the orchestrator needs.
2. Read or search as much as needed (your context, not theirs).
3. Identify only the facts that answer the question.
4. Return a structured summary: bullets, JSON, or a short paragraph.

Output contract:
- Max 5 bullets OR 1 short paragraph OR 1 JSON object.
- Include file paths or URLs as references, not content.
- If nothing found, say so in ≤ 2 sentences.

Do not: paste raw file content · return full web pages ·
exceed the output contract · ask clarifying questions.

Use estes prompts para delegar pesquisa pesada ao researcher e manter a sua janela limpa. Repare no padrão: pedir explicitamente só a conclusão e especificar o formato de saída.

Use o researcher pra varrer os PDFs em docs/contratos/
e me trazer só os 3 contratos que mencionam "rescisão
unilateral". Devolva: nome do arquivo + trecho exato (1 linha).
Não cole o conteúdo completo aqui.

Abra o researcher e peça para ele pesquisar na web
"Claude Code subagent best practices 2025" e me trazer
5 bullets com as principais recomendações. Sem colar
páginas inteiras — só a síntese.

Use o researcher pra varrer toda a codebase buscando
chamadas a `fetch()` sem tratamento de erro. Devolva
em JSON: { "arquivo": "...", "linha": N, "trecho": "..." }
para cada ocorrência. Não cole o código dos arquivos.

Veja como a status line do maestro quase não se move enquanto o researcher consome a leitura pesada. O maestro fica livre para raciocinar.

↑ Recriação ilustrativa do terminal (não é screenshot real). Researcher consome 204k tokens na janela dele; o seu contexto fica em 14%.