Fan-out de subagentes para migração de código é a prática de dividir uma mudança grande entre agentes especializados que exploram, implementam, testam e revisam partes diferentes do repositório. A técnica ajuda em monorepos, migrações de TypeScript, troca de API interna e ajustes de infraestrutura, mas só funciona com fronteiras claras.

Em 2026, a GitLab afirmou que 85% das pessoas pesquisadas veem a revisão e a validação como o novo gargalo depois da adoção de IA no desenvolvimento (GitLab, "AI Accountability Report", 2026). Se agentes escrevem mais código, a orquestração precisa reduzir ruído, não multiplicar diffs sem dono.

TL;DR prático

  • Use subagentes para leitura paralela, não para disputa no mesmo arquivo.
  • Particione por pacote, módulo, contrato ou risco operacional.
  • Worktrees evitam conflito quando há implementação paralela.
  • O PR final precisa mostrar evidência, comandos e decisões descartadas.

Diagrama abstrato mostra subagentes coordenados ao redor de uma migração de código sem texto visível.

Por que fan-out virou uma habilidade de engenharia?

Em 2025, o relatório DORA do Google Cloud mediu 90% de uso de IA no trabalho e mais de 80% de percepção de produtividade maior (Google Cloud, "Announcing the 2025 DORA Report", 2025). Fan-out virou habilidade de engenharia porque produtividade individual não resolve migração grande quando a validação continua centralizada em uma pessoa.

O erro comum é chamar vários agentes como se fossem threads de CPU. Agentes não compartilham memória com consistência, não entendem automaticamente a intenção uns dos outros e podem tocar o mesmo arquivo por caminhos diferentes. Sem particionamento, paralelismo vira retrabalho.

Use fan-out quando a tarefa tem independência real. Uma migração de fetch para cliente interno pode ser dividida por pacote. Uma troca de logger pode ser dividida por camada. Uma mudança de CI pode separar inventário, patch e validação. Se a tarefa exige ordem estrita, use um agente principal com checkpoints.

Esse tema continua a conversa sobre context engineering para agentes de código. Lá, a pergunta era como economizar contexto. Aqui, a pergunta é como distribuir contexto entre trabalhadores sem perder a cadeia de decisão.

O ganho aparece quando cada subagente entrega síntese curta. O agente principal não precisa receber todos os arquivos lidos. Ele precisa saber escopo, achado, patch proposto, teste rodado e risco residual. Esse é o contrato que mantém o contexto útil.

Quando usar subagentes, workflows ou times de agentes?

Em 2026, a documentação do Claude Code descreveu quatro formas de paralelizar trabalho: subagentes, visão de agentes, times de agentes e workflows dinâmicos (Claude Code Docs, "Run agents in parallel", 2026). A escolha certa depende de quem coordena, se os trabalhadores conversam e se eles editam os mesmos arquivos.

Subagentes são bons quando o agente principal continua no comando. Eles pesquisam, revisam ou executam uma parte estreita e retornam resumo. Para migração de monorepo, use subagentes para inventário de módulos, análise de testes quebrados, revisão de segurança ou leitura de dependências.

Workflows dinâmicos entram quando o trabalho precisa de script repetível. A própria documentação do Claude Code cita auditoria de codebase, migração de 500 arquivos e pesquisa cruzada como casos para workflows dinâmicos (Claude Code Docs, "Run agents in parallel", 2026). Isso combina com migração mecânica que precisa de verificação cruzada.

Times de agentes são mais caros em coordenação. Em 2026, a documentação do Claude Code marcou agent teams como experimental e desativado por padrão, com uso indicado para exploração paralela, módulos independentes, hipóteses concorrentes e coordenação entre camadas (Claude Code Docs, "Orchestrate teams of Claude Code sessions", 2026). Use quando os trabalhadores precisam conversar.

Superfície Melhor uso na migração Sinal de risco
Subagente Leitura, revisão e tarefa estreita. Tenta editar muitos módulos.
Workflow dinâmico Passo repetível com verificação cruzada. Vira script sem critério de parada.
Time de agentes Camadas independentes que precisam negociar. Todos dependem do mesmo arquivo central.
Sessão principal Decisão final, merge e narrativa do PR. Recebe logs brutos demais.

Um bom critério é simples: se o resultado de um trabalhador cabe em um resumo, use subagente. Se o trabalho precisa ser reexecutado, use workflow. Se os trabalhadores precisam debater trade-offs entre frontend, backend e testes, considere time de agentes.

Como particionar uma migração sem criar conflito?

Em 2025, o Stack Overflow mostrou que 69% dos usuários de agentes perceberam aumento de produtividade, mas só 17% perceberam melhora de colaboração em equipe (Stack Overflow, "2025 Developer Survey: AI", 2025). Particionar migração é transformar produtividade isolada em colaboração verificável.

Diagrama abstrato mostra linhas de trabalho isoladas para migrações paralelas sem texto visível.

Comece pelo inventário. Antes do patch, peça a um subagente só de leitura para mapear arquivos afetados, testes prováveis, donos de módulo e dependências cruzadas. Outro subagente pode procurar risco operacional: autenticação, pagamentos, filas, dados pessoais, migrações e infraestrutura.

