Fan out de subagentes no Claude Code, e depois conferir o que volta

As pessoas digitam “claude fan out subagents” no Google, e várias acrescentam “command” no final, como se existisse um botão para ligar. Existe um padrão, e também existe um comando. Verificamos os dois no Claude Code 2.1.301 e na documentação da Anthropic em 16 de outubro de 2026.

Depois vem a parte sobre a qual a documentação fala pouco, e o motivo de escrevermos este artigo: o que fazer com os resultados. Rodamos um fan out toda noite. Seis subagentes traduzem cada novo artigo deste blog para dezessete idiomas, e a sessão principal faz o merge do trabalho deles. Todos eles relatam que seguiram as regras. A verificação que escrevemos antes de iniciá-los ainda encontra coisas.

A resposta curta

Fazer um fan out significa que uma sessão divide um trabalho em fatias que não dependem umas das outras, entrega cada fatia a um subagente, deixa todos rodarem ao mesmo tempo e junta o que volta. No Claude Code, você pode fazer isso de três jeitos.

O restante desta página passa por cada um, e depois pelas verificações que fazemos no nosso próprio fan out.

O que um subagente vê e o que ele não vê

Três fatos da documentação decidem como você divide o trabalho.

Cada subagente começa do zero. Ele roda na sua própria janela de contexto, com o seu próprio system prompt, ferramentas e permissões. Ele não vê a sua conversa, nem as skills que você já usou, nem os arquivos que o Claude já leu. Tudo o que ele precisa saber tem que estar no brief.

Os resultados voltam para a conversa principal. A parte detalhada do trabalho de um subagente fica no contexto dele, e só o resultado volta. Mas muitos subagentes devolvendo relatórios longos ainda podem encher o seu contexto principal, e cada um gasta os seus próprios tokens enquanto roda.

Existem limites. Por padrão, 20 subagentes podem rodar ao mesmo tempo em uma sessão. O 21º falha com Concurrent subagent limit reached, e o erro diz ao Claude para não tentar de novo. Você pode aumentar ou diminuir esse limite com CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Um subagente pode iniciar os seus próprios subagentes, até três níveis abaixo da conversa principal, e não há limite para o total em uma sessão.

Jeito 1: pedir com palavras simples

O fan out mais simples é uma frase. O exemplo da documentação da Anthropic:

Research the authentication, database, and API modules in parallel using separate subagents

Cada subagente explora a sua área, e depois o Claude escreve uma síntese. A documentação acrescenta a condição que importa: isso funciona melhor quando as linhas de pesquisa não dependem umas das outras. Se a pergunta sobre o banco de dados precisa da resposta sobre o auth, você não tem três fatias, tem uma sequência.

Com palavras simples, quem decide é o Claude. Se você definiu um subagente personalizado em .claude/agents/, mencioná-lo com @ garante que ele rode para essa tarefa. Nossa página sobre os subagentes do Claude Code explica como esses arquivos funcionam.

Jeito 2: /batch, o mais próximo de um comando de fan out

/batch é uma skill que vem com o Claude Code. Você dá uma instrução a ela:

/batch migrate src/ from JavaScript to TypeScript

Ela pesquisa o código, divide o trabalho em 5 a 30 unidades independentes e mostra um plano para você. Depois que você aprova, ela inicia um subagente em segundo plano por unidade, cada um em um worktree do git isolado. Cada subagente implementa a sua unidade, roda os testes e publica a sua mudança. É preciso um repositório git, ou um hook WorktreeCreate que crie os worktrees para outro sistema de controle de versão.

O plano é a hora de ir devagar. É ali que a divisão é decidida, e a divisão é o jogo inteiro: duas unidades que mexem no mesmo arquivo, ou uma unidade que precisa da saída de outra, não vão se juntar de forma limpa, por melhor que seja cada subagente. Leia a lista de unidades como você leria um plano de migração escrito por um colega.

Jeito 3: um loop sobre claude -p

