Modulo 3.6: Orquestracao Multi-Agente

🎭 Conceito de Multi-Agente

Orquestracao multi-agente envolve multiplas instancias de Claude trabalhando simultaneamente em diferentes partes de um problema. Cada agente opera em seu proprio contexto, e um orquestrador coordena o trabalho.

🔄 Arquitetura Multi-Agente

                    ┌───────────────────┐
                    │   ORQUESTRADOR    │
                    │   (Coordenador)   │
                    └─────────┬─────────┘
              ┌───────────────┼───────────────┐
              │               │               │
        ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
        │  AGENTE 1 │  │  AGENTE 2 │  │  AGENTE 3 │
        │  Frontend │  │  Backend  │  │   Tests   │
        └─────┬─────┘  └─────┬─────┘  └─────┬─────┘
              │               │               │
        ┌─────▼─────┐  ┌─────▼─────┐  ┌─────▼─────┐
        │ /src/ui/  │  │ /src/api/ │  │ /tests/   │
        └───────────┘  └───────────┘  └───────────┘

• Paralelismo: Multiplas tarefas executam simultaneamente
• Isolamento: Cada agente tem seu proprio contexto
• Coordenacao: Orquestrador gerencia conflitos e merge

📊 Quando Usar Multi-Agente

Ideal para

• Refatoracoes grandes
• Implementacao de features independentes
• Geracao massiva de testes
• Migracao de codebase

Evitar quando

• Tarefas muito interdependentes
• Codigo altamente acoplado
• Mudancas que afetam mesmos arquivos
• Contexto compartilhado e critico

🎯 Estrategias de Divisao

A chave para multi-agente eficaz e dividir o trabalho corretamente. Tarefas mal divididas causam conflitos e retrabalho.

📁

Por Diretorio

Cada agente trabalha em pasta separada

Agente 1: /frontend/
Agente 2: /backend/
Agente 3: /mobile/

🏷️

Por Feature

Cada agente implementa uma feature

Agente 1: Auth
Agente 2: Dashboard
Agente 3: Reports

🔧

Por Tipo de Tarefa

Especialização por tipo de trabalho

Agente 1: Codigo
Agente 2: Testes
Agente 3: Docs

💡 Regra de Ouro

Se dois agentes precisam editar o mesmo arquivo, a divisao esta errada. Reorganize as tarefas para garantir isolamento completo.

🖥️ Implementacao com Tmux

A forma mais simples de rodar multi-agente e usar multiplos terminais. Tmux permite gerenciar varias sessoes facilmente.

Script de Setup

#!/bin/bash
# multi-agent-setup.sh

SESSION="multi-claude"

# Criar sessao tmux
tmux new-session -d -s $SESSION -n "orchestrator"

# Criar paineis para agentes
tmux split-window -h -t $SESSION
tmux split-window -v -t $SESSION
tmux select-pane -t $SESSION:0.0
tmux split-window -v -t $SESSION

# Nomear paineis
tmux select-pane -t $SESSION:0.0 -T "orchestrator"
tmux select-pane -t $SESSION:0.1 -T "frontend"
tmux select-pane -t $SESSION:0.2 -T "backend"
tmux select-pane -t $SESSION:0.3 -T "tests"

# Iniciar Claude em cada painel
tmux send-keys -t $SESSION:0.1 "cd frontend && claude" Enter
tmux send-keys -t $SESSION:0.2 "cd backend && claude" Enter
tmux send-keys -t $SESSION:0.3 "cd tests && claude" Enter

# Attach na sessao
tmux attach -t $SESSION

Comandos Uteis Tmux

Ctrl+b %

Split vertical

Ctrl+b "

Split horizontal

Ctrl+b o

Proximo painel

Ctrl+b z

Zoom painel

Layout Recomendado

┌────────────────────┬────────────────────┐
│    ORCHESTRATOR    │      FRONTEND      │
│  (voce coordena)   │  (claude agente)   │
├────────────────────┼────────────────────┤
│      BACKEND       │       TESTS        │
│  (claude agente)   │  (claude agente)   │
└────────────────────┴────────────────────┘

🔀 Gerenciando Conflitos

