subagent-driven-development

子 Agent 驱动的开发

执行计划时，如果客户端支持，应为每项任务分派一个全新的子 Agent 或并行工作者，并在每项任务完成后进行两阶段审查：先检查是否符合规范，再检查代码质量。如果客户端不支持工作者功能，则使用 executing-plans，依次完成任务和审查。

**为什么使用子 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 the task list" [shape=box];
    }

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

    "Read plan, extract all tasks with full text, note context, create task list" -> "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 the task list" [label="yes"];
    "Mark task complete in the task list" -> "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 superjawn: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 a task-list or plan item for every task]

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 在交还任务前会逐项验证
• 每项任务都有全新的上下文（不会混淆）
• 支持安全并行（子 Agent 之间不会相互干扰）
• 子 Agent 可以提问（开始工作之前和工作期间均可）

与执行计划相比：

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

效率提升：

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

质量门槛：

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

成本：

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

危险信号

绝不：

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

如果子 Agent 提出问题：

• 清晰、完整地作答
• 必要时提供额外上下文
• 不要催促他们开始实现

如果审查者发现问题：

• 由实现者（同一个子 Agent）修复
• 审查者再次审查
• 重复此流程，直到获得批准
• 不要跳过复审

如果子 Agent 未能完成任务：

• 派发修复子 Agent，并给出具体指示
• 不要尝试手动修复（会污染上下文）

集成

必需的工作流技能：

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

子 Agent 应使用：

• superjawn:verification-before-completion —— 子 Agent 在报告任务完成前，证明每项任务都能正常运行

替代工作流：

• superjawn:executing-plans —— 使用并行会话，而不是在同一会话中执行