subagent-driven-development

name	subagent-driven-development
description	当在当前会话中执行具有独立任务的实现计划时使用

Subagent-Driven Development（子代理驱动开发）

通过为每个任务派发一个全新的 implementer subagent 来执行计划，每个任务之后进行一次 task review（规范合规 + 代码质量），并在最后进行一次覆盖整个分支的 broad review。

为什么用 subagent： 你把任务委托给拥有隔离上下文的专门 agent。通过精确构建它们的指令和上下文，你确保它们保持专注并成功完成各自的任务。它们绝不应该继承你会话的上下文或历史——你精确构造它们所需的内容。这也为你自己的协调工作保留了上下文。

核心原则： 每个任务一个全新 subagent + task review（规范 + 质量）+ 最后的 broad review = 高质量、快速迭代

叙述（Narration）： 在工具调用之间，至多用一行简短叙述——ledger 和工具结果承载记录。

持续执行： 不要在任务之间暂停向你的 human partner 请示。不停顿地执行计划中的所有任务。停止的唯一理由是：你无法解决的 BLOCKED 状态、确实阻碍推进的歧义，或所有任务完成。"我是否继续？"这类提示和进度汇报是在浪费他们的时间——他们让你执行计划，那就执行。

何时使用

digraph when_to_use {
    "有实现计划？" [shape=diamond];
    "任务大多独立？" [shape=diamond];
    "留在当前会话？" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "手动执行或先 brainstorm" [shape=box];

    "有实现计划？" -> "任务大多独立？" [label="是"];
    "有实现计划？" -> "手动执行或先 brainstorm" [label="否"];
    "任务大多独立？" -> "留在当前会话？" [label="是"];
    "任务大多独立？" -> "手动执行或先 brainstorm" [label="否 - 强耦合"];
    "留在当前会话？" -> "subagent-driven-development" [label="是"];
    "留在当前会话？" -> "executing-plans" [label="否 - 并行会话"];
}

对比 Executing Plans（并行会话）：

• 同一会话（无上下文切换）
• 每个任务一个全新 subagent（无上下文污染）
• 每个任务后进行 review（规范合规 + 代码质量），最后进行 broad review
• 更快迭代（任务之间无需人工介入）

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "派发 implementer subagent（./implementer-prompt.md）" [shape=box];
        "Implementer subagent 提问？" [shape=diamond];
        "回答问题，提供上下文" [shape=box];
        "Implementer subagent 实现、测试、提交、自审" [shape=box];
        "写 diff 文件，派发 task reviewer subagent（./task-reviewer-prompt.md）" [shape=box];
        "Task reviewer 报告规范 ✅ 且质量通过？" [shape=diamond];
        "为 Critical/Important 发现派发修复 subagent" [shape=box];
        "在 todo 列表和进度 ledger 中标记任务完成" [shape=box];
    }

    "阅读计划，记录上下文和全局约束，创建 todos" [shape=box];
    "还有剩余任务？" [shape=diamond];
    "派发最终 code reviewer subagent（../requesting-code-review/code-reviewer.md）" [shape=box];
    "使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "阅读计划，记录上下文和全局约束，创建 todos" -> "派发 implementer subagent（./implementer-prompt.md）";
    "派发 implementer subagent（./implementer-prompt.md）" -> "Implementer subagent 提问？";
    "Implementer subagent 提问？" -> "回答问题，提供上下文" [label="是"];
    "回答问题，提供上下文" -> "派发 implementer subagent（./implementer-prompt.md）";
    "Implementer subagent 提问？" -> "Implementer subagent 实现、测试、提交、自审" [label="否"];
    "Implementer subagent 实现、测试、提交、自审" -> "写 diff 文件，派发 task reviewer subagent（./task-reviewer-prompt.md）";
    "写 diff 文件，派发 task reviewer subagent（./task-reviewer-prompt.md）" -> "Task reviewer 报告规范 ✅ 且质量通过？";
    "Task reviewer 报告规范 ✅ 且质量通过？" -> "为 Critical/Important 发现派发修复 subagent" [label="否"];
    "为 Critical/Important 发现派发修复 subagent" -> "写 diff 文件，派发 task reviewer subagent（./task-reviewer-prompt.md）" [label="重新 review"];
    "Task reviewer 报告规范 ✅ 且质量通过？" -> "在 todo 列表和进度 ledger 中标记任务完成" [label="是"];
    "在 todo 列表和进度 ledger 中标记任务完成" -> "还有剩余任务？";
    "还有剩余任务？" -> "派发 implementer subagent（./implementer-prompt.md）" [label="是"];
    "还有剩余任务？" -> "派发最终 code reviewer subagent（../requesting-code-review/code-reviewer.md）" [label="否"];
    "派发最终 code reviewer subagent（../requesting-code-review/code-reviewer.md）" -> "使用 superpowers:finishing-a-development-branch";
}

