AI代理并行调度指南：如何高效处理多个独立故障与测试问题

dispatching-parallel-agents by obra/superpowers

22,400 周安装量

107,700 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/obra/superpowers --skill dispatching-parallel-agents

AI/机器学习开发生产力

🇨🇳中文介绍

并行调度代理

概述

您可以将任务委托给具有独立上下文的专业代理。通过精心设计指令和上下文，确保它们保持专注并成功完成任务。它们绝不应继承您会话的上下文或历史记录——您需要精确构建它们所需的内容。这也能保留您自己的上下文以进行协调工作。

当您遇到多个不相关的故障（不同的测试文件、不同的子系统、不同的错误）时，按顺序调查它们会浪费时间。每个调查都是独立的，可以并行进行。

核心原则： 为每个独立的问题域调度一个代理。让它们并发工作。

何时使用

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"];
}

在以下情况使用：

3个以上测试文件因不同根本原因而失败
多个子系统独立损坏
每个问题无需其他问题的上下文即可理解
调查之间没有共享状态

不要在以下情况使用：

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

2. 创建专注的代理任务

每个代理获得：

特定范围： 一个测试文件或子系统
明确目标： 使这些测试通过
约束： 不要更改其他代码
预期输出： 发现和修复内容的摘要

// 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

当代理返回时：

阅读每个摘要
验证修复没有冲突
运行完整的测试套件
集成所有更改

好的代理提示应具备：

专注性 - 一个清晰的问题域
自包含性 - 理解问题所需的所有上下文
输出明确性 - 代理应返回什么？

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.

❌ 范围太广： "修复所有测试" - 代理会迷失方向 ✅ 具体： "修复 agent-tool-abort.test.ts" - 专注的范围

❌ 无上下文： "修复竞态条件" - 代理不知道在哪里 ✅ 提供上下文： 粘贴错误信息和测试名称

❌ 无约束： 代理可能重构所有内容 ✅ 设置约束： "不要更改生产代码" 或 "仅修复测试"

❌ 输出模糊： "修复它" - 您不知道更改了什么 ✅ 具体： "返回根本原因和更改的摘要"

相关故障： 修复一个可能修复其他——先一起调查 需要完整上下文： 理解需要查看整个系统 探索性调试： 您还不知道哪里坏了 共享状态： 代理会相互干扰（编辑相同文件，使用相同资源）

会话中的真实示例

场景： 重大重构后，3个文件出现6个测试失败

agent-tool-abort.test.ts: 3个故障（时序问题）
batch-completion-behavior.test.ts: 2个故障（工具未执行）
tool-approval-race-conditions.test.ts: 1个故障（执行计数 = 0）

决策： 独立域——中止逻辑与批量完成分离，与竞态条件分离

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

代理 1：用时序等待替换了超时
代理 2：修复了事件结构错误（threadId 位置错误）
代理 3：添加了等待异步工具执行完成的逻辑

集成： 所有修复独立，无冲突，完整套件通过

节省时间： 3个问题并行解决 vs 顺序解决

并行化 - 多个调查同时进行
专注性 - 每个代理范围狭窄，需要跟踪的上下文更少
独立性 - 代理互不干扰
速度 - 解决3个问题的时间相当于解决1个

审查每个摘要 - 了解更改内容
检查冲突 - 代理是否编辑了相同的代码？
运行完整套件 - 验证所有修复协同工作
抽查 - 代理可能犯系统性错误

来自调试会话（2025-10-03）：

3个文件出现6个故障
并行调度了3个代理
所有调查并发完成
所有修复成功集成
代理更改之间零冲突

🇺🇸English

Dispatching Parallel Agents

Overview

You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.

When to Use

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 when:

3+ test files failing with different root causes
Multiple subsystems broken independently
Each problem can be understood without context from others
No shared state between investigations

Don't use when:

Failures are related (fix one might fix others)
Need to understand full system state
Agents would interfere with each other

The Pattern

1. Identify Independent Domains

Group failures by what's broken:

File A tests: Tool approval flow
File B tests: Batch completion behavior
File C tests: Abort functionality

Each domain is independent - fixing tool approval doesn't affect abort tests.

2. Create Focused Agent Tasks

Each agent gets:

Specific scope: One test file or subsystem
Clear goal: Make these tests pass
Constraints: Don't change other code
Expected output: Summary of what you found and fixed

3. Dispatch in Parallel

// 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. Review and Integrate

When agents return:

Read each summary
Verify fixes don't conflict
Run full test suite
Integrate all changes

Agent Prompt Structure

Good agent prompts are:

Focused - One clear problem domain
Self-contained - All context needed to understand the problem
Specific about output - What should the agent return?

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.

Common Mistakes

❌ Too broad: "Fix all the tests" - agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope

❌ No context: "Fix the race condition" - agent doesn't know where ✅ Context: Paste the error messages and test names

❌ No constraints: Agent might refactor everything ✅ Constraints: "Do NOT change production code" or "Fix tests only"

❌ Vague output: "Fix it" - you don't know what changed ✅ Specific: "Return summary of root cause and changes"

When NOT to Use

Related failures: Fixing one might fix others - investigate together first Need full context: Understanding requires seeing entire system Exploratory debugging: You don't know what's broken yet Shared state: Agents would interfere (editing same files, using same resources)

Real Example from Session

Scenario: 6 test failures across 3 files after major refactoring

Failures:

agent-tool-abort.test.ts: 3 failures (timing issues)
batch-completion-behavior.test.ts: 2 failures (tools not executing)
tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)

Decision: Independent domains - abort logic separate from batch completion separate from race conditions

Dispatch:

Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts

Results:

Agent 1: Replaced timeouts with event-based waiting
Agent 2: Fixed event structure bug (threadId in wrong place)
Agent 3: Added wait for async tool execution to complete

Integration: All fixes independent, no conflicts, full suite green

Time saved: 3 problems solved in parallel vs sequentially

Key Benefits

Parallelization - Multiple investigations happen simultaneously
Focus - Each agent has narrow scope, less context to track
Independence - Agents don't interfere with each other
Speed - 3 problems solved in time of 1

Verification

After agents return:

Review each summary - Understand what changed
Check for conflicts - Did agents edit same code?
Run full suite - Verify all fixes work together
Spot check - Agents can make systematic errors

Real-World Impact

From debugging session (2025-10-03):

6 failures across 3 files
3 agents dispatched in parallel
All investigations completed concurrently
All fixes integrated successfully
Zero conflicts between agent changes

Weekly Installs

22.4K

Repository

obra/superpowers

GitHub Stars

107.7K

First Seen

Jan 19, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode19.0K

codex18.4K

gemini-cli18.3K

github-copilot17.3K

cursor16.8K

amp16.1K