Depois divida por fronteiras estáveis. Pacote, serviço, rota, fila, schema, biblioteca compartilhada e pipeline de CI são fronteiras melhores que "primeira metade dos arquivos". Se dois subagentes precisam tocar a mesma abstração central, essa parte deve ficar com o agente principal.

Use worktrees quando houver edição paralela. A documentação do Claude Code recomenda isolamento com worktrees quando tarefas podem tocar arquivos, e observa que sessões em paralelo podem ficar em checkouts separados (Claude Code Docs, "Run agents in parallel", 2026). Isso evita que uma tentativa quebre o estado da outra.

Um plano mínimo pode ficar assim:

migracao:
  inventario:
    papel: "somente leitura"
    saida: "arquivos afetados, testes e riscos"
  patches:
    pacote_api:
      fronteira: "packages/api/**"
      proibido: "packages/web/**"
    pacote_web:
      fronteira: "packages/web/**"
      proibido: "packages/api/**"
  consolidacao:
    responsavel: "sessao principal"
    exige: "testes, diff limpo e resumo de decisoes"

Na prática, eu só deixo subagente editar quando a fronteira é objetiva. Se a mudança cruza contrato público, types compartilhados ou migração de banco, o subagente pode propor patch, mas a sessão principal aplica. Isso preserva autoria técnica.

Como manter contexto e custo sob controle?

Em 2026, a documentação do Claude Code avisou que rodar várias sessões ou subagentes ao mesmo tempo multiplica uso de tokens (Claude Code Docs, "Run agents in parallel", 2026). O controle vem de limitar entrada, limitar ferramenta e exigir saída curta de cada trabalhador.

Defina uma pergunta por subagente. "Ache todos os impactos no pacote de cobrança" é melhor que "entenda a codebase". A saída deve listar arquivos, motivo, teste recomendado e confiança. Se o subagente precisa de mais contexto, ele deve pedir uma ferramenta estreita, não despejar o repositório na conversa.

Permissões também controlam custo. Um subagente de inventário não precisa escrever. Um revisor de segurança não precisa rodar deploy. Um avaliador de testes talvez só precise ler arquivos e executar comandos. Essa divisão segue o mesmo princípio do MCP de codebase RAG para agentes que não leem tudo: ferramentas estreitas geram contexto melhor.

Quando a migração passa por muitas sessões, evidências e subagentes, eu uso o RemoteCode para estender Claude Code e Codex em fluxos agentic longos como recurso do próprio autor. A utilidade aqui é qualitativa: reduzir desperdício de contexto quando o trabalho precisa atravessar etapas sem recarregar todo o histórico.

O formato de retorno deve ser rígido:

area: pacote de autenticacao
status: pronto_para_patch
arquivos: src/auth/session.ts, src/auth/session.spec.ts
risco: medio
prova: teste unitario cobre expiracao e revogacao
proxima_acao: aplicar patch apenas neste pacote

Esse contrato impede que o fan-out vire uma pilha de narrativas. O agente principal pode comparar resultados, escolher ordem de aplicação e abrir um PR que explica o caminho. Contexto bom é contexto que cabe na decisão seguinte.

Onde Codex, MCP e CI entram nesse desenho?

Em 2026, a documentação do Codex afirmou que a configuração MCP fica em config.toml e pode ser escopada ao projeto com .codex/config.toml em repositórios confiáveis (OpenAI Developers, "Model Context Protocol - Codex", 2026). Isso permite que a migração carregue ferramentas do próprio repositório em vez de depender de colagem manual.

Codex pode participar como executor ou como ferramenta. Em 2026, a documentação da OpenAI mostrou que o Codex CLI pode rodar como servidor MCP com codex mcp-server, expondo ferramentas para workflows multiagente com rastros revisáveis (OpenAI Developers, "Use Codex with the Agents SDK", 2026). Essa arquitetura combina com migrações que precisam de trilha de auditoria.

O CI deve ser o juiz determinístico. Subagentes podem propor, mas lint, typecheck, testes, build e análise de contrato precisam rodar fora da conversa. Se o projeto já tem GitLab CI para Node.js, use os jobs existentes antes de criar rubrica com IA.

Para backend, conecte a migração ao desenho de serviços. Uma mudança bem particionada respeita fronteiras de arquitetura de serviços em TypeScript. Se a fronteira do sistema é confusa, o agente vai expor essa confusão em forma de conflito.

O PR final deve ter uma seção de evidência:

### Evidência da migração
- Inventario: pacotes afetados e arquivos fora de escopo.
- Patches: worktrees usados e conflitos resolvidos.
- Testes: comandos executados e falhas corrigidas.
- Revisão: achados de segurança, tipos e regressão.
- Risco residual: pontos que exigem decisao humana.

Isso conecta fan-out ao texto sobre evals de PR que seguram agentes de código no CI. O agente pode fazer trabalho paralelo, mas a aceitação precisa continuar baseada em prova.

Qual é o roteiro mínimo para esta semana?

