Subagents — delegando sem sujar o contexto

Subagent é uma instância nova do Claude que roda uma tarefa isolada e te devolve só o resultado. O contexto dele não entra no teu. A sua conversa fica limpa.

Por que usar

Três motivos práticos:

1. Contexto isolado: pesquisa que envolve ler 20 arquivos não precisa inflar sua sessão. O subagent lê, resume, e você recebe 3 parágrafos.
2. Economia de token: teu contexto principal não incha com exploração. Você paga a exploração uma vez.
3. Paralelismo mental: delega “descobre X” enquanto você segue codando outra coisa.

Quando delegar

• “Procura onde essa função é usada no monorepo”
• “Lê a doc da lib Y e me diz se suporta Z”
• “Analisa esses 3 PRs recentes e resume o que mudou na arquitetura”
• “Debuga por que esse teste tá flaky” (o subagent roda várias vezes sem encher teu contexto com logs)

Quando fazer direto

• Tarefa que vai gerar pergunta de volta (“qual convenção você prefere?”) — subagent não conversa bem
• Edição de código que depende do contexto atual da conversa
• Coisa rápida, 1-2 arquivos — o overhead não compensa

Exemplo na prática

Você tá no meio de implementar uma feature e precisa saber como o time trata erros de API em outro módulo. Sem subagent, você pede “lê src/api/*.ts e me diz o padrão de erro” — o Claude lê 15 arquivos e teu contexto vai pras cuecas.

Com subagent:

Usa um subagent pra investigar o padrão de error handling
em src/api/. Quero saber: que tipo de erro é lançado, se tem
classe custom, como logs são feitos. Resposta em até 10 linhas.

O subagent lê os arquivos, processa, e volta com:

Padrão atual:
- Classe `ApiError` em src/api/errors.ts com code + message
- Toda rota faz try/catch e loga via `logger.error({ err, ctx })`
- Erros esperados viram 4xx, inesperados viram 500 + Sentry

Teu contexto ganhou 10 linhas úteis em vez de 2000 linhas de arquivo.

Subagents custom

Você pode criar subagents especializados em .claude/agents/<nome>.md:

---
name: pesquisador
description: Investiga padrões no código e retorna resumo conciso. Use pra exploração, não pra edição.
tools: Read, Grep, Glob
---

Você é um investigador. Lê o código que for necessário e
responde em no máximo 15 linhas. Nunca edita arquivo.
Se a pergunta for ambígua, assume a interpretação mais comum
e segue — não pergunta de volta.

Limitar as tools é importante: subagent de pesquisa não precisa de Edit nem Bash.

Gotcha

Subagent não tem memória entre invocações. Cada chamada começa do zero. Se você precisa de continuidade (“agora com base no que achou, faz X”), ou você passa o resultado de volta no prompt, ou você faz direto na conversa principal.