Workflow multiagente no Claude Code: papéis, isolamento e revisão manual
Guia prático para workflows multiagente no Claude Code: separação de papéis, isolamento com Git worktrees, cartão de handoff e validação manual.
Construir “equipes de agentes de IA” totalmente autônomas, que fazem merge de código automaticamente, pode introduzir falhas sutis de arquitetura, ciclos de refatoração e degradação da base de código. Dois agentes executados em paralelo não formam uma fonte independente de verdade: se o agente autor cometer um erro de lógica, um revisor que trabalhe com fundamentos de prompt semelhantes também pode não percebê-lo.
Um workflow multiagente confiável não se apoia na ilusão de autonomia completa, mas em uma separação rigorosa de papéis: um implementador (Author), um verificador independente (Reviewer) e uma pessoa desenvolvedora que toma a decisão final de merge.
1. Limites dos papéis: Author, Reviewer e decisor humano
Em um fluxo de desenvolvimento eficaz, cada participante tem uma área de responsabilidade bem definida e fechada:
2. Isolamento de contexto e de workspace
Nunca execute os agentes Author e Reviewer no mesmo diretório de trabalho nem na mesma conversa. Isole-os em três níveis operacionais:
- Contexto de sessão: conversas independentes evitam alucinações mútuas e confirmações circulares.
- Isolamento do sistema de arquivos: Git worktrees separados garantem que o reviewer examine apenas um diff confirmado, sem estado local pendente.
- Segurança do ambiente: chaves de API e credenciais de execução permanecem em variáveis de ambiente e nunca são incluídas no texto do prompt.
Comandos para preparar os worktrees
[!IMPORTANT]
Configuração da API: cada sessão do Claude Code usa suas próprias credenciais de API, configuradas por variáveis de ambiente do sistema operacional. Consulte o guia do BetterToken para Claude Code.
3. O contrato de handoff estruturado
Quando o agente Author conclui a implementação, ele produz um cartão de handoff conciso. Transcrições brutas de chat, segredos e suposições não verificadas ficam estritamente de fora:
Handoff Card
- Task: Add HTTP 429 retry support in payment client with exponential backoff.
- Branch:
feat/payment-retry - Changed Files:
src/client/http.ts,tests/http-retry.test.ts - Verification Command:
npm test -- tests/http-retry.test.ts(Passed) - Risks & Blockers: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- Next Step: Reviewer agent validates Retry-After header handling.
4. Protocolo de aprovação com humano no circuito
O agente Reviewer realiza uma avaliação isolada:
- Entra no worktree limpo:
../agent-reviewer. - Executa o comando de verificação registrado.
- Inspeciona o diff de forma independente em busca de efeitos colaterais e casos extremos.
- Produz um resumo estruturado para a pessoa responsável pela engenharia.
A pessoa engenheira faz a aprovação final:
- revisa os achados do reviewer;
- confirma a ausência de regressões em relação a
main; - executa o merge manualmente:
git merge feat/payment-retry.
Esse pipeline evita ciclos de confirmação mútua e mantém o controle de qualidade e da arquitetura nas mãos de quem desenvolve.