Em 2026, o GitHub relatou que o Copilot code review cresceu 10 vezes desde o lançamento inicial e já responde por mais de uma em cada cinco revisões de código no GitHub (GitHub, "60 million Copilot code reviews and counting", 2026). O roteiro mínimo deve reduzir carga de revisão, não só aumentar volume de patches.

Primeiro, escolha uma migração pequena, mas real. Trocar uma função utilitária, atualizar uma API interna ou migrar um pacote TypeScript é melhor que atacar o monorepo inteiro. O objetivo é testar o protocolo de fan-out, não provar heroísmo.

Segundo, escreva três papéis. Um subagente de inventário, um subagente de teste e um subagente de revisão. Só depois adicione agentes que editam. Essa ordem evita que a equipe confunda paralelismo com falta de processo.

Terceiro, rode com limite. Dois ou três subagentes bastam no começo. Se eles encontrarem fronteiras claras, avance para worktrees. Se encontrarem acoplamento inesperado, pare e ajuste a arquitetura antes de multiplicar sessões.

Diagrama abstrato mostra fluxos de subagentes convergindo para uma verificação final sem texto visível.

Quarto, salve o aprendizado no repositório. Coloque comandos, fronteiras, áreas sensíveis e formato de evidência em AGENTS.md, CLAUDE.md ou documento equivalente. Isso ajuda Claude Code, Codex, Copilot e qualquer agente futuro a repetir o fluxo.

O sinal de sucesso é revisão menor e mais objetiva. Se o PR chega com escopo, teste e decisões descartadas, o fan-out ajudou. Se chega com cinco narrativas incompatíveis, você só automatizou o caos.

FAQ sobre fan-out de subagentes

Em 2026, a GitLab disse que 92% relatam algum desafio de governança com código gerado por IA (GitLab, "AI Accountability Report", 2026). As respostas abaixo ajudam a aplicar fan-out sem perder rastreabilidade.

Fan-out de subagentes serve para qualquer migração?

Não. Em 2026, a documentação do Claude Code recomenda escolher a abordagem conforme coordenação, comunicação e arquivos tocados (Claude Code Docs, "Run agents in parallel", 2026). Use fan-out quando há fronteiras independentes. Para mudança sequencial ou arquivo central único, um agente principal com checkpoints é melhor.

Subagentes devem editar código ou só revisar?

Depende da fronteira. Em 2026, a documentação do Claude Code explicou que subagentes têm contexto, ferramentas e permissões próprios (Claude Code Docs, "Create custom subagents", 2026). Eles podem editar quando o escopo é estreito. Para contratos compartilhados, prefira proposta de patch e aplicação pela sessão principal.

Worktree é obrigatório para fan-out?

Não, mas ajuda quando há edição paralela. Em 2026, a documentação do Claude Code recomenda worktrees para isolar tarefas que tocam arquivos (Claude Code Docs, "Run agents in parallel", 2026). Se os subagentes só leem e resumem, worktree é excesso. Se editam, ele reduz conflito.

Como medir se a orquestração melhorou?

Meça retrabalho de revisão. Em 2026, o GitHub disse que comentários de alta qualidade importam mais que volume e que 71% das revisões do Copilot code review têm feedback acionável (GitHub, "60 million Copilot code reviews and counting", 2026). O fan-out melhorou quando reduz comentários repetidos, conflitos e falhas pós-merge.

Fechamento

Em 2026, a GitLab afirmou que só 28% dizem ter ferramentas de ciclo de desenvolvimento totalmente integradas com dados e fluxos compartilhados (GitLab, "AI Accountability Report", 2026). Fan-out de subagentes é uma resposta prática para essa lacuna quando a equipe precisa migrar código grande com rastreabilidade.

Comece pequeno: inventário, teste e revisão. Depois permita patch em fronteiras claras. Use worktrees quando houver edição paralela, MCP quando o agente precisar de ferramenta estreita e CI para validar o resultado. O objetivo não é ter mais agentes. É entregar uma migração que o time consegue entender, verificar e manter.

Fontes consultadas

  • GitLab, "AI Accountability Report", recuperado em 2026-07-03, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
  • Google Cloud, "Announcing the 2025 DORA Report", recuperado em 2026-07-03, https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report
  • Claude Code Docs, "Run agents in parallel", recuperado em 2026-07-03, https://code.claude.com/docs/en/agents
  • Claude Code Docs, "Orchestrate teams of Claude Code sessions", recuperado em 2026-07-03, https://code.claude.com/docs/en/agent-teams
  • Stack Overflow, "2025 Developer Survey: AI", recuperado em 2026-07-03, https://survey.stackoverflow.co/2025/ai
  • OpenAI Developers, "Model Context Protocol - Codex", recuperado em 2026-07-03, https://developers.openai.com/codex/mcp
  • OpenAI Developers, "Use Codex with the Agents SDK", recuperado em 2026-07-03, https://developers.openai.com/codex/guides/agents-sdk
  • GitHub, "60 million Copilot code reviews and counting", recuperado em 2026-07-03, https://github.blog/ai-and-ml/github-copilot/60-million-copilot-code-reviews-and-counting/