🎯 O que é um subagente
Um subagente é um agente invocado pelo agente principal que executa uma tarefa em sua própria janela de contexto. Ele começa do zero, tem system prompt próprio, tools específicas, e devolve apenas um resumo final ao pai.
📚 Definição oficial (Anthropic docs)
"Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions. A subagent's context window starts fresh (no parent conversation)."
Fonte: docs.claude.com · Subagents
Relação pai ↔ subagente
- • Contexto acumulado da sessão
- • Você (usuário) conversa direto
- • Decide quando invocar subagente
- • Recebe apenas o resumo final
- • Não "vê" o trabalho interno do filho
- • Contexto novo, isolado
- • System prompt próprio
- • Tools configuráveis (limitadas ou amplas)
- • Executa, gera resumo, morre
- • Não vê conversa do pai
🧠Mental model
Pense no subagente como um funcionário terceirizado: você passa o briefing, ele faz o trabalho em sala separada, volta com o relatório. Você nunca vê rascunhos, cafés tomados ou discussões internas. Só o resultado.
📦 Quando usar subagentes
Regra prática: se o resultado final cabe em 300 palavras mas o caminho para chegar lá lê 50k tokens — delegue. Subagente brilha em qualquer operação verbosa onde só o resumo importa.
Pesquisa em repositório
"Encontre onde está implementada a autenticação em OAuth neste projeto." Lê 20 arquivos, retorna 3 paths + função.
Análise de documento longo
"Resuma este contrato de 40 páginas em bullets por cláusula." Input de 60k tokens, retorno de 500.
Web research
"Pesquise melhores práticas de cache HTTP para APIs REST em 2025." Visita 15 páginas, retorna síntese.
Análise de logs
"Identifique padrões de erro em logs/app.log dos últimos 3 dias." Lê arquivo gigante, retorna top 5 erros.
Diagnóstico de bug
"Rastreie por que getUserById retorna null às vezes." Lê código, stack trace, retorna hipótese + fix.
Síntese multi-fonte
"Compare abordagens A, B e C em docs/adr/*.md." Lê todas ADRs, retorna matriz comparativa.
✓ Delegue quando
- ✓Resultado útil é 1–2 parágrafos
- ✓Caminho envolve ler >3 arquivos
- ✓Não vai precisar iterar nos detalhes
- ✓Output verboso atrapalharia a sessão
✗ NÃO delegue quando
- ✗Precisa ver o código linha a linha
- ✗Vai iterar várias vezes no mesmo arquivo
- ✗Tarefa já é pequena (<5k tokens)
- ✗Conversação contínua sobre o resultado
🎭 Tipos prontos no Claude Code
O Claude Code já vem com um time de subagentes nativos que cobrem os casos mais comuns. Conhecer cada um ajuda a escolher o mais leve para cada trabalho.
Subagentes disponíveis
| Agente | Melhor para | Tools | Custo relativo |
|---|---|---|---|
| Explore | Busca rápida no repo, encontrar código por descrição | Glob, Grep, Read | baixo |
| general-purpose | Tarefas multi-step, pesquisa complexa | Todas disponíveis | médio–alto |
| web-research-assistant | Pesquisa profunda na internet, síntese de fontes | WebSearch, WebFetch | médio |
| Plan | Criar plano de execução detalhado antes de codar | Read, Grep, Glob | baixo–médio |
| code-reviewer | Auditoria de diff, review antes de PR | Read, Bash (git) | baixo |
Custo relativo considera turnos típicos + verbosidade esperada de cada tipo.
💡Regra de escolha
Comece sempre pelo mais específico. Explore para busca no repo, Plan para planejamento, code-reviewer para review. Caia em general-purpose só quando a tarefa for realmente multi-faceta.
🏷️ Criando agentes customizados
Agentes customizados ficam em .claude/agents/ no repositório. Cada um é um arquivo markdown com frontmatter YAML + system prompt.
Anatomia de .claude/agents/sec-review.md
---
name: sec-review
description: Revisa um diff em busca de vulnerabilidades de segurança comuns (SQL injection, XSS, secrets hardcoded, auth ausente). Acione antes de fazer merge de mudanças em rotas HTTP, queries SQL, ou arquivos de configuração.
tools:
- Read
- Grep
- Glob
- Bash
model: claude-sonnet-4-6
---
Você é um auditor sênior de segurança. Analise o diff fornecido e produza um relatório estruturado:
## Formato de saída
1. **Resumo** (1 parágrafo, veredito: SAFE / RISK / BLOCK)
2. **Achados críticos** (lista numerada, cada um com: arquivo:linha, descrição, correção sugerida)
3. **Observações** (bullets de coisas menores)
## Regras
- Seja específico: cite arquivo e linha
- Não invente vulnerabilidades — cite apenas o que você viu
- Priorize OWASP Top 10
- Termine sempre com recomendação clara: pode dar merge ou nãoCampos do frontmatter
| Campo | Obrigatório | Descrição |
|---|---|---|
| name | sim | ID único, kebab-case |
| description | sim | Quando acionar — é a chave para auto-invocação |
| tools | opcional | Lista de tools permitidas. Omitido = todas |
| model | opcional | Força um modelo específico (Haiku para barato, Opus para caro) |
💡A descrição é o gatilho
O campo description é lido pelo agente principal para decidir se aciona o subagente. Seja específico sobre quando, não só sobre o quê. "Revisa diff" é fraco; "Acione antes de fazer merge em rotas HTTP" é forte.
🧰Ideias para sua pasta .claude/agents/
- 📦 migrator — Plano de migração framework X → Y
- 🗃️ dba — Review de queries SQL e índices
- 🔐 sec-review — Auditoria de segurança de diff
- 📝 doc-writer — Gera README a partir do código
- 🧪 test-generator — Lê função e propõe casos de teste
- 🎨 a11y-checker — Revisa HTML em busca de problemas de acessibilidade
💡 Pai só recebe o resumo
Essa é a feature mais importante (e mais subestimada) dos subagentes: o contexto é completamente isolado. O pai não enxerga o que o filho leu, pensou ou gerou internamente — só o texto final.
Contexto do pai: com vs sem delegação
Tudo isso FICA no contexto até o fim da sessão.
Contexto principal ficou limpo. 50× menos tokens.
📝Controle o formato do resumo
Como você só vê o output final, instrua o subagente sobre o formato dele. Exemplo ruim vs bom:
"Pesquise onde usamos OAuth"
"Pesquise onde usamos OAuth. Responda: 1) arquivo principal, 2) providers configurados, 3) rota de callback. Max 100 palavras."
⚠️ Cuidado: você não pode "perguntar depois"
Se precisar de detalhe que não veio no resumo, terá que invocar o subagente de novo (e ele começa do zero). Isso incentiva a dar briefing completo de primeira.
💰 Economia: output verboso fica no subagente
Aqui está a conta do dinheiro: para a mesma tarefa real, comparamos o contexto acumulado no agente principal com e sem delegação. A diferença é da ordem de dezenas de vezes.
Tarefa: "mapeie todo o fluxo de checkout do projeto"
| Etapa | Sem delegação (pai) | Com delegação (pai) |
|---|---|---|
| Listagem de arquivos (Glob) | +2.000 | 0 |
| Leitura de 12 arquivos | +28.000 | 0 |
| 4 Greps intermediários | +3.500 | 0 |
| Análise raciocinando em voz alta | +4.000 | 0 |
| Resumo final entregue | +800 | +800 |
| Total adicionado ao contexto do pai | ~38.300 tokens | ~800 tokens |
menos tokens no pai, para a mesma tarefa e mesmo resultado útil
💸 Sem delegação — custo total
✅ Com delegação — custo total
🎯Por que é exponencial
O que fica no contexto do pai é relido a cada turno seguinte. Então +38k na pesquisa vira 760k+ ao longo de 20 turnos. O subagente paga o custo uma vez e morre. Por isso a economia multiplica com o tempo.
📋Resumo do Módulo
Próximo módulo:
4.2 — 📚 Dividir Tarefas Grandes em Sessões
Fluxo canônico, exemplos reais, quando NÃO dividir.