🧹 The real reason: clean context

Every Claude Code session has a token limit — the context window. Everything you type, everything the model responds, every file read, every search made: it all takes up part of that window. When it fills up, the model starts to forget the beginning of the conversation. Using a subagent isn’t about doing two things at once—it’s about avoid letting raw reading poison your context ahead of time.

↑ Without a subagent: the raw reading consumes 90% of the window. With a subagent: only the summary goes in — context stays free for what matters.

Each Claude Code session has a token budget. A status line — that bar at the bottom of the terminal shows in real time how much of this budget you’ve used. As you approach the limit, the model starts to “forget” the oldest parts of the conversation. You can’t buy extra tokens midway through.

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%

This is the point most people miss: in Claude Code, when you ask it to read a file, the raw content enters your context window and stays there. It doesn't leave when reading is done. It doesn't disappear when you change the subject. It only disappears when the session ends. That means reading 50 files in the middle of a long task can consume the entire context window before you get to the part that matters.

Sometimes you should read the file yourself — when reading it is quick and you’ll need to reason about it right afterward. But when reading it is heavy, broad, or disposable (you only want the conclusion), sending a subagent protects your window. The distinction is simple: will anything useful remain in my window after I read this?

The subagent does the heavy reading in the its window — that it is separate, disposable, and disappears when it finishes. What returns to the conductor is only the structured output that you asked for: 3 facts, 1 paragraph, a list of paths, a number. None of the raw text the subagent read reaches your context window.

Saying that subagents are "faster" is technically true for parallel reads — but it's the wrong reason to use them. A serial subagent (one at a time) still protects the context window. The reason #1 is qualitative: a session with clean context reason more carefully, makes fewer “forgetting” mistakes and can continue to the end without degradation.

The course’s most compelling use case: you have 300 pages of financial reports and need to 3 facts for your presentation tomorrow. If the orchestrator reads all 300 documents, the context window will blow up. If an researcher (Haiku) read everything in its window and return only the 3 facts, your window stays at 15%.

O researcher is the archetypal context-protection subagent: it uses Haiku (cheap and fast), only reads (without writing or executing), and is explicitly instructed to return only the summary. It's the model you'll replicate for any "heavy reading → concise conclusion" task.

--- # 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 these prompts to delegate heavy research to researcher and keep your window clean. Notice the pattern: explicitly asking for only the conclusion and specify the output format.

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.

See how the status line of orchestrator barely moves while the researcher handles the heavy reading. The orchestrator is free to reason.

↑ Illustrative recreation of the terminal (not a real screenshot). Researcher consumes 204k tokens in its own window; your context stays at 14%.