Quando o trabalho é uma lista de arquivos e você quer controle sobre cada chamada, as boas práticas da Anthropic descrevem um loop. Primeiro, peça ao Claude para escrever a lista (list all 2,000 Python files that need migrating and save the list to files.txt). Depois:

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

Três detalhes desse exemplo valem ser copiados.

• A resposta pode ser lida por uma máquina. “Return OK or FAIL” quer dizer que o seu script consegue contar as falhas sem ler prosa.
• As permissões são decididas antes. --allowedTools aprova exatamente o que a migração precisa, e --permission-mode dontAsk nega todo o resto em vez de esperar por alguém que não está lá.
• Você começa com dois ou três arquivos. A documentação diz isso com todas as letras: ajuste o prompt com base no que dá errado nos primeiros arquivos, e só então rode a lista inteira.

Do jeito que está escrito, o loop processa um arquivo depois do outro. Rodar várias chamadas ao mesmo tempo é trabalho comum de shell, mas cada chamada é uma sessão completa na sua máquina e na sua cota. Medimos o que acontece quando vários agentes iniciam o mesmo comando pesado no mesmo minuto neste artigo, e aqui a história é a mesma: comece com poucas chamadas em paralelo.

Para CI, a documentação recomenda adicionar --bare, que pula os hooks, as skills, os servidores MCP e o CLAUDE.md para que cada máquina faça o mesmo run. O modo bare não usa o login da sua assinatura: ele precisa de ANTHROPIC_API_KEY.

Como fazemos um fan out toda noite

Este é o fan out que realmente rodamos. Nossa equipe de SEO noturna escreve cada novo artigo à mão, em inglês e em francês. Depois, um segundo agente o traduz para mais dezessete idiomas com subagentes do Claude Code, e gera o chinês tradicional a partir do chinês simplificado com um script, em vez de traduzi-lo. Onze artigos já passaram por isso desde 13 de setembro de 2026, e cada um chega como vinte arquivos.

As fatias

Seis subagentes, três idiomas para cada um (dois para o último): espanhol, português e italiano; alemão, holandês e polonês; russo, ucraniano e turco; japonês, coreano e chinês; tailandês, vietnamita e indonésio; árabe e hindi. Nenhum idioma depende de outro, e é isso que faz disso um fan out limpo.

Cada brief leva as mesmas cinco coisas, porque o subagente não vê mais nada:

• a fonte em inglês, e a versão em francês como referência de tom e de termos do produto;
• para cada idioma, frases já publicadas no site naquele idioma, para que o subagente reaproveite as palavras que o site já usa em vez de inventar outras;
• as regras rígidas: nomes de marcas e de produtos ficam como estão, o código fica idêntico byte a byte, nenhum travessão;
• o script de verificação, com a instrução de rodá-lo até ele dizer OK;
• o pedido de relatar qualquer coisa duvidosa que tenha visto, dentro ou fora da sua fatia.

A verificação é escrita antes de iniciar

A verificação é um script, não a opinião de um subagente. Para cada idioma, ela compara o arquivo com a fonte em inglês:

• mesmo slug e mesma data, título igual ao H1;
• mesmo número de seções, subseções, imagens, links e linhas de tabela, e tantas respostas de FAQ no corpo quanto perguntas nos metadados;
• links idênticos byte a byte, trechos de código idênticos byte a byte;
• nomes de marcas contados, nunca menos do que no inglês;
• um tamanho dentro de limites calibrados para cada idioma, porque o chinês diz a mesma coisa em cerca de 36% dos caracteres de que o inglês precisa, e o japonês em mais ou menos a metade;
• acentos presentes onde o idioma tem acentos (polonês, turco, vietnamita).

Todo subagente termina com alguma versão de “pronto, todas as verificações passaram”. O único veredito com base no qual agimos é o mesmo script, rodado de novo pela sessão principal, em todos os arquivos de uma vez.

O que a verificação central pegou e os próprios relatórios não

