subagent-driven-development

子 Agent 驱动开发

通过为每项任务或问题派遣新的子 Agent 来创建并执行计划，并在每项任务或每批任务后审查代码和输出。

核心原则： 每项任务都使用新的子 Agent + 在任务之间或之后进行审查 = 高质量、快速迭代。

通过 Agent 执行计划：

• 在同一会话中执行（无需切换上下文）
• 每项任务都使用新的子 Agent（避免上下文污染）
• 在每项任务或每批任务后进行代码审查（及早发现问题）
• 更快迭代（任务之间无需人工介入）

支持的执行类型

顺序执行

当多个任务或问题彼此相关且需要按顺序执行时，按顺序调查或修改是最佳做法。

为每项任务或问题派遣一个 Agent，让其按顺序处理。在每项任务或问题后审查输出和代码。

适用场景：

• 任务紧密耦合
• 任务需要按顺序执行

并行执行

当有多个互不相关的任务或问题（涉及不同文件、不同子系统、不同 Bug）时，按顺序调查或修改会浪费时间。每项任务或调查都是独立的，可以并行进行。

为每个独立的问题领域派遣一个 Agent，让它们并行工作。

适用场景：

• 任务大多相互独立
• 所有任务完成后可以统一审查

顺序执行流程

1. 加载计划

读取计划文件，并使用 TodoWrite 创建包含所有任务的待办事项列表。

2. 使用子 Agent 执行任务

对于每项任务：

派遣新的子 Agent：

Task tool (general-purpose):
  description: "Implement Task N: [task name]"
  prompt: |
    You are implementing Task N from [plan-file].

    Read that task carefully. Your job is to:
    1. Implement exactly what the task specifies
    2. Write tests (following TDD if task says to)
    3. Verify implementation works
    4. Commit your work
    5. Report back

    Work from: [directory]

    Report: What you implemented, what you tested, test results, files changed, any issues

子 Agent 返回工作摘要。

3. 审查子 Agent 的工作

派遣代码审查子 Agent：

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from subagent's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

代码审查者返回： 优势、问题（严重／重要／轻微）、评估

4. 应用审查反馈

如果发现问题：

• 立即修复严重问题
• 在开始下一项任务前修复重要问题
• 记录轻微问题

必要时派遣后续子 Agent：

"Fix issues from code review: [list issues]"

5. 标记完成并处理下一项任务

• 在 TodoWrite 中将任务标记为已完成
• 转到下一项任务
• 重复步骤 2～5

6. 最终审查

所有任务完成后，派遣最终代码审查者：

• 审查整个实现
• 检查是否满足所有计划要求
• 验证整体架构

7. 完成开发

最终审查通过后：

• 宣布：“我将使用 finishing-a-development-branch 技能来完成这项工作。”
• 必需的子技能： 使用 superpowers:finishing-a-development-branch
• 按照该技能的指引验证测试、提供选项并执行所选操作

工作流示例

You: I'm using Subagent-Driven Development to execute this plan.

[Load plan, create TodoWrite]

Task 1: Hook installation script

[Dispatch implementation subagent]
Subagent: Implemented install-hook with tests, 5/5 passing

[Get git SHAs, dispatch code-reviewer]
Reviewer: Strengths: Good test coverage. Issues: None. Ready.

[Mark Task 1 complete]

Task 2: Recovery modes

[Dispatch implementation subagent]
Subagent: Added verify/repair, 8/8 tests passing

[Dispatch code-reviewer]
Reviewer: Strengths: Solid. Issues (Important): Missing progress reporting

[Dispatch fix subagent]
Fix subagent: Added progress every 100 conversations

