Aprenda a delegar tarefas complexas a instâncias paralelas do Claude Code, multiplicando sua capacidade sem aumentar o tempo de espera.
Um subagent é uma instância independente do Claude Code lançada pelo agente principal (orquestrador) para executar uma tarefa específica. Ele recebe um prompt bem delimitado, executa com suas próprias ferramentas e retorna um resultado resumido.
O orquestrador usa a ferramenta interna Task para criar subagents. Cada Task é isolada: tem seu próprio histórico de conversa, contexto de arquivos e permissões configuradas.
O subagent não compartilha memória com o orquestrador. Ele só sabe o que está no prompt que recebeu. Isso é uma feature — isolamento garante que um subagent não contamine o contexto de outro.
Define o prompt com escopo claro, formato de saída esperado e permissões necessárias
Nova sessão isolada é criada com o prompt como contexto inicial
Usa Bash, Read, WebSearch e outras ferramentas conforme necessário
Texto comprimido com o output — não o log completo, apenas a resposta
O critério mais rápido: consegue descrever a tarefa em 1-2 frases com input e output claros? Se sim, é candidata a subagent. Se precisa de parágrafos de contexto, execute no orquestrador mesmo.
Fan-out é quando um orquestrador dispara N subagents simultaneamente, cada um resolvendo uma fatia do problema. O orquestrador fica bloqueado aguardando todos terminarem, depois agrega os resultados.
Uma pesquisa que visitaria 8 fontes em série (8 × 30s = 4 minutos) vira 8 subagents paralelos (~30 segundos). Velocidade 8× com o mesmo custo total.
Você é o orquestrador. Use a ferramenta Task para criar 4 subagents em PARALELO: Task 1: Pesquise a doc oficial do Claude Code sobre hooks. Retorne: lista de eventos disponíveis com descrição. Task 2: Leia os arquivos .claude/settings.json do projeto. Retorne: estrutura atual de configuração. Task 3: Pesquise exemplos de hooks em repositórios públicos. Retorne: 3 exemplos práticos com código. Task 4: Analise o código em src/ para identificar oportunidades de automação com hooks. Retorne: lista priorizada de melhorias. // Aguarde TODOS terminarem, depois integre os resultados.
O ganho de velocidade aumenta com N subagents, mas o custo também. Para tarefas de 1-2 minutos, fan-out com 4-8 agentes é o ponto ótimo. Além de 10 agentes, o overhead de coordenação reduz o retorno.
Modo de leitura — acesso somente a ferramentas de observação (Read, Bash somente leitura, WebSearch). Não pode criar ou modificar arquivos.
Acesso completo às ferramentas — pode ler, escrever, executar comandos e interagir com APIs externas.
Sempre use o tipo mais restrito que a tarefa permite. Um subagent de pesquisa com permissão de escrita é um risco desnecessário — se o modelo "alucinar" uma instrução, pode modificar arquivos por engano.
O resultado de um subagent chega ao orquestrador como texto puro — um resumo consolidado do que foi encontrado/feito. O orquestrador não recebe o log de ferramentas, apenas a resposta final.
Para garantir que o resultado seja consumível, especifique no prompt o formato de saída: Retorne: lista de bullets, Retorne: JSON com campos X e Y, etc.
Prompt do orquestrador: ~500 tokens ($0.003) Execução do subagent: ~2000 tokens ($0.012) Output para orquestrador: ~300 tokens ($0.002) ────────────────────── Total por subagent: ~$0.017 // Com prompt caching (se CLAUDE.md ou contexto fixo): Custo cache hit: ~$0.002 (10× mais barato) // ROI: 1h de trabalho humano = $50-100 // 100 subagents = $1.70 → 30× mais barato que humano
Compare: tempo economizado × valor do seu tempo vs custo da API. Se você economiza 1h ($50) e a automação custa $0.50, o ROI é 100×. Vale para qualquer tarefa que você faz mais de uma vez por semana.
4.2 — 🪝 Hooks: automatizar o harness com PreToolUse, PostToolUse, SessionStart e Stop