💥 O Caos Clássico do Multiagente Ingênuo
Roda dois agentes Codex no mesmo repositório, mesma branch, sem isolamento. Em 20 minutos: conflito de merge no AGENTS.md, agente A reescreve componente que B acabou de criar, e você gasta 1h limpando bagunça que nem teria existido com 1 agente.
📊 Cenário do Caos — Linha do Tempo
⚠️ Os 4 sintomas que indicam que você caiu na armadilha
- •Conflitos de merge em arquivos óbvios (package.json, AGENTS.md, lockfiles)
- •Trabalho some: você jura que viu o agente B criar um componente, mas ele não está mais no repo
- •Estado inconsistente: front chama API que back já removeu (ou vice-versa)
- •Você passa mais tempo arbitrando entre agentes do que revisando código
🌳 Cada Agente em sua Worktree
Git worktree é a primitiva técnica que destrava o multiagente. Cada agente abre sua própria pasta, sua branch, seu node_modules. O repo continua único, mas o filesystem fica isolado.
🛠️ Setup das 6 worktrees
# Repo principal: ~/projects/inboxai
cd ~/projects/inboxai
# Cria 1 worktree por papel
git worktree add ../inboxai-frontend feature/frontend
git worktree add ../inboxai-backend feature/backend
git worktree add ../inboxai-qa feature/qa
git worktree add ../inboxai-mkt feature/marketing
git worktree add ../inboxai-pesquisa feature/pesquisa
git worktree add ../inboxai-arq feature/arquitetura
# Resultado
git worktree list
# /home/voce/projects/inboxai abc123 [main]
# /home/voce/projects/inboxai-frontend def456 [feature/frontend]
# /home/voce/projects/inboxai-backend ghi789 [feature/backend]
# ...
# Em cada terminal/sessão Codex, abre uma pasta diferente
cd ~/projects/inboxai-frontend && codex
cd ~/projects/inboxai-backend && codex
# ...zero conflito de filesystem✓ Ganhos imediatos
- • Cada agente vê só seu node_modules
- • Builds paralelos não brigam por porta
- • Branches já isoladas → PR limpa
- • Você abre 6 VS Code, cada um numa pasta
⚠️ Cuidados
- • Disco: 6 worktrees = 6× node_modules
- • .env precisa estar em cada worktree
- • git worktree remove no fim do projeto
- • Não dê push direto na main
🎭 Os 6 Papéis Canônicos da Equipe-Fantasma
Cada agente recebe um AGENTS.md próprio definindo escopo, fronteiras e o que NÃO deve tocar. Especialização é mais valiosa que generalismo no multiagente — agentes generalistas brigam por território.
| Papel | Faz | Não faz |
|---|---|---|
| 🏛️ Arquiteto | Define schema, contratos de API, decisões estruturais | Não escreve UI, não escreve queries |
| 🎨 Frontend | Componentes, páginas, estado de UI, Tailwind | Não toca em /api ou no schema |
| ⚙️ Backend | Routes, queries, jobs, integrações externas | Não mexe em /components |
| 🧪 QA | Testes E2E, testes unitários, fixtures | Não corrige bugs — abre issue |
| 📣 Marketing | Landing /marketing, copy, posts, assets | Não toca no app real |
| 🔬 Pesquisa | Concorrentes, benchmark, docs/research | Não escreve código de produção |
💡 A regra de ouro
No AGENTS.md de cada papel, escreva uma seção "Anti-objetivos" com o que aquele agente NÃO faz. É mais importante do que listar o que faz — porque é onde o caos começa quando dois agentes acham que a mesma coisa é deles.
🎬 Você como Agente Coordenador
Seu papel real não é programar — é definir interfaces, mediar conflitos e decidir prioridades. Quem fica programando junto com os agentes vira gargalo. Quem só coordena destrava 4–8x output.
🎯 As 4 atividades do coordenador
Antes de qualquer agente codar, você fixa: contratos da API, formato dos eventos, schema do banco. Vira input pra TODOS.
Backend deve fazer X antes de Y porque frontend depende. Você é quem mantém ordem de execução clara.
Quando 2 agentes querem o mesmo arquivo, você decide quem ganha e ajusta AGENTS.md pra evitar de novo.
PRs entram pra você. Você revisa, comenta, pede ajuste, faz merge. É a última linha de defesa de qualidade.
📌 Sinal claro de que você está coordenando bem
Você passa 70% do tempo lendo PRs e ajustando AGENTS.md, 20% definindo próximas tarefas, e menos de 10% escrevendo código direto. Se você está digitando código todo dia, ainda é programador, não coordenador.
📨 Comunicação Assíncrona via PRs
PRs viram a interface oficial de comunicação. Cada agente abre PR quando termina; você revisa, comenta, faz merge. Sem chat ao vivo, sem reuniões, sem perda de rastro.
🔄 Fluxo de PR multiagente
📋 Template de PR de agente
## Resumo
<1-2 linhas do que mudou>
## Escopo
- [x] Componente X criado
- [x] Testes para X
- [ ] Integração com /api/x (depende de PR #42 do back)
## Test plan
- [ ] npm run dev → abrir /dashboard → checar X
- [ ] npm test src/components/X.test.tsx
## Notas pro diretor
Bloqueado por: PR #42 (backend)
Decisão pendente: tom da mensagem de erro
🤖 Agente: frontend⚠️ Quando ABANDONAR Multiagente
Multiagente tem custo de coordenação fixo. Se a tarefa é pequena, o overhead vence o ganho de paralelismo e você gasta mais tempo dando briefing do que ganharia. Reconhecer isso é maturidade.
❌ Não use multiagente quando
- •Tarefa total cabe em < 30 minutos
- •Bug isolado em 1 ou 2 arquivos
- •Refactor que toca tudo no mesmo módulo
- •Você não sabe ainda como o produto deve funcionar
- •POC/exploração — vibe coding com 1 agente é melhor
✓ Use multiagente quando
- ✓Lançamento com 4+ frentes (front, back, mkt, vídeo)
- ✓Sprint de 2+ dias com escopo claro
- ✓Especificação madura, contratos definidos
- ✓Deadline apertado (uma noite, um fim de semana)
- ✓Você quer ir dormir e acordar com PRs prontas
💡 A heurística da regra-de-bolso
Se você consegue escrever AGENTS.md de cada agente em < 10 minutos cada, multiagente vale. Se você ainda está descobrindo o produto enquanto coda, fica com 1 agente focado. Multiagente é amplificador, não acelerador inicial.
✅ O que Aprendemos
Próximo Módulo:
5.2 — Browser Use + Computer Use: quando o agente precisa controlar um browser real ou seu desktop inteiro, e onde você NÃO deve deixar ele entrar.