Multi-agente é o buzzword que todo mundo cola num slide. Também é onde Claude Code fica genuinamente interessante — quando usado cirurgicamente.

A forma que funciona: um pipeline pequeno de sub-agentes limitados, cada um fazendo uma coisa, com handoff explícito. A forma que falha: "enxame de agentes debatendo arquitetura".

Vamos ao tático.

Os três padrões que de fato entregam

1. Pipeline linear (o feijão com arroz)

test-writer  →  test-fixer  →  code-reviewer  →  release-bot

Cada passo tem uma entrada e uma saída. Falhas param o pipeline. É 80% do que os times usam.

2. Fan-out / fan-in

Quando a tarefa é naturalmente paralela — traduzir 5 arquivos, gerar testes para 12 módulos, escanear logs de 8 serviços — abra em leque.

            ┌─ translator(es) ─┐
            ├─ translator(fr) ─┤
spawner ──> ├─ translator(ar) ─┤── merger
            ├─ translator(pt) ─┤
            └─ translator(de) ─┘

Você dispara N sub-agentes especializados em paralelo, e um sub-agente merger reconcilia as saídas (deduplica, escolhe a variante de maior confiança, escreve um único PR).

3. Loop de crítico

writer  ↔  critic

O writer produz. O crítico pontua contra uma rubrica. O writer revisa. Para quando o crítico passa de um threshold ou após N rodadas.

Esse padrão brilha para:

• Reescritas de docs.
• Planos de migração.
• Propostas de refactor onde "isso está limpo?" é o portão.

O crítico tem que ser um sub-agente diferente do writer. Mesmo agente se autocriticando é teatro.

Onde multi-agente deixa de pagar

Depois de um ano, minha visão honesta sobre os retornos decrescentes:

• 2 agentes: salto enorme. Writer + reviewer é ganho real.
• 3-4 agentes: útil para pipelines claros (test-writer → fixer → reviewer).
• 5+ agentes: marginal na melhor das hipóteses. Custo de coordenação > ganho de delegação.
• "Enxame de 10 agentes debatendo": demo, não workflow.

Se seu pipeline tem mais de 4 sub-agentes, pergunte se metade não poderia ser comandos shell ou targets de Makefile.

Concreto: um pipeline "PR factory"

Objetivo: pegar um ticket do Linear, entregar um PR.

1. ticket-reader     → parseia o ticket do Linear, gera um prompt /feature
2. implementer       → escreve o código
3. test-writer       → escreve / atualiza testes
4. test-fixer        → se algum teste falha, conserta o código (não o teste)
5. code-reviewer     → revisa o diff, SHIP / FIX-FIRST / REWRITE
6. release-bot       → redige descrição de PR + entrada de changelog
7. (humano)          → revisa o diff e dá push

Cada passo é um sub-agente em .claude/agents/. O passo humano no fim não é negociável — é onde o git push acontece.

Tempo de execução numa feature típica: 4-12 minutos de wall clock. Revisão humana no fim: 5-15 minutos. Ponta a ponta: uma feature por hora, sustentável.

Como invocar um pipeline na prática

Dois sabores.

Passo a passo manual (recomendado no começo)

> /agents implementer
> Objetivo: ... Restrições: ... DoD: ... Arquivos: ...

# espera, revise

> /agents test-writer
> Escreva testes para o código novo.

# espera, revise

> /agents code-reviewer
> Revise o diff.

Você fica no controle. Lento mas seguro.

Orquestrado via slash command

.claude/commands/pr-factory.md:

1. Dispare `implementer` com o objetivo dado pelo usuário.
2. Espere terminar. Se implementer falhar, aborte.
3. Dispare `test-writer` no diff.
4. Dispare `test-fixer` até os testes passarem ou após 3 retries.
5. Dispare `code-reviewer` no diff final.
6. Se veredito != SHIP, escale ao usuário e pare.
7. Senão dispare `release-bot` para descrição de PR.
8. Imprima um resumo de uma linha e pare. Nunca dê push.

Depois:

> /pr-factory
> Objetivo: <preencher> Restrições: <preencher> DoD: <preencher> Arquivos: <preencher>

Você roda um comando. O pipeline executa. O push continua sendo uma tecla humana.

Padrões paralelos — quando usar

Rode agentes em paralelo quando:

• O trabalho é independente (traduzir 5 arquivos, resumir 8 PRs).
• Você consegue escrever um merger determinístico (concat, dedup, pick-highest-score).
• Você consegue orçar o custo (paralelo = mais chamadas de API, menos wall clock).

Evite paralelo quando:

• Tarefas têm dependências (test-fixer precisa do diff do implementer).
• O passo de merge é fuzzy ("qual arquitetura preferimos?"). Isso não é merge — é decisão humana.

O truque mais útil: handoffs explícitos

Cada sub-agente encerra sua vez emitindo um handoff estruturado:

status: ok | needs-human | failed
artifacts:
  - path: src/cache.ts
  - path: tests/cache.test.ts
notes: "Implementado LRU + TTL. Todos os testes verdes."
next: test-writer | code-reviewer | done

O próximo agente lê esse handoff e sabe exatamente onde está. Sem rederivar contexto, sem "peraí, qual era o objetivo?".

Padronizar o handoff é a alavanca mais alta quando você tem 3+ sub-agentes. É o equivalente multi-agente de uma assinatura de função bem tipada.

---

Próximo artigo: Construindo features completas — pegar tudo daqui e dos artigos 3-7 e percorrer uma sessão real de ticket-para-PR, comando por comando.