Código traduzido dentro de uma tabela. Em 13 de setembro, cerca de metade dos subagentes traduziu as palavras que vinham depois de um comando dentro das mesmas crases de uma tabela. Cada um tinha seguido o seu brief do jeito que o entendeu. A correção foi para o brief, não para os subagentes: um trecho de código contém só o comando, e as palavras que vêm depois ficam fora das crases.

A nossa própria verificação estava errada. Em 6 de setembro, uma verificação de tamanho calibrada na frase antiga que estávamos substituindo apontou 11 subagentes de 17. Os 11 estavam certos: o texto novo devia mesmo ser mais longo. Calibrada no francês já corrigido, ela não apontou nenhum. Uma verificação central também pode falhar, e o jeito de perceber isso é rodá-la primeiro em uma entrega que você já sabe que está boa.

A consistência entre as fatias. Em 15 de outubro, em uma nova página de funcionalidade traduzida do mesmo jeito, a verificação de merge confirmou que só as frases esperadas tinham mudado em 90 arquivos. Mas os subagentes de japonês, coreano e chinês tinham escolhido, cada um, para “You may also like” um título diferente daquele que o seu idioma já usava em uma página vizinha. Cada escolha era uma tradução correta. Nenhuma era consistente com o site. Nenhum subagente conseguia ver isso de dentro da sua fatia: só uma passada sobre o resultado do merge consegue.

Uma palavra errada passa por todas as verificações de estrutura. Um idioma do site chegou a chamar os agentes de IA de concessionárias de carros, e isso ficou no ar por meses. Mesmo tamanho, mesma pontuação, marca presente: todas as contagens estavam verdes. A única coisa que pega isso é uma lista nomeada de palavras erradas conhecidas, que bloqueia cada deploy e ganha uma linha a cada vez que encontramos uma nova.

Os relatos de fora da fatia. Em 15 de outubro, o subagente que trabalhava no turco relatou que o site escrevia “ajans”, agência, para “agent” em 97 frases existentes. Ele não mexeu nelas, porque o seu brief dizia para não mexer. Abrimos um ticket, e a correção saiu no dia seguinte. Perguntar aos subagentes o que eles viram, e não só o que eles fizeram, custa pouco e compensa.

O merge acontece em um só lugar

Os subagentes não escrevem diretamente no repositório. Cada um devolve os seus arquivos, e um script faz o merge deles e depois compara o resultado com a versão anterior, frase por frase: só as frases que pedimos podem ter mudado. Depois disso, as verificações do repositório e o build do site rodam uma única vez, sobre o resultado do merge. Rodar o build uma vez por subagente seria mais lento e testaria estados com merge pela metade que nunca vão ao ar.

Quando não fazer um fan out

• As fatias dependem umas das outras. Se a fatia B precisa da saída da fatia A, rode as duas em ordem.
• O trabalho é pequeno. Cada subagente começa do zero e relê o que precisa. Em uma tarefa de dez minutos, os recomeços custam mais do que economizam.
• Você não consegue escrever a verificação. Se não há como distinguir uma fatia boa de uma ruim sem ler tudo você mesmo, é no merge que você vai gastar o seu tempo.
• A cota está apertada. Cada subagente gasta os seus próprios tokens. O fan out compra tempo e um contexto principal limpo, não uma conta menor.

Onde o AgentsRoom entra

Os subagentes vivem dentro de uma única sessão do Claude Code. Você vê os resultados deles, não o trabalho, e não consegue redirecionar um deles no meio do caminho. Quando você quer que cada fatia seja um agente que você pode acompanhar, responder e revisar separadamente, rode sessões separadas: cada ticket no seu próprio worktree do git, e Agent Teams quando as fatias passam trabalho umas para as outras. Uma etapa de equipe pode levar um comando de verificação, e é o código de saída dele, não o que o agente afirma, que decide se o run avança. É a mesma regra de antes, aplicada pelo runner. Funciona com o Claude Code, o Codex e as outras CLIs de agentes que o AgentsRoom suporta.

Se você ainda está decidindo entre subagentes e Agent Teams, esta comparação explica para que serve cada um.