Módulo 1.9 — Agentes Paralelos

🔀 dispatching-parallel-agents: quando dividir

A skill dispatching-parallel-agents fornece os critérios para decidir quando vale paralelizar. A decisão não é sempre "paralelizar tudo" — há overhead de coordenação que precisa ser justificado pelo ganho de velocidade.

Critérios para paralelizar

✓As tarefas são independentes — A não precisa do resultado de B
✓Cada tarefa leva pelo menos 15-20 minutos para completar
✓Os contratos de interface entre as partes estão definidos
✓Cada tarefa pode ser testada independentemente

O ponto de break-even

Se cada tarefa leva 5 minutos, o overhead de coordenação (criar worktrees, definir contratos, integrar resultados) pode levar 10 minutos — perdendo o benefício. Paralelismo compensa para tarefas de 20+ minutos.

🤝 Coordenação sem conflito entre agentes

A coordenação entre agentes paralelos é responsabilidade do agente coordenador (ou de você, se não houver um). Sem coordenação explícita, dois agentes podem modificar o mesmo arquivo, criar funções duplicadas ou fazer suposições incompatíveis sobre o estado do sistema.

Partição por arquivo

Agente A modifica apenas src/api/, Agente B modifica apenas src/ui/. Sem sobreposição de arquivos, sem conflito possível.

Partição por funcionalidade

Agente A implementa autenticação, Agente B implementa autorização. A fronteira é o contrato de interface: o que cada função expõe e espera.

Worktrees como lock implícito

Cada agente em sua própria worktree não pode afetar os arquivos do outro. O lock é físico — diretórios separados — não lógico.

📐 Definindo contratos de interface antes

O pré-requisito do paralelismo é a definição dos contratos de interface — antes de despachar qualquer agente. Os contratos especificam exatamente o que cada parte expõe para as outras, permitindo implementações independentes que se encaixam na integração.

O que um contrato deve definir

→Assinatura de funções/métodos compartilhados (tipos de input e output)
→Formato de dados trocados (esquema JSON, tipos TypeScript)
→Comportamento em erros (o que cada parte faz quando a outra falha)
→Estado compartilhado e quem é o dono de cada parte

Exemplo de contrato mínimo

// Contrato: módulo de autenticação
interface AuthService {
  login(email: string, password: string): Promise<AuthToken>
  logout(token: string): Promise<void>
  verify(token: string): Promise<User | null>
}

🔗 Integrando resultados de agentes paralelos

A integração é a fase mais crítica do paralelismo. É onde partes que funcionam individualmente precisam funcionar juntas. O processo tem etapas definidas que capturam incompatibilidades antes que se tornem bugs em produção.

Coletar resultados — cada agente commita na sua worktree e reporta o que implementou

Verificar contratos — confirmar que cada parte implementou o contrato exatamente como definido

Merge sequencial — integrar uma branch por vez, rodando testes após cada merge

Teste de integração — executar testes que exercitam a interação entre as partes

🚧 Limites do paralelismo: quando não dividir

O entusiasmo com paralelismo leva ao erro oposto: paralelizar tudo, incluindo tarefas que se beneficiam da execução sequencial. Reconhecer esses casos evita complexidade desnecessária.

Quando NÃO paralelizar

✗Dependência sequencial forte: B não pode começar sem o resultado de A
✗Contexto compartilhado essencial: ambas as partes precisam entender o estado completo
✗Tarefas muito pequenas: overhead de coordenação maior que o trabalho em si
✗Contratos indefinidos: sem interface clara, paralelismo cria incompatibilidades
✗Feature exploratória: quando você não sabe ainda o que está construindo

Paralelismo é uma otimização para execução, não para exploração. Use sequencialmente até entender bem o problema, então paralelize a implementação.

🛠️ Prática: feature dividida e paralelizada

Exercício completo: tomar uma feature de médio porte, dividi-la em partes independentes, definir contratos, criar worktrees para cada parte e integrar os resultados.

Roteiro do exercício

1.Escolha uma feature com pelo menos 2 partes independentes
2.Defina os contratos de interface entre as partes (tipos, APIs)
3.Crie uma worktree por parte e despache um agente em cada uma
4.Monitore os relatórios dos agentes conforme trabalham
5.Verifique conformidade com os contratos antes de integrar
6.Integre sequencialmente, testando após cada merge

Critério de conclusão

Feature integrada com sucesso, todos os testes passando, contrato respeitado pelas duas partes. Você usou paralelismo de forma estruturada e verificável.

Resumo do Módulo 1.9

✓Sei quando paralelizar e quando não paralelizar

✓Coordeno agentes paralelos sem conflito via partição de trabalho

✓Defino contratos de interface antes de despachar agentes

✓Integro resultados de forma estruturada: coleta → verificação → merge → teste

✓Reconheço os 5 cenários onde paralelismo não deve ser usado

✓Completei o exercício de feature dividida e paralelizada

Próximo módulo: 1.10 — Criando suas próprias Skills

← Voltar para Trilha Próximo Módulo →

⚡ Agentes paralelos