起飞前计划审查（Pre-Flight Plan Review）

在派发任务 1 之前，把整个计划扫一遍，找出冲突：

• 彼此矛盾、或与计划的全局约束（Global Constraints）矛盾的任务
• 计划明确要求、但被 review 评分标准视为缺陷的任何内容（一个不断言任何东西的测试、一段逐字复制的逻辑块）

把你发现的所有问题作为一个批量问题提交给你的 human partner——每个发现放在要求它的那段计划文本旁边，询问以哪个为准——在执行开始前一次性提出，而不是在计划进行中每发现一个就打断一次。如果扫描结果是干净的，无需多言直接推进。review 循环仍然是兜底，捕获那些只有在实现过程中才会浮现的冲突。

模型选择（Model Selection）

为每个角色使用能够胜任的、最不强大的模型，以节省成本并提高速度。

机械性实现任务（孤立函数、清晰规范、1-2 个文件）：使用快速、便宜的模型。当计划定义良好时，大多数实现任务都是机械的。

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

架构和设计任务：使用可用的最强大模型。最终的整分支 review 就属于这一类——用可用的最强大模型派发它，而不是会话默认模型。

审查任务：选择具有同等判断力的模型，并按 diff 的规模、复杂度和风险来缩放。一个小的机械 diff 不需要最强大的模型；一个微妙的并发改动则需要。

派发 subagent 时务必显式指定模型。 省略模型会继承你会话的模型——通常是最强大也最昂贵的——这会无声地使本节失效。

回合数胜过 token 单价。 实际耗时和上下文成本随 subagent 走了多少个回合而攀升，而最便宜的模型在多步骤工作上通常要花 2-3 倍的回合——总体成本更高。对 reviewer 以及依据散文描述工作的 implementer，用中端模型作为下限。当任务的计划文本包含了要写的完整代码时，实现工作就是誊抄加测试：对那个 implementer 使用最便宜档次。单文件机械修复也用最便宜档次。

任务复杂度信号（实现任务）：

• 触及 1-2 个文件且有完整规范 → 便宜模型
• 触及多个文件且涉及集成 → 标准模型
• 需要设计判断或广泛的代码库理解 → 最强大模型

处理 Implementer 状态

Implementer subagent 报告四种状态之一。恰当地处理每一种：

DONE： 生成 review 包（scripts/review-package BASE HEAD，从本 skill 目录运行——它会打印自己写入的唯一文件路径；BASE 是你派发 implementer 之前记录的 commit——绝不要用 HEAD~1，那会无声地丢弃多 commit 任务中除最后一个之外的所有 commit），然后带着打印出的路径派发 task reviewer。

DONE_WITH_CONCERNS： Implementer 完成了工作但标记了疑虑。在继续之前阅读这些疑虑。如果疑虑关于正确性或范围，在 review 之前解决它们。如果只是观察性备注（例如"这个文件越来越大了"），记录下来并继续 review。

NEEDS_CONTEXT： Implementer 需要未被提供的信息。提供缺失的上下文并重新派发。

BLOCKED： Implementer 无法完成任务。评估阻碍因素：

1. 如果是上下文问题，提供更多上下文并以相同模型重新派发
2. 如果任务需要更多推理，以更强大的模型重新派发
3. 如果任务太大，把它拆成更小的片段
4. 如果计划本身是错的，上报给 human

