Despachando Subagentes Paralelos para Tarefas de Pesquisa Isoladas
Quando uma tarefa de pesquisa se divide claramente em partes independentes, despachar um subagente para cada peça e executá-los ao mesmo tempo é mais rápido e limpo do que pesquisar cada peça uma após a outra na sessão principal.
Este é o padrão de fan-out: vários subagentes lançados juntos, cada um com sua própria tarefa com escopo definido, cada um reportando um resumo curto assim que termina.
Resumo
Um único subagente já mantém o trabalho exploratório fora do contexto da sessão principal.
O fan-out estende isso lançando vários subagentes ao mesmo tempo em vez de um por vez, para que a pesquisa independente ocorra concorrentemente em vez de sequencialmente.
Como cada subagente obtém seu próprio contexto isolado, executar três ou cinco deles em paralelo não corre o risco de as descobertas de um subagente vazarem para ou contaminarem as de outro.
O papel da sessão principal muda de fazer a pesquisa em si para escrever descrições de tarefas claras e independentes e, em seguida, sintetizar os resumos que retornam.
Isso só funciona bem quando as peças são realmente independentes; uma tarefa onde o segundo subagente precisa da resposta do primeiro antes de poder começar não é um candidato a fan-out.
Receita
Despache três subagentes em paralelo, um para o código de autenticação, um para
o código de faturamento e um para o código de notificações. Cada subagente deve
reportar: o arquivo de ponto de entrada, o fluxo de dados geral e qualquer padrão
de tratamento de erros que encontrar. Mantenha cada relatório com menos de 150
palavras.Quando usar isso:
- Auditoria de um padrão (tratamento de erros, logging, uma convenção de nomenclatura) em vários subsistemas não relacionados ao mesmo tempo.
- Responder "como funciona X" para vários recursos independentes antes de iniciar uma alteração maior.
- Comparar como o mesmo problema é resolvido em diferentes partes de uma base de código.
- Coleta de contexto para um grande refator onde as áreas afetadas não dependem umas das outras.
Exemplo de Trabalho
Estou prestes a adicionar limitação de taxa a esta API. Antes de fazer isso,
despache três subagentes em paralelo:
1. Pesquise como o middleware de autenticação existente é estruturado, para que
a limitação de taxa possa se conectar ao mesmo pipeline de requisição.
2. Pesquise como os erros são atualmente formatados e retornados aos clientes da
API, para que uma resposta 429 corresponda às convenções existentes.
3. Pesquise se algum sistema de configuração existente (variáveis de ambiente,
um arquivo de configurações) deve conter os limites de taxa, em vez de
codificá-los diretamente.
Cada subagente deve reportar caminhos de arquivo e um resumo de duas ou três
frases, não o conteúdo completo do arquivo. Assim que todos os três terminarem,
proponha onde a lógica de limitação de taxa deve residir com base no que eles
encontraram.O que isso demonstra:
- Três perguntas de pesquisa genuinamente independentes, nenhuma das quais depende da resposta de outra, é o que torna o fan-out paralelo seguro aqui.
- Cada subagente recebe um entregável com escopo e concreto (descobertas específicas, não "dê uma olhada"), o que produz um resumo utilizável em vez de um vago.
- A instrução para reportar "caminhos de arquivo e um resumo, não o conteúdo completo do arquivo" mantém os relatórios curtos o suficiente para que a sessão principal realmente sintetize.
- A etapa final de síntese ocorre após todos os três subagentes reportarem, na sessão principal, que é onde as peças são realmente combinadas em uma decisão.
Mergulho Profundo
Como Funciona
- A sessão principal escreve uma descrição de tarefa por subagente, cada uma com escopo para uma única peça independente da questão geral.
- Os subagentes rodam concorrentemente, cada um em seu próprio contexto isolado, então suas explorações intermediárias nunca aparecem na sessão principal ou nos contextos uns dos outros.
- Cada subagente termina e reporta um resumo de volta para a sessão principal; a sessão principal recebe N resumos, não a transcrição completa do trabalho de qualquer subagente.
- A sessão principal, então, sintetiza os resumos, tirando conclusões ou tomando decisões que nenhum subagente individual tinha contexto suficiente para fazer por conta própria.
Reconhecendo um Candidato Genuíno para Fan-Out
| Sinal | Fan-out se encaixa | Fan-out não se encaixa |
|---|---|---|
| Dependência entre tarefas | Nenhuma; cada tarefa pode começar com zero informação das outras | Uma tarefa precisa das descobertas de outra antes de poder começar |
| Escopo de cada tarefa | Limitado e específico (um subsistema, uma pergunta) | Vago ("dar uma olhada em toda a base de código") |
| O que "feito" parece | Um resumo curto e concreto responde à pergunta | A resposta só faz sentido integrada em uma narrativa longa |
Escrevendo Descrições de Tarefas Que Funcionam Bem com Fan-Out
Ruim: "Investigue como o aplicativo lida com erros."
Melhor: "Apenas no módulo de pagamentos, encontre onde os erros são capturados e formatados para o cliente. Reporte o caminho do arquivo e o formato usado, em menos de 100 palavras."- Uma tarefa vaga produz um resumo vago e difícil de sintetizar; uma tarefa específica e com escopo produz um resumo específico e utilizável.
- Nomear o entregável exato ("caminho do arquivo e formato usado") diz ao subagente no que realmente gastar seu esforço para verificar, em vez de explorar amplamente e adivinhar o que importa.
Armadilhas
- Dividir uma tarefa que realmente tem dependências - despachar o subagente B para construir sobre as descobertas do subagente A, em paralelo, significa que B começa sem as informações que realmente precisava. Correção: execute a pesquisa dependente sequencialmente e reserve o fan-out paralelo para peças genuinamente independentes.
- Descrições de tarefas vagas e sobrepostas - dois subagentes recebendo instruções quase idênticas ("olhe o backend" e "olhe a API") frequentemente duplicam o trabalho ou produzem resumos redundantes e difíceis de comparar. Correção: escopo cada subagente para uma peça distinta e não sobreposta da pergunta.
- Pedir o conteúdo completo dos arquivos de volta em vez de um resumo - um subagente retornando arquivos inteiros frustra o propósito do fan-out, já que o contexto da sessão principal se enche de qualquer maneira, apenas atrasado. Correção: peça explicitamente a cada subagente um resumo curto e descobertas específicas, não conteúdo bruto de arquivos.
- Despachar muitos subagentes para uma tarefa pequena - fazer fan-out de cinco subagentes para responder algo que um subagente (ou a sessão principal diretamente) poderia responder em um minuto adiciona latência e sobrecarga de coordenação sem benefício. Correção: reserve o fan-out para tarefas que genuinamente se dividem em várias peças substanciais e independentes.
- Esquecer de especificar um formato de relatório - sem orientação sobre qual forma o resumo deve ter, diferentes subagentes podem reportar em formatos inconsistentes que são mais difíceis de comparar e sintetizar. Correção: peça uma estrutura consistente (por exemplo, "caminho do arquivo, seguido por um resumo de duas frases") em todos os subagentes do lote.
- Não contabilizar o tempo de síntese - a sessão principal ainda precisa ler e combinar N resumos depois que todos retornam, o que exige esforço real proporcional a quantos subagentes foram despachados. Correção: mantenha a largura do fan-out (o número de subagentes) correspondente a quanto a sessão principal pode sintetizar significativamente depois.
Alternativas
| Alternativa | Use Quando | Não Use Quando |
|---|---|---|
| Um único subagente | A pergunta de pesquisa é uma tarefa coerente, mesmo que toque em vários arquivos. | A tarefa se divide genuinamente em várias subperguntas não relacionadas que diluiriam o foco de um único subagente. |
| Subagentes sequenciais, um após o outro | Pesquisas posteriores dependem do que um subagente anterior encontrou. | As peças são independentes e executá-las uma de cada vez apenas adicionaria latência desnecessária. |
| Pesquisar diretamente na sessão principal | A consulta é rápida e pequena o suficiente para que despachar um subagente custaria mais do que economizaria. | A pesquisa é ampla o suficiente para que suas etapas intermediárias inchem significativamente o contexto da sessão principal. |
FAQs
Quantos subagentes podem ser razoavelmente despachados em paralelo para um único fan-out?
Não há um limite fixo declarado pelo produto, mas na prática o número deve corresponder a quantas peças genuinamente independentes a tarefa realmente tem, e quanto esforço de síntese a sessão principal pode razoavelmente fazer depois, geralmente um punhado em vez de dezenas.
Subagentes paralelos compartilham algum contexto entre si enquanto rodam?
Não. Cada subagente obtém seu próprio contexto isolado, então nenhum deles pode ver o que os outros estão fazendo ou encontraram enquanto todos ainda estão em andamento.
O que acontece se um subagente em um lote de fan-out levar muito mais tempo do que os outros?
A sessão principal geralmente espera que todos os subagentes despachados concluam antes de sintetizar seus relatórios, então o subagente mais lento do lote determina quando a síntese pode começar.
Devo pedir a cada subagente para reportar no mesmo formato?
Sim. Pedir uma estrutura consistente, como um caminho de arquivo seguido por um resumo curto, torna muito mais fácil comparar e combinar os relatórios depois que todos retornam.
O padrão de fan-out é adequado para uma tarefa com três etapas que dependem umas das outras?
Não. O fan-out é para peças independentes que podem começar sem nenhuma informação umas das outras; uma tarefa dependente e sequencial deve ser executada como subagentes (ou etapas) sequenciais em vez disso.
Qual é o maior sinal de que uma tarefa não deve ser distribuída (fanned out)?
Se descrever a tarefa para um subagente naturalmente requer referenciar "o que o subagente B encontrou", a tarefa tem uma dependência e não é um candidato genuíno a fan-out.
Despachar subagentes em paralelo economiza contexto em comparação com executá-los um de cada vez?
As economias de contexto vêm do isolamento em si (a exploração de cada subagente nunca chega à sessão principal), o que se mantém se os subagentes rodam em paralelo ou sequencialmente; o despacho paralelo economiza principalmente tempo de relógio, não contexto adicional.
Quem faz a síntese real depois que vários subagentes reportam?
A sessão principal que os despachou. Ela recebe o resumo de cada subagente e é responsável por tirar conclusões ou tomar decisões que combinam informações de todos eles.
Um lote de fan-out pode ser acionado a partir de um comando de barra personalizado?
Sim. O corpo do prompt de um comando pode instruir Claude a despachar vários subagentes em paralelo, transformando uma auditoria recorrente de fan-out em uma única invocação repetível de /nome-do-comando.
Qual é um exemplo realista de uma tarefa que não deve ser distribuída (fanned out)?
Depurar um único teste específico que falha, onde a investigação é um fio contínuo de raciocínio em vez de várias subperguntas independentes e paralelas.
Cada subagente em um lote de fan-out precisa de seu próprio escopo de ferramenta distinto?
Não necessariamente; subagentes de pesquisa em um lote comumente compartilham a mesma lista de ferramentas com escopo, muitas vezes somente leitura, pois seus trabalhos (ler e pesquisar, não editar) são geralmente semelhantes, embora seus alvos difiram.
Relacionados
- Noções Básicas de Comandos Personalizados e Subagentes - um primeiro exemplo de subagente único antes de escalar para fan-out.
- Como os Subagentes Obtêm Seu Próprio Contexto e Ferramentas - por que executar vários subagentes ao mesmo tempo é seguro.
- Subagentes vs. o Agent SDK: Como Claude Code é Construído - os primitivos subjacentes que tornam o isolamento e o fan-out possíveis.
- Melhores Práticas para Comandos Personalizados, Hooks e Subagentes - convenções para delegar trabalho a subagentes de forma eficaz.
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos do produto mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.