Morpheus não pilota, não combate, não escapa. Ele chama a tripulação certa para cada missão.
O que é um Subagent?
Quatro propriedades que separam um subagente de uma capacidade injetada no contexto principal.
Contexto isolado
Janela própria. O subagente não vê seu histórico, e você não vê o rascunho dele.
Especialista
Uma persona, um job. Revisor, auditor, gerador de testes; cada um faz uma coisa bem.
Retorna só resultado
O capitão recebe a conclusão limpa. Todo o ruído da investigação fica do outro lado.
Paralelismo nativo
Três subagentes podem rodar ao mesmo tempo. Uma missão, vários especialistas.
Subagent · Skill · Command · Hook
Quatro peças do ecossistema. Quatro papéis. O subagente é o único que roda fora do seu contexto.
Onde a tripulação descansa
Cada subagente é um arquivo Markdown. O nome do arquivo vira o nome da função na nave.
# Subagents do projeto: viajam com o repositório .claude/ └── agents/ ├── code-reviewer.md # revisa diffs ├── security-auditor.md # varredura OWASP ├── doc-writer.md # gera READMEs ├── test-generator.md # cria testes └── refactor-planner.md # monta plano sem executar # Subagents do usuário: valem em qualquer projeto ~/.claude/ └── agents/ ├── brainstormer.md # gera ideias └── summarizer.md # resume textos longos
Tripulação do projeto
Vai para o Git. Todo o time embarca na mesma nave.
Tripulação pessoal
Mora no seu home. Sua nave particular, em qualquer porto.
Anatomia
A missão em contexto isolado
Morpheus convoca. O subagente sai em missão na sua própria bolha de contexto, investiga, processa, e retorna apenas a conclusão. O capitão nunca vê o rascunho.
Markdown é o subagente
Frontmatter mínimo, persona no corpo. O Claude lê name e description, decide quando convocar, dispara em contexto próprio.
O name é o identificador da função
A description diz quando convocar
O corpo é o system prompt da bolha
--- name: code-reviewer description: Revisa diffs em busca de bugs, regressoes e problemas de design. Use quando o usuario pedir para revisar codigo ou conferir uma mudanca. --- Voce e um revisor de codigo senior. Sua missao em cada chamada: 1. Ler o diff fornecido com atencao 2. Apontar bugs, regressoes e codigo morto 3. Sugerir melhorias de design pontuais 4. Sempre devolver bullets curtos e diretos Nao reescreva o codigo. Apenas aponte.
Convocação: o agente principal usa a ferramenta Agent com subagent_type: "code-reviewer".
O frontmatter completo
Quatro chaves controlam o ciclo de vida: identidade, gatilho, ferramentas e modelo.
--- name: security-auditor description: Faz varredura OWASP no codigo modificado. Use quando o usuario pedir auditoria de seguranca, revisao de autenticacao, ou checar SQL injection. tools: Read, Grep, Glob, Bash model: opus color: red --- Voce e um auditor de seguranca de aplicacoes. Para cada missao: 1. Mapeie endpoints, formularios e queries 2. Procure injecao, XSS, CSRF, broken auth 3. Cheque manuseio de segredos e logs 4. Devolva uma lista priorizada por severidade Nao corrija. Aponte e explique o risco.
name
Identidade do subagente
description
Gatilho de convocação
tools
Allowlist de ferramentas
model
opus, sonnet, haiku
Bônus avançado: adicione isolation: "worktree" no frontmatter para que cada convocação rode num worktree Git temporário. A bolha vira física, com cópia de trabalho isolada.
A tripulação built-in
O Claude Code embarca com cinco subagentes prontos. Você não precisa criar nada para começar a delegar.
general-purpose
subagente universal
O coringa. Investiga, executa código, faz tarefas multi-passo. Quando nenhum outro especialista se encaixa, ele é o convocado padrão.
Explore
reconhecimento read-only
O batedor. Vasculha o repositório, encontra arquivos, mapeia padrões. Não escreve nada, só observa e relata. Ideal para perguntas amplas que exigem exploração.
Plan
arquiteto que monta plano
O estrategista. Recebe um objetivo, devolve um plano em etapas com critérios de sucesso. Não executa, deixa o agente principal decidir e seguir.
statusline-setup
configura o terminal
O especialista doméstico. Cuida da statusline do Claude Code. Convocação rara, mas a pessoa certa para uma missão específica.
claude-code-guide
manual vivo da ferramenta
O guia interno. Sabe como o Claude Code funciona, quais comandos existem, como configurar permissões. Convocado quando o usuário pergunta sobre a própria ferramenta.
Seu primeiro subagente: code-reviewer
Um arquivo. Três campos. Um especialista pronto para revisar todo diff que entrar na nave.
--- name: code-reviewer description: Revisa diffs em busca de bugs e regressoes. Use quando o usuario pedir review de codigo. tools: Read, Bash, Grep --- Voce e um revisor senior. Para cada diff: 1. Aponte bugs e regressoes 2. Marque codigo morto 3. Sugira melhorias pontuais 4. Devolva bullets curtos
A description é o gatilho. Quanto mais clara, mais o principal acerta o momento de convocar.
- Falta teste para 401
- Variável n usada
O subagente trabalhou na bolha, leu, analisou, devolveu três bullets. Seu contexto principal ficou limpo.
Crie a pasta
.claude/agents/ dentro do projeto.
Salve o arquivo
code-reviewer.md com o frontmatter e o corpo do prompt.
Peça uma revisão
"Revise o diff" e o Claude convoca o subagente. Sem comando, sem barra.
Três missões, uma mensagem
Subagents rodam em paralelo. O capitão dispara três convocações no mesmo turno, cada bolha investiga seu canto, e os três relatórios chegam juntos.
Explore
bolha 1
Encontra onde está a lógica de pagamento no repositório inteiro.
security-auditor
bolha 2
Audita endpoints de checkout em busca de injeção e validação fraca.
test-generator
bolha 3
Gera casos de teste para o fluxo de cartão recusado e expirado.
# Uma única mensagem do principal, três Agent calls em paralelo: Agent(subagent_type="Explore", prompt="onde fica o checkout?") Agent(subagent_type="security-auditor", prompt="audite o checkout") Agent(subagent_type="test-generator", prompt="testes para cartao recusado") # Três bolhas trabalham ao mesmo tempo. Três relatórios voltam juntos.
Sacada: o que levaria três turnos sequenciais vira um turno só. A tripulação trabalha em paralelo enquanto o capitão decide o próximo movimento.
Cinco subagents que valem o dia
Especialistas que viram extensão da sua nave. Você os escreve uma vez, convoca para sempre.
Subagent 1 · code-reviewer · o Apoc da nave
Revisão de diff
Toda mudança de código merece um olhar fora do seu contexto. O code-reviewer abre uma bolha nova, lê o diff sem ruído, e devolve só os pontos que importam. Apoc, o olho crítico que enxerga o que escapa do capitão.
---
name: code-reviewer
description: Revisa diffs em busca de bugs,
regressoes e codigo morto. Use sempre que
o usuario pedir review ou conferencia
de codigo.
tools: Read, Bash, Grep
model: sonnet
---
# Revisor senior
Para cada chamada, voce recebe um diff.
Sua entrega obrigatoria:
1. **Bugs**: pontos que vao quebrar
2. **Regressoes**: comportamento perdido
3. **Codigo morto**: nao executavel
4. **Design**: melhorias pontuais
Bullets curtos. Sem reescrever.
Sem opinar fora desses 4 eixos.
Ganho prático: seu contexto principal não fica poluído com o diff inteiro. Só os achados entram na conversa.
Subagent 2 · security-auditor · a Trinity em combate
Varredura OWASP
Auditoria de segurança exige uma cabeça com lente própria. O security-auditor mapeia injeção, XSS, autenticação fraca e segredos vazados. Trinity entra na missão letal, sem misturar com o resto da conversa.
---
name: security-auditor
description: Audita codigo em busca de
vulnerabilidades OWASP. Use ao revisar
autenticacao, manuseio de input,
ou antes de subir para producao.
tools: Read, Grep, Glob, Bash
model: opus
---
# Auditor de seguranca
Para cada missao:
1. Mapeie endpoints e entradas
2. Procure SQLi, XSS, CSRF, SSRF
3. Cheque auth, sessao e tokens
4. Veja segredos hardcoded
5. Reveja logs (PII vazando)
Devolva lista priorizada por severidade:
**critica**, **alta**, **media**, **baixa**.
Nao corrija. Aponte e explique o risco.
Ganho prático: auditoria deixa de ser "lembrar de auditar" e vira convocação. O critério vive no subagente, não na sua cabeça.
Subagent 3 · doc-writer · o Switch que registra
Gera README de módulo
Documentação morre porque ninguém quer escrever. O doc-writer lê o módulo, identifica entradas, saídas, exemplos, e devolve um README pronto para revisão humana. Switch, o reconhecimento que vira mapa para os próximos que entrarem.
---
name: doc-writer
description: Gera README de modulo a partir
do codigo fonte. Use quando o usuario pedir
para documentar uma pasta, modulo ou pacote
sem documentacao.
tools: Read, Glob, Write
model: sonnet
---
# Documentador tecnico
Para cada pasta indicada:
1. Liste arquivos publicos do modulo
2. Extraia funcoes/classes exportadas
3. Identifique entradas e saidas
4. Procure exemplos no codigo de testes
5. Monte um README.md com:
- O que o modulo faz (uma frase)
- Instalacao/import
- Exemplos de uso
- API publica
- Limitacoes conhecidas
Ganho prático: a documentação não vira culpa do dev. Vira convocação automática no fim de cada feature.
Subagent 4 · test-generator · o Mouse que simula
Cria testes a partir do código
Você terminou uma função e o teste ficou pra depois. O test-generator lê o código, identifica caminhos felizes e bordas, e devolve a suite pronta para você refinar. Mouse, o programador de simulações que coloca o código pra dançar.
--- name: test-generator description: Gera testes unitarios a partir de uma funcao ou modulo. Use quando o usuario pedir testes para codigo existente que ainda nao tem cobertura. tools: Read, Write, Grep model: sonnet --- # Gerador de testes Para cada alvo: 1. Identifique o framework do projeto (jest, vitest, pytest, etc) 2. Cubra: - Caminho feliz - Bordas (vazio, nulo, limite) - Erros esperados (excecoes) 3. Use nomes descritivos (deve_retornar_X_quando_Y) 4. Mocke dependencias externas 5. Nao implemente o codigo, so o teste Devolva um arquivo .test/.spec pronto.
Ganho prático: de "vou escrever teste depois" para "o subagente já escreveu, falta revisar". O depois deixa de ser desculpa.
Subagent 5 · refactor-planner · o Tank que opera os controles
Plano de refactor sem executar
Antes de mexer no código grande, você quer o mapa. O refactor-planner analisa o estado atual, propõe etapas pequenas, marca riscos. Não toca em nada. Tank na cadeira do operador, monitorando as rotas antes de qualquer salto. Morpheus decide se segue.
---
name: refactor-planner
description: Monta plano de refactor em etapas
pequenas, sem executar nada. Use quando o
usuario pedir um plano antes de mexer em
codigo grande ou critico.
tools: Read, Grep, Glob
model: opus
---
# Arquiteto de refactor
Para cada alvo:
1. Mapeie estado atual
(quem chama, dependencias)
2. Identifique o "smell" principal
3. Proponha 3-5 etapas pequenas:
- Cada etapa entrega valor
- Cada etapa e revertivel
- Cada etapa tem teste antes
4. Marque riscos altos
5. Sugira ordem de execucao
**Nunca escreva codigo.**
Devolva apenas o plano.
Ganho prático: o pensar e o fazer ficam separados. Planejar com um especialista, executar com outro. Cada bolha com seu propósito.
Os cinco especialistas lado a lado
Resumo da tripulação que você acabou de conhecer.
| Subagent | Missão | Ganho | |
|---|---|---|---|
| code-reviewer | Revisa diff em busca de bugs, regressões e código morto | Contexto principal limpo | |
| security-auditor | Varredura OWASP com lista priorizada por severidade | Auditoria sem desculpa | |
| doc-writer | Gera README de módulo com API pública e exemplos | Doc deixa de morrer | |
| test-generator | Cria suite de testes cobrindo feliz, borda e erro | Cobertura por convocação | |
| refactor-planner | Monta plano em etapas pequenas, marca riscos, não executa | Pensar antes de mexer |
Cinco arquivos Markdown em .claude/agents/. Cinco bolhas de contexto especializadas. Uma tripulação que cresce com você.
Quer dominar cada peça?
O livro Engenharia de Software para Agentes Inteligentes destrincha commands, skills, hooks, subagents, MCP e tudo que faz a tripulação trabalhar a seu favor.
·
@canalsandeco
Tank disca, Trinity pilota, Smith vigia, a tripulação executa. Você comanda, e a Nabucodonosor inteira faz o resto.
A barra que vira atalho, a skill que vira capacidade, o hook que vira limite, o subagente que vira especialista. Quatro peças, um capitão no controle.