artubss/SKILLS-CLAUDE-CODE / skills/skills/ai-research/dispatching-parallel-agents
dispatching-parallel-agents
UnverifiedUse quando enfrenta 2+ tarefas independentes que podem ser trabalhadas sem estado compartilhado ou dependências sequenciais
Despachando Agentes em Paralelo
Visão Geral
Quando você tem múltiplas falhas não relacionadas (arquivos de teste diferentes, subsistemas diferentes, bugs diferentes), investigá-las sequencialmente desperdiça tempo. Cada investigação é independente e pode acontecer em paralelo.
Princípio central: Despache um agente por domínio de problema independente. Deixe-os trabalhar simultaneamente.
Quando Usar
digraph when_to_use {
"Múltiplas falhas?" [shape=diamond];
"São independentes?" [shape=diamond];
"Um agente investiga tudo" [shape=box];
"Um agente por domínio" [shape=box];
"Podem trabalhar em paralelo?" [shape=diamond];
"Agentes sequenciais" [shape=box];
"Despacho em paralelo" [shape=box];
"Múltiplas falhas?" -> "São independentes?" [label="sim"];
"São independentes?" -> "Um agente investiga tudo" [label="não - relacionadas"];
"São independentes?" -> "Podem trabalhar em paralelo?" [label="sim"];
"Podem trabalhar em paralelo?" -> "Despacho em paralelo" [label="sim"];
"Podem trabalhar em paralelo?" -> "Agentes sequenciais" [label="não - estado compartilhado"];
}
Use quando:
- 3+ arquivos de teste falhando com causas raiz diferentes
- Múltiplos subsistemas quebrados independentemente
- Cada problema pode ser entendido sem contexto dos outros
- Sem estado compartilhado entre investigações
Não use quando:
- Falhas são relacionadas (corrigir uma pode corrigir outras)
- Precisa entender o estado completo do sistema
- Agentes interfeririam um com o outro
O Padrão
1. Identifique Domínios Independentes
Agrupe falhas pelo que está quebrado:
- Testes do Arquivo A: Fluxo de aprovação de ferramenta
- Testes do Arquivo B: Comportamento de conclusão em lote
- Testes do Arquivo C: Funcionalidade de abortar
Cada domínio é independente – corrigir aprovação de ferramenta não afeta testes de aborto.
2. Crie Tarefas de Agente Focadas
Cada agente recebe:
- Escopo específico: Um arquivo de teste ou subsistema
- Objetivo claro: Fazer esses testes passarem
- Restrições: Não altere outro código
- Output esperado: Resumo do que você encontrou e corrigiu
3. Despache em Paralelo
// Em Claude Code / ambiente AI
Task("Corrigir falhas em agent-tool-abort.test.ts")
Task("Corrigir falhas em batch-completion-behavior.test.ts")
Task("Corrigir falhas em tool-approval-race-conditions.test.ts")
// Os três rodam concorrentemente
4. Revise e Integre
Quando agentes retornam:
- Leia cada resumo
- Verifique se os corrigios não entram em conflito
- Execute a suite de testes completa
- Integre todas as mudanças
Estrutura de Prompt de Agente
Bons prompts de agente são:
- Focados - Um domínio de problema claro
- Autossuficientes - Todo contexto necessário para entender o problema
- Específicos sobre output - O que o agente deve retornar?
Corrija os 3 testes falhando em src/agents/agent-tool-abort.test.ts:
1. "should abort tool with partial output capture" - espera 'interrupted at' na mensagem
2. "should handle mixed completed and aborted tools" - ferramenta rápida foi abortada em vez de concluída
3. "should properly track pendingToolCount" - espera 3 resultados mas recebe 0
Estes são problemas de timing/race condition. Sua tarefa:
1. Leia o arquivo de teste e entenda o que cada teste verifica
2. Identifique a causa raiz – problemas de timing ou bugs reais?
3. Corrija:
- Substituindo timeouts arbitrários por espera baseada em eventos
- Corrigindo bugs na implementação de aborto se encontrados
- Ajustando expectativas de teste se o comportamento mudou
Não apenas aumente timeouts – encontre o problema real.
Retorne: Resumo do que você encontrou e do que você corrigiu.
Erros Comuns
❌ Muito amplo: "Corrija todos os testes" - agente fica perdido ✅ Específico: "Corrija agent-tool-abort.test.ts" - escopo focado
❌ Sem contexto: "Corrija a race condition" - agente não sabe onde ✅ Contexto: Cole as mensagens de erro e nomes de testes
❌ Sem restrições: Agente pode refatorar tudo ✅ Restrições: "NÃO altere código de produção" ou "Corrija apenas testes"
❌ Output vago: "Corrija" - você não sabe o que mudou ✅ Específico: "Retorne resumo da causa raiz e mudanças"
Quando NÃO Usar
Falhas relacionadas: Corrigir uma pode corrigir outras - investigue junto primeiro Precisa de contexto completo: Entender requer ver todo o sistema Debugging exploratório: Você não sabe o que está quebrado ainda Estado compartilhado: Agentes interfeririam (editando mesmos arquivos, usando mesmos recursos)
Exemplo Real de Sessão
Cenário: 6 falhas de teste em 3 arquivos após refatoração maior
Falhas:
- agent-tool-abort.test.ts: 3 falhas (problemas de timing)
- batch-completion-behavior.test.ts: 2 falhas (ferramentas não executando)
- tool-approval-race-conditions.test.ts: 1 falha (contagem de execução = 0)
Decisão: Domínios independentes - lógica de aborto separada de conclusão em lote separada de race conditions
Despacho:
Agente 1 → Corrigir agent-tool-abort.test.ts
Agente 2 → Corrigir batch-completion-behavior.test.ts
Agente 3 → Corrigir tool-approval-race-conditions.test.ts
Resultados:
- Agente 1: Substituiu timeouts por espera baseada em eventos
- Agente 2: Corrigiu bug de estrutura de evento (threadId no lugar errado)
- Agente 3: Adicionou espera para conclusão de execução assíncrona de ferramenta
Integração: Todos os corrigios independentes, sem conflitos, suite completa verde
Tempo economizado: 3 problemas resolvidos em paralelo vs sequencialmente
Benefícios Principais
- Paralelização - Múltiplas investigações acontecem simultaneamente
- Foco - Cada agente tem escopo estreito, menos contexto para rastrear
- Independência - Agentes não interferem um com o outro
- Velocidade - 3 problemas resolvidos no tempo de 1
Verificação
Depois que agentes retornam:
- Revise cada resumo - Entenda o que mudou
- Verifique conflitos - Agentes editaram o mesmo código?
- Execute suite completa - Verifique se todos os corrigios funcionam juntos
- Verificação pontual - Agentes podem cometer erros sistemáticos
Impacto no Mundo Real
Da sessão de debugging (2025-10-03):
- 6 falhas em 3 arquivos
- 3 agentes despachados em paralelo
- Todas as investigações completadas concorrentemente
- Todos os corrigios integrados com sucesso
- Zero conflitos entre mudanças de agentes
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |