Despachando Agentes Paralelos

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 para cada domínio de problema independente. Deixe-os trabalhar concorrentemente.

Quando Usar

digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}

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
• Nenhum estado compartilhado entre investigações

Não use quando:

• Falhas estão relacionadas (corrigir uma pode corrigir outras)
• Precisa entender o estado completo do sistema
• Agentes interfeririam uns com os outros

O Padrão

1. Identificar Domínios Independentes

Agrupe as falhas pelo que está quebrado:

• Testes do Arquivo A: Fluxo de aprovação de ferramentas
• Testes do Arquivo B: Comportamento de conclusão de lote
• Testes do Arquivo C: Funcionalidade de abortar

Cada domínio é independente - corrigir a aprovação de ferramentas não afeta os testes de abortar.

2. Criar 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 alterar outro código
• Saída esperada: Resumo do que você encontrou e corrigiu

3. Despachar em Paralelo

// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. Revisar e Integrar

Quando os agentes retornarem:

• Leia cada resumo
• Verifique se as correções não entram em conflito
• Execute a suíte de testes completa
• Integre todas as alterações

Estrutura do Prompt do Agente

Bons prompts de agente são:

1. Focados - Um domínio de problema claro
2. Autocontidos - Todo o contexto necessário para entender o problema
3. Específicos sobre a saída - O que o agente deve retornar?

Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

Erros Comuns

❌ Muito amplo: "Corrigir todos os testes" - o agente se perde ✅ Específico: "Corrigir agent-tool-abort.test.ts" - escopo focado

❌ Sem contexto: "Corrigir a condição de corrida" - o agente não sabe onde ✅ Contexto: Cole as mensagens de erro e os nomes dos testes

❌ Sem restrições: O agente pode refatorar tudo ✅ Restrições: "NÃO alterar código de produção" ou "Corrigir apenas testes"

❌ Saída vaga: "Conserte" - você não sabe o que mudou ✅ Específico: "Retornar resumo da causa raiz e das alterações"

Quando NÃO Usar

Falhas relacionadas: Corrigir uma pode corrigir outras - investigue juntas primeiro Precisa de contexto completo: O entendimento requer ver o sistema inteiro Depuração exploratória: Você ainda não sabe o que está quebrado Estado compartilhado: Agentes interfeririam (editando os mesmos arquivos, usando os mesmos recursos)

Exemplo Real da Sessão

Cenário: 6 falhas de teste em 3 arquivos após refatoração importante

Falhas:

• agent-tool-abort.test.ts: 3 falhas (problemas de timing)
• batch-completion-behavior.test.ts: 2 falhas (ferramentas não executando)

…