Mesmo com boa divisao, conflitos podem surgir. Tenha estrategias para detectar e resolver rapidamente.

Conflitos Comuns

! Dois agentes editam mesmo arquivo
! Mudancas em interface compartilhada
! Conflitos de dependencias
! Testes quebrados por mudancas paralelas

Estrategias de Resolucao

✓ Commits frequentes e atomicos
✓ Branches por agente
✓ Feature flags para integracao
✓ Interfaces contratuais definidas antes

Workflow com Git Branches

# Antes de iniciar - criar branches
git checkout -b feature/auth-frontend   # Agente 1
git checkout -b feature/auth-backend    # Agente 2
git checkout -b feature/auth-tests      # Agente 3

# Durante - commits frequentes
git add . && git commit -m "wip: progresso parcial"

# Apos conclusao - merge sequencial
git checkout main
git merge feature/auth-backend --no-ff
git merge feature/auth-frontend --no-ff
git merge feature/auth-tests --no-ff

⚠️ Importante

Sempre defina interfaces antes de iniciar trabalho paralelo. Se o backend expoe uma API, documente os endpoints antes do frontend comecar a consumir.

📋 Protocolo de Comunicacao

Defina um protocolo claro para comunicacao entre agentes e o orquestrador (voce).

Arquivo de Coordenacao

# .claude/coordination.md

## Status dos Agentes

| Agente | Tarefa | Status | Bloqueio |
|--------|--------|--------|----------|
| Frontend | Tela de login | Em progresso | Aguarda API |
| Backend | API de auth | Completo | - |
| Tests | Testes unitarios | Em progresso | - |

## Interfaces Acordadas

### API de Autenticacao
- POST /api/auth/login
  - Body: { email, password }
  - Response: { token, user }

### Eventos de Frontend
- onLoginSuccess(user)
- onLoginError(error)

## Decisoes Pendentes
- [ ] Usar JWT ou sessao?
- [ ] Refresh token automatico?

## Log de Mudancas
- 10:30 - Backend: API de login pronta
- 10:45 - Frontend: Iniciando integracao

Sinais do Orquestrador

@all PAUSA - Todos param
@frontend ESPERA - Aguardar dependencia
@backend PRIORIDADE - Foco nessa tarefa
@all SYNC - Commit e push agora

Sinais dos Agentes

DONE - Tarefa concluida
BLOCKED - Precisa de algo
CONFLICT - Encontrou conflito
QUESTION - Duvida de requisito

💡 Dica

Mantenha o arquivo coordination.md aberto em uma aba. Atualize-o conforme os agentes progridem para ter visibilidade do status geral.

🎯 Caso Pratico: Refatoracao

Vamos ver um exemplo completo de refatoracao multi-agente de um sistema legado.

Analise e Planejamento

Orquestrador analisa o codigo legado

"Analise src/ e identifique modulos independentes que podem ser refatorados em paralelo"

Divisao de Tarefas

Definir escopo de cada agente

Agente 1: Refatorar src/auth/ (5 arquivos)
Agente 2: Refatorar src/users/ (4 arquivos)
Agente 3: Atualizar testes de auth e users

Execucao Paralela

Cada agente trabalha em sua branch

# Em cada terminal
git checkout -b refactor/[modulo]
claude "Refatore [escopo] seguindo os padroes em CLAUDE.md"

Integracao e Validacao

Merge das branches e testes finais

git checkout main
git merge --no-ff refactor/auth
git merge --no-ff refactor/users
npm run test && npm run lint

Resultado

Mais rapido

Conflitos de merge

100%

Cobertura de testes

📋 Resumo do Modulo

✓

Multi-agente multiplica produtividade - tarefas paralelas, resultados mais rapidos

✓

Divisao correta e essencial - por diretorio, feature ou tipo de tarefa

✓

Tmux para gerenciar terminais - multiplos agentes em uma tela

✓

Git branches evitam conflitos - uma branch por agente, merge sequencial

✓

Protocolo de comunicacao claro - coordination.md para status e decisoes

Proximo Modulo:

3.7 - GitHub Actions e CI/CD com Claude - automatize reviews e testes no pipeline

← Modulo Anterior Proximo Modulo →