绝不无视一个上报，或在没有任何改变的情况下强制同一模型重试。如果 implementer 说它卡住了，那就一定有东西需要改变。

处理 Reviewer 的 ⚠️ 项

Task reviewer 可能报告 "⚠️ Cannot verify from diff"（无法从 diff 验证）项——即位于未改动代码中、或跨越多个任务的需求。这些不会阻塞 review 的其余部分，但你必须在标记任务完成之前，自己逐一解决它们：你掌握 reviewer 所缺乏的计划和跨任务上下文。如果你确认某一项确实是缺口，把它当作一次失败的规范 review 处理——退回给 implementer 并重新 review。

构建 Reviewer Prompt

每个任务的 review 是任务范围的关卡。broad review 只发生一次，在最终的整分支 review 时。当你填写 reviewer 模板时：

• 不要在没有具体、特定于任务的理由时，添加诸如"检查所有用法"或"如果有用就跑竞态测试"这类开放式指令
• 不要要求 reviewer 重新运行 implementer 已经在相同代码上跑过的测试——implementer 的报告承载测试证据
• 不要替 reviewer 预判发现——绝不指示 reviewer 忽略或不标记某个具体问题。如果你认为某个发现会是误报，让 reviewer 提出它，并在 review 循环中裁决。如果你正在写的 prompt 里包含"不要标记"、"不要把 X 当缺陷"、"最多 Minor"、"计划选择了"——停下：你在预判，通常是为了让自己省掉一轮 review。
• 你交给 reviewer 的全局约束块是它的注意力透镜。从计划的 Global Constraints 小节或规范中逐字复制绑定要求：精确的值、精确的格式，以及组件之间陈述的关系（"与 X 相同的布局"、"匹配 Y"）。reviewer 的模板已经承载了流程规则（YAGNI、测试卫生、review 方法）——约束块是给 THIS 项目的规范所要求的内容。
• 把它的 diff 作为文件交给 reviewer：运行本 skill 的 scripts/review-package BASE HEAD，把它打印出的文件路径传给 reviewer（或者，在没有 bash 的情况下：对该范围运行 git log --oneline、git diff --stat 和 git diff -U10，重定向到一个唯一命名的文件）。输出绝不进入你自己的上下文，而 reviewer 一次 Read 就能看到 commit 列表、stat 摘要和带上下文的完整 diff。使用你在派发 implementer 之前记录的 BASE——绝不要用 HEAD~1，那会无声地截断多 commit 任务。
• 一次派发 prompt 描述一个任务，而不是会话的历史。不要把累积的过往任务摘要（"任务 1-3 之后的状态"）粘贴进后续派发——一个真实会话的派发达到了 42k 字符，其中 99% 是粘贴的历史。一个全新的 subagent 需要的是它的任务、它触及的接口，以及全局约束。仅此而已。
• 为 Critical 和 Important 发现派发修复 subagent。Minor 发现则边走边记入进度 ledger，并把最终的整分支 review 指向那个列表，让它能分诊哪些必须在合并前修复。一份没人读的汇总就是无声的丢弃。
• 一个被标记为 plan-mandated（计划要求）的发现——或任何与计划文本要求相冲突的发现——是 human 的决定，就像任何计划矛盾一样：把发现和计划文本一并呈现，询问以哪个为准。不要因为计划要求它就驳回发现，也不要在未询问的情况下派发一个与计划相矛盾的修复。
• 最终的整分支 review 也会得到一个包：运行 scripts/review-package MERGE_BASE HEAD（MERGE_BASE = 分支起始的 commit，例如 git merge-base main HEAD），并在最终 review 派发中包含打印出的路径，这样最终 reviewer 读一个文件即可，而不用用 git 命令重新推导分支 diff。
• 每次修复派发都携带 implementer 契约：修复 subagent 重新运行覆盖其改动的测试并报告结果。在派发中指明覆盖测试文件的名称——一行修复不需要整个测试套件。在重新派发 reviewer 之前，确认修复报告包含覆盖测试、运行的命令和输出；三者齐全后再派发重新 review。
• 如果最终整分支 review 返回了发现，派发一个带有完整发现列表的修复 subagent——而不是每个发现一个修复者。每个发现一个修复者各自重建上下文并重跑套件；一个真实会话的最终 review 修复波次，花费超过了它所有任务的总和。

文件交接（File Handoffs）

你粘贴进派发 prompt 的一切——以及 subagent 打印回来的一切——都会在会话剩余时间里常驻你的上下文，并在之后每一轮被重新读取。把产物作为文件交接：

• 任务简报（Task brief）： 在派发 implementer 之前，运行本 skill 的 scripts/task-brief PLAN_FILE N——它把任务的完整文本提取到一个唯一命名的文件并打印路径。组织派发内容，让简报保持为需求的唯一来源。你的派发应包含：(1) 一句话说明这个任务在项目中处于什么位置；(2) 简报路径，以"先读这个——它是你的需求，包含要逐字使用的精确值"引入；(3) 简报无法知晓的、来自更早任务的接口和决定；(4) 你在简报中注意到的任何歧义的解决方案；(5) 报告文件路径和报告契约。精确值（数字、魔法字符串、签名、测试用例）只出现在简报中。
• 报告文件（Report file）： 用简报的命名方式命名 implementer 的报告文件（简报 …/task-N-brief.md → 报告 …/task-N-report.md），并把它放入派发 prompt。Implementer 在那里写入完整报告，只返回状态、commits、一行测试摘要和疑虑。
• Reviewer 输入： task reviewer 得到三个路径——同一个简报文件、报告文件和 review 包——加上绑定该任务的全局约束。
• 修复派发把它们的修复报告（含测试结果）追加到同一个报告文件，并返回简短摘要；重新 review 读取更新后的文件。

持久化进度（Durable Progress）

对话记忆无法在压缩（compaction）后存活。在真实会话中，丢失了进度的 controller 曾重新派发整个已完成的任务序列——这是观察到的最昂贵的失败。把进度追踪在 ledger 文件里，而不仅仅在 todos 中。

• 在 skill 开始时，检查是否存在 ledger：cat "$(git rev-parse --show-toplevel)/.superpowers/sdd/progress.md"。那里标记为完成的任务是 DONE——不要重新派发它们；在第一个未标记完成的任务处恢复。
• 当一个任务的 review 回来是干净的，在与你其他记账工作相同的消息里，向 ledger 追加一行：Task N: complete (commits <base7>..<head7>, review clean)。
• ledger 是你的恢复地图：它点名的 commits 存在于 git 中，即使你的上下文已不记得创建过它们。在压缩之后，信任 ledger 和 git log，胜过你自己的回忆。
• git clean -fdx 会销毁 ledger（它是 git 忽略的临时文件）；如果发生这种情况，从 git log 恢复。

Prompt 模板

• implementer-prompt.md - 派发 implementer subagent
• task-reviewer-prompt.md - 派发 task reviewer subagent（规范合规 + 代码质量）
• 最终的整分支 review：使用 superpowers:requesting-code-review 的 code-reviewer.md

示例工作流

你：我正在使用 Subagent-Driven Development 来执行这个计划。

[读取计划文件一次：docs/superpowers/plans/feature-plan.md]
[为所有任务创建 todos]

任务 1：Hook 安装脚本

[为任务 1 运行 task-brief；带着简报 + 报告路径 + 上下文派发 implementer]

Implementer："开始之前——hook 应该安装在用户级还是系统级？"

你："用户级（~/.config/superpowers/hooks/）"

Implementer："明白。开始实现..."
[稍后] Implementer：
  - 实现了 install-hook 命令
  - 添加了测试，5/5 通过
  - 自审：发现漏了 --force 标志，已补上
  - 已提交

[运行 review-package，带着打印出的路径派发 task reviewer]
Task reviewer：规范 ✅ - 所有需求都满足，没有多余。
  优点：测试覆盖好，干净。问题：无。任务质量：通过。

[标记任务 1 完成]

任务 2：恢复模式

[为任务 2 运行 task-brief；带着简报 + 报告路径 + 上下文派发 implementer]

Implementer：[没有问题，继续]
Implementer：
  - 添加了 verify/repair 模式
  - 8/8 测试通过
  - 自审：一切良好
  - 已提交

[运行 review-package，带着打印出的路径派发 task reviewer]
Task reviewer：规范 ❌：
  - 缺失：进度报告（规范说"每 100 项报告一次"）
  - 多余：添加了 --json 标志（未被要求）
  问题（Important）：魔法数字（100）

[带着所有发现派发修复 subagent]
Fixer：移除了 --json 标志，添加了进度报告，提取了 PROGRESS_INTERVAL 常量

[Task reviewer 再次 review]
Task reviewer：规范 ✅。任务质量：通过。

[标记任务 2 完成]

...

[所有任务之后]
[派发最终 code-reviewer]
最终 reviewer：所有需求都满足，可以合并

完成！

优势

对比手动执行：

• Subagent 自然遵循 TDD
• 每个任务全新上下文（无混淆）
• 并行安全（subagent 互不干扰）
• Subagent 可以提问（工作前和工作期间都可以）

对比 Executing Plans：

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

效率提升：

• Controller 精确筛选所需的上下文；大批量产物以文件形式流动，而非粘贴的文本
• Subagent 预先获得完整信息
• 问题在工作开始前（而非之后）浮现

质量关卡：

• 自审在交接前捕获问题
• Task review 携带两个裁决：规范合规和代码质量
• review 循环确保修复真正生效
• 规范合规防止过度/不足构建
• 代码质量确保实现构建良好

成本：

• 更多 subagent 调用（每个任务 implementer + reviewer）
• Controller 做更多准备工作（预先提取所有任务）
• review 循环增加迭代
• 但早早捕获问题（比之后调试更便宜）

危险信号（Red Flags）

绝不：

• 在没有用户明确同意的情况下，在 main/master 分支上开始实现
• 跳过 task review，或接受缺少任一裁决的报告（规范合规和任务质量两者都是必需的）
• 带着未修复的问题继续
• 并行派发多个实现 subagent（会冲突）
• 让 subagent 读取整个计划文件（改交给它任务简报——scripts/task-brief）
• 跳过背景设定上下文（subagent 需要理解任务所处的位置）
• 忽略 subagent 的问题（让它们继续之前先回答）
• 在规范合规上接受"差不多就行"（reviewer 发现了规范问题 = 未完成）
• 跳过 review 循环（reviewer 发现问题 = implementer 修复 = 再次 review）
• 让 implementer 的自审取代真正的 review（两者都需要）
• 告诉 reviewer 不要标记什么，或在派发 prompt 中预判某个发现的严重度（"最多当作 Minor"）——计划的示例代码是起点，不是它的弱点是被选定的证据
• 在没有 diff 文件的情况下派发 task reviewer——先生成它（scripts/review-package BASE HEAD），并在 prompt 中指明打印出的路径
• 在 review 还有未解决的 Critical/Important 问题时进入下一个任务
• 重新派发进度 ledger 已标记为完成的任务——在任何压缩或恢复之后检查 ledger（以及 git log）

如果 subagent 提问：

• 清晰完整地回答
• 如有需要提供额外上下文
• 不要催促它们进入实现

如果 reviewer 发现问题：

• Implementer（同一个 subagent）修复它们
• Reviewer 再次 review
• 重复直到通过
• 不要跳过重新 review

如果 subagent 任务失败：

• 派发带有具体指令的修复 subagent
• 不要尝试手动修复（会污染上下文）

集成

必需的工作流 skills：

• superpowers:using-git-worktrees - 确保隔离工作区（创建一个或验证已存在）
• superpowers:writing-plans - 创建本 skill 执行的计划
• superpowers:requesting-code-review - 用于最终整分支 review 的代码审查模板
• superpowers:finishing-a-development-branch - 在所有任务之后完成开发

Subagent 应使用：

• superpowers:test-driven-development - Subagent 为每个任务遵循 TDD

替代工作流：

• superpowers:executing-plans - 用于并行会话，而非同会话执行