[Verify fix, mark Task 2 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!

危险信号

切勿：

• 跳过任务之间的代码审查
• 在严重问题尚未修复时继续
• 并行派遣多个实现子 Agent（会产生冲突）
• 不读取计划任务就开始实现

如果子 Agent 未能完成任务：

• 派遣修复子 Agent，并提供具体指示
• 不要尝试手动修复（避免上下文污染）

并行执行流程

加载计划，认真审查，分批执行任务，并在每批任务之间提交报告供审查。

核心原则： 分批执行，并设置检查点供架构师审查。

开始时宣布：“我将使用 executing-plans 技能来实施此计划。”

步骤 1：加载并审查计划

1. 读取计划文件
2. 认真审查，找出对计划的疑问或顾虑
3. 如果有顾虑：开始前向你的协作伙伴提出
4. 如果没有顾虑：使用 TodoWrite 创建待办事项列表并继续

步骤 2：执行一批任务

默认：前 3 项任务

对于每项任务：

1. 将状态标记为 in_progress
2. 严格遵循每个步骤（计划包含细化的小步骤）
3. 按要求运行验证
4. 将状态标记为已完成

步骤 3：报告

批次完成后：

• 展示已实现的内容
• 展示验证输出
• 说明：“已准备好接受反馈。”

步骤 4：继续

根据反馈：

• 如有需要，应用修改
• 执行下一批任务
• 重复以上步骤，直到全部完成

第 5 步：完成开发

所有任务完成并验证后：

• 宣布：“我正在使用 finishing-a-development-branch 技能来完成这项工作。”
• 必需的子技能： 使用 superpowers:finishing-a-development-branch
• 按照该技能验证测试、提供选项并执行选择

何时停止并寻求帮助

出现以下情况时，立即停止执行：

• 批次执行中遇到阻碍（缺少依赖项、测试失败、指令不明确）
• 计划存在关键缺陷，导致无法开始
• 你不理解某条指令
• 验证反复失败

请寻求澄清，不要猜测。

何时重新审视前面的步骤

以下情况返回“审查”（第 1 步）：

• 合作者根据你的反馈更新了计划
• 需要重新思考根本方案

不要强行绕过阻碍——停下来寻求帮助。

请记住

• 先批判性地审查计划
• 严格按照计划步骤执行
• 不要跳过验证
• 计划要求时，参考相关技能
• 批次之间：只汇报并等待
• 遇到阻碍时停止，不要猜测

并行调查流程

这是并行执行的一种特殊情况，适用于存在多个互不相关、可在没有共享状态或依赖项的情况下调查的问题。

1. 找出独立领域

按问题所在分组：

• 文件 A 测试：工具批准流程
• 文件 B 测试：批次完成行为
• 文件 C 测试：中止功能

这些领域互相独立——修复工具批准不会影响中止测试。

2. 创建范围明确的 Agent 任务

每个 Agent 都应获得：

• 具体范围： 一个测试文件或子系统
• 明确目标： 让这些测试通过
• 限制条件： 不要更改其他代码
• 预期输出： 总结发现和修复内容

3. 并行分派

// 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. 审查并整合

Agent 返回后：

• 阅读每份总结
• 验证修复之间没有冲突
• 运行完整测试套件
• 整合所有更改

Agent 提示词结构

优秀的 Agent 提示词应当：

1. 范围明确——只有一个清晰的问题领域
2. 内容完整——包含理解问题所需的全部上下文
3. 明确输出要求——说明 Agent 应返回什么

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 会不知所措
✅ 具体明确：“修复 agent-tool-abort.test.ts”——范围清晰

❌ 没有上下文：“修复竞态条件”——Agent 不知道问题出在哪里
**✅ 提供上下文：**粘贴错误消息和测试名称

**❌ 没有限制条件：**Agent 可能会重构所有内容
✅ 明确限制：“不要更改生产代码”或“只修复测试”

❌ 输出要求含糊：“修好它”——你不知道发生了什么更改
✅ 明确具体：“返回根本原因和更改内容的总结”

不适用的情况

问题相关： 修复一个问题可能会解决其他问题——先一起调查
需要完整上下文： 理解问题需要查看整个系统
探索性调试： 你还不知道问题出在哪里
存在共享状态： Agent 之间会互相干扰（编辑同一文件、使用相同资源）

会话中的真实示例

场景： 大规模重构后，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

结果：

• Agent 1：用基于事件的等待替换超时
• Agent 2：修复事件结构错误（threadId 放错位置）
• Agent 3：添加等待，确保异步工具执行完成

整合： 所有修复互相独立，没有冲突，完整测试套件全部通过

节省时间： 并行解决 3 个问题，而不是依次解决

#验证

Agent 返回后：

1. 审查每份摘要 - 了解发生了哪些更改
2. 检查冲突 - Agent 是否编辑了相同的代码？
3. 运行完整测试套件 - 验证所有修复能否协同工作
4. 抽查 - Agent 可能会造成系统性错误