Subagents
Subagents são assistentes especializados que rodam em uma janela de contexto separada, com prompt de sistema próprio, ferramentas restritas e permissões independentes. Quando o Claude principal delega uma tarefa, o subagente trabalha em isolamento e devolve só o resumo.
A motivação é simples: contexto é finito. Se você manda o Claude principal explorar um diretório com 200 arquivos, todo esse conteúdo entra na sua conversa e fica lá pra sempre. Se você delega pra um subagente, ele faz a mesma exploração no contexto dele e te devolve um sumário de 500 tokens.
Para que servem
- Preservar contexto: pesquisa, leitura de logs, exploração de codebase ficam fora da conversa principal
- Forçar restrições: subagente só usa as tools que você permitiu
- Reusar configurações: subagentes user-level funcionam em todos os projetos
- Especializar comportamento: prompt de sistema focado em um domínio
- Controlar custo: rotas para modelos mais baratos como Haiku para tarefas simples
Built-in Agents
O Claude Code já vem com alguns subagentes prontos:
| Agente | Para que serve |
|---|---|
general-purpose | Pesquisa complexa, busca de código, tarefas multi-step |
Explore | Exploração rápida de codebase (busca por padrão, keyword, perguntas) |
Plan | Arquiteto de software, desenha planos de implementação |
statusline-setup | Configura a statusline |
Você invoca via Task tool, geralmente assim:
Use um subagente Explore pra investigar como o sistema de auth lida com refresh de token.
Custom Subagents
Defina os seus em .claude/agents/<nome>.md:
---
name: security-reviewer
description: Revisa código por vulnerabilidades de segurança
tools: Read, Grep, Glob, Bash
model: opus
---
Você é um engenheiro sênior de segurança. Revise código por:
- Vulnerabilidades de injeção (SQL, XSS, command injection)
- Falhas de autenticação e autorização
- Secrets ou credenciais no código
- Manipulação insegura de dados
Forneça referências específicas de linha e fixes sugeridos.
Pra invocar: "Use o subagente security-reviewer pra revisar essa branch."
Frontmatter Reference
| Campo | O que faz |
|---|---|
name | Identificador do subagente |
description | Quando o Claude deve delegar (importante pra invocação automática) |
tools | Lista de ferramentas que o subagente pode usar |
model | Modelo específico (opus, sonnet, haiku, inherit) |
prompt ou corpo | System prompt do subagente |
Padrões de Uso
Investigação
Sua tarefa: implementar OAuth. Antes, você precisa entender o que já existe:
Use subagentes pra investigar como nosso sistema de autenticação lida com
refresh de token e se temos algum utilitário OAuth pré-existente que eu
deveria reutilizar.
O subagente lê 30 arquivos. Você recebe um relatório de 5 parágrafos. Sua janela permanece limpa pra implementação.
Verificação
Depois do Claude implementar:
Use um subagente pra revisar esse código por edge cases e race conditions.
Contexto fresco do reviewer pega coisas que o autor não pegaria.
Padrão Writer/Reviewer
Numa sessão, você faz o Claude escrever. Em outra (paralela), o reviewer revisa. O reviewer não está enviesado pelo código que acabou de escrever, então pega problemas que passariam batido.
Tarefas em paralelo
Se você precisa rodar várias tarefas independentes ao mesmo tempo, dispare múltiplos subagentes na mesma mensagem. O Claude principal coordena, eles trabalham em paralelo, retornam, e você consolida.
Skills + Subagents
Os dois mecanismos se combinam de duas formas:
Skill com context: fork
A skill define a tarefa, o subagente executa em isolamento:
---
name: deep-research
description: Pesquisa um tópico a fundo
context: fork
agent: Explore
---
Pesquise $ARGUMENTS:
1. Encontre arquivos relevantes via Glob/Grep
2. Leia e analise
3. Resume com referências específicas
Subagent com skills field
Um subagente customizado que pré-carrega skills como material de referência. Útil pra subagentes especializados que sempre precisam de certo contexto.
Custo de Subagentes
Cada subagente roda como uma instância separada do Claude com sua própria janela de contexto. Isso significa:
- Tokens de cada subagente contam separadamente
- O system prompt e contexto inicial são duplicados
- Subagentes que rodam em plan mode usam mais tokens (planejam antes de agir)
Para controlar custo:
- Use Sonnet ou Haiku pra subagentes de coordenação ou tarefas simples
- Reserve Opus para subagentes que precisam de raciocínio profundo
- Mantenha o spawn prompt focado: tudo que você passa entra no contexto inicial deles
Quando NÃO usar Subagentes
- Tarefa pequena que cabe na conversa principal sem poluir
- Você precisa do output verboso completo (não só do resumo)
- A tarefa depende fortemente de mensagens anteriores da conversa principal
- Edição que vai pingar muito de volta pro contexto principal mesmo
Best Practices
Description detalhada
A description é o que o Claude usa pra decidir delegar. Escreva como se fosse onboarding pra um colega: o que esse subagente faz, em que situações usar, e o que ele devolve.
Restrinja as tools
Se o subagente é pra revisão, não dê Bash ou Edit. Read, Grep, Glob resolvem. Restrição de tools = menos chance do subagente fazer algo inesperado.
Modelo certo pra tarefa
| Tarefa | Modelo recomendado |
|---|---|
| Exploração de codebase | Haiku ou Sonnet |
| Revisão de código | Sonnet ou Opus |
| Arquitetura, planejamento | Opus |
| Sumarização de logs | Haiku |
Prompt de sistema curto
Subagente com prompt de 50 linhas funciona melhor que com 500. Menos é mais.
Delegue cedo
Se você sente que vai precisar ler muitos arquivos pra responder uma pergunta, delegue antes de começar. Mais barato do que inflar a janela e ter que /clear depois.
Agent Teams
Existe uma feature mais avançada chamada Agent Teams que coordena múltiplas sessões em paralelo, com mensagens entre elas e um agente líder. É experimental (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) e usa significativamente mais tokens. Para a maioria dos casos, subagentes simples no Task tool resolvem.
Conclusão
Subagentes são uma das ferramentas mais poderosas pra controlar contexto. Internalize: investigar = subagente, revisar = subagente, processar log verboso = subagente. Sua conversa principal fica curta e focada na implementação. Você gasta menos token e o Claude trabalha melhor.
Próximo: Hooks
Referências: