subagent-driven-development

子 Agent 驱动的开发

通过为每项任务派发一个全新的子 Agent 来执行计划，并在每项任务完成后进行两阶段审查：先审查规范合规性，再审查代码质量。

**为何使用子 Agent：**你可以将任务委派给拥有独立上下文的专用 Agent。通过精心编写指令并提供恰当的上下文，你可以确保它们专注于任务并顺利完成。它们绝不应继承你当前会话的上下文或历史记录——你应准确构建它们所需的信息。这样也能保留你自己的上下文，用于协调工作。

**核心原则：**每项任务使用全新的子 Agent + 两阶段审查（先审查规范，再审查质量）= 高质量、快速迭代

适用场景

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

与执行计划（并行会话）的对比：

• 同一会话（无需切换上下文）
• 每项任务使用全新的子 Agent（不会污染上下文）
• 每项任务完成后进行两阶段审查：先审查规范合规性，再审查代码质量
• 迭代更快（任务之间无需人工介入）

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers-ruby:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers-ruby:finishing-a-development-branch";
}

模型选择

为节省成本并提高速度，针对每种角色使用能够胜任的最低能力模型。

机械式实现任务（独立函数、规范明确、涉及 1-2 个文件）：使用快速、低成本的模型。计划规范明确时，大多数实现任务都属于机械式任务。

集成与判断任务（涉及多个文件的协调、模式匹配、调试）：使用标准模型。

架构、设计和审查任务：使用当前可用的能力最强模型。

任务复杂度判断信号：

• 涉及 1-2 个文件，且规范完整 → 低成本模型
• 涉及多个文件，且存在集成方面的考量 → 标准模型
• 需要设计判断或广泛理解代码库 → 能力最强的模型

处理实现者状态

实现者子 Agent 会报告以下四种状态之一。请妥善处理：

**DONE：**继续进行规范合规性审查。

**DONE_WITH_CONCERNS：**实现者已完成工作，但指出了疑虑。继续之前，请先阅读这些疑虑。如果疑虑涉及正确性或范围，应在审查前解决。如果只是观察意见（例如“这个文件越来越大”），请记录下来并继续审查。

**NEEDS_CONTEXT：**实现者需要尚未提供的信息。补充缺失的上下文，然后重新派发任务。

**BLOCKED：**实现者无法完成任务。评估阻塞原因：

1. 如果是上下文问题，补充更多上下文，并使用相同模型重新派发
2. 如果任务需要更深入的推理，使用能力更强的模型重新派发
3. 如果任务过大，将其拆分成更小的部分
4. 如果计划本身有误，提交给人工处理

切勿忽略升级请求，或在不做任何调整的情况下要求同一模型重试。如果实现者表示陷入困境，就需要做出改变。

提示词模板

• ./implementer-prompt.md - 派发实现者子 Agent
• ./spec-reviewer-prompt.md - 派发规范合规性审查者子 Agent
• ./code-quality-reviewer-prompt.md - 派发代码质量审查者子 Agent

工作流示例

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

[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: ✅ Approved

[Mark Task 2 complete]

...

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

Done!

优势

与手动执行相比：

• 子 Agent 会自然地遵循 TDD
• 每项任务使用全新的上下文（避免混淆）
• 可安全并行执行（子 Agent 之间不会相互干扰）
• 子 Agent 可以提问（工作开始前和进行中都可以）

与执行计划相比：

• 在同一会话中完成（无需交接）
• 持续推进（无需等待）
• 自动设置审核检查点

效率提升：

• 无需承担读取文件的开销（控制器会提供完整文本）
• 控制器会精准筛选所需上下文
• 子 Agent 一开始就能获取完整信息
• 在工作开始前就会提出问题（而不是之后）

质量关卡：

• 自我审查可在交接前发现问题
• 两阶段审查：先检查规范符合性，再检查代码质量
• 审查循环可确保修复确实有效
• 规范符合性可避免过度构建或构建不足
• 代码质量可确保实现完善

成本：

• 调用子 Agent 的次数更多（每项任务需要实现者和 2 位审查者）
• 控制器需要做更多准备工作（提前提取所有任务）
• 审查循环会增加迭代次数
• 但能及早发现问题（比之后调试更省成本）

危险信号

切勿：

• 未经用户明确同意，就在 main/master 分支上开始实现
• 跳过审查（规范符合性或代码质量）
• 带着未修复的问题继续推进
• 并行派遣多个实现子 Agent（会产生冲突）
• 让子 Agent 读取计划文件（应直接提供完整文本）
• 跳过背景说明（子 Agent 需要了解任务在整体中的位置）
• 忽略子 Agent 的问题（让其继续之前应先作答）
• 对规范符合性采取“差不多就行”的态度（规范审查者发现问题 = 尚未完成）
• 跳过审查循环（审查者发现问题 = 实现者修复 = 再次审查）
• 让实现者的自我审查取代实际审查（两者都不可或缺）
• 在规范符合性尚未 ✅ 之前就开始代码质量审查（顺序错误）
• 在任一审查仍有未解决问题时转到下一项任务

如果子 Agent 提问：

• 清晰、完整地作答
• 必要时提供额外背景信息
• 不要催促其开始实现

如果审查者发现问题：

• 由实现者（同一个子 Agent）修复
• 审查者再次审查
• 重复上述过程，直到通过
• 不要跳过再次审查

如果子 Agent 未能完成任务：

• 派遣修复子 Agent，并提供具体说明
• 不要尝试手动修复（会污染上下文）

集成

必需的工作流技能：

• superpowers-ruby:using-git-worktrees - 必需：开始前设置隔离工作区
• superpowers-ruby:writing-plans - 创建此技能要执行的计划
• superpowers-ruby:requesting-code-review - 为审查者子 Agent 提供代码审查模板
• superpowers-ruby:finishing-a-development-branch - 完成所有任务后的开发收尾工作

子 Agent 应使用：

• superpowers-ruby:test-driven-development - 子 Agent 为每项任务遵循 TDD

替代工作流：

• superpowers-ruby:executing-plans - 使用并行会话，而非在同一会话中执行