subagent-driven-development

subagent-driven-development 技能概览

subagent-driven-development 实际做什么

subagent-driven-development 是一种执行实现计划的工作流：把工作拆成彼此独立的任务，将每个任务交给一个全新的 subagent，并对每个结果进行两轮审查：先看是否符合 spec，再看代码质量。它真正的价值不在于“用更多 agent”，而在于有意识地隔离上下文，让每个执行者只拿到完成该任务所需的任务说明、要求和局部代码上下文。

这个技能最适合什么场景

如果你已经有了一份计划，现在需要在当前会话里把它稳定地落成实现，那么这个 subagent-driven-development skill 会很合适。尤其适用于以下情况：

• 任务之间大多相互独立
• 你希望 coordinator agent 专注于编排和调度
• 你在意既要发现需求跑偏，也要发现代码写得草率
• 你需要的是可重复执行的 review 闭环，而不是一次性的 coding prompt

要解决的核心问题

用户采用 subagent-driven-development for Agent Orchestration，通常是因为常规的“按这个计划实现”提示词开始反复暴露出一些典型问题：agent 会把多个任务混在一起做、忘记约束、过度实现，或者产出看上去像那么回事、实际上却没对上 spec 的代码。这个技能提供了一套纪律化的交接与审查模式，用来减少这些失误。

它和普通 prompt 的区别在哪里

它的关键差异都非常务实：

• 每个任务都用一个全新的 subagent，而不是让一个长时间运行的 agent 背着一堆噪声历史继续做
• 显式的任务包（task packet），会把完整任务文本直接贴进去，而不是让执行者自己从零散文件里推断需求
• 编码前必须先提问，让不明确的要求尽早暴露
• 两阶段 review，把“有没有按 spec 实现”与“代码写得好不好”明确分开

这种拆分很重要。很多团队会先看代码质量，再确认范围是否正确，结果就是过度实现或实现不足反而更难被识别出来。

什么情况下不该用它

如果你还没有一份具体可执行的实现计划、任务之间高度耦合，或者这项工作本来就更适合放到另一个并行执行流里，而不是放在当前会话中，那就不要一上来使用 subagent-driven-development。这类情况下，通常应该先做规划，或者先选另一种执行类技能。

如何使用 subagent-driven-development 技能

安装 subagent-driven-development 技能

如果你通过 Skills CLI 从这个仓库安装技能，可以使用：

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

安装后，第一次运行前先打开这个 skill 本体和配套的 prompt 模板文件。

先读这几个文件

为了更快上手，建议按这个顺序阅读：

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

这个顺序能让你先理解工作流，再看到 implementer 以及两轮 review 的 prompt 具体长什么样。

开始前先理解调用模式

在实际使用中，subagent-driven-development usage 不是一个神奇的单条命令。你需要以 coordinator 的身份来驱动流程：

1. 从计划里取出一个任务
2. 给一个全新的 implementer subagent 派发一个范围明确的 prompt
3. 要求它回报结果
4. 让 spec reviewer 基于实际代码做检查
5. 只有 spec 通过后，才运行 code quality reviewer
6. 决定接受、修改，或者重新派发

如果你跳过这些 review 关卡，那其实就已经不是按这个技能原本的设计在用了。

这个技能需要什么输入

在派发任何 subagent 之前，先准备好这些输入：

• 计划中的准确任务文本
• 验收标准或需求
• 相关的架构上下文
• 工作目录或 repo 范围
• 任何依赖关系或执行顺序说明
• 用于 review diff 的基线 commit 或 SHA
• 用于追踪的任务编号和任务名称

从原始模板能明显看出来：你应该把完整任务内容贴进 prompt，而不是让 subagent “自己去看 plan 文件”。

把模糊目标改写成强 implementer prompt

一个弱 prompt 往往只是这样：

• “Implement task 4 from the plan.”

而一个更强的 subagent-driven-development guide 型 prompt 通常会包含：

• 任务标题和编号
• 完整任务文本
• 这个任务存在的原因
• 应该在 repo 的哪个位置工作
• 文件结构上的约束
• 是否要求测试
• 如果必须做假设该怎么办
• 编码前必须先提问的要求

之所以重要，是因为这个技能建立在受控上下文之上，而不是让 agent 自主地对整个 repo 做大范围解读。

更好的任务包示例

给 implementer 派发任务时，可以使用类似这样的结构：

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

这比让执行者自己大范围探索更可靠，因为这个技能默认 coordinator 要对“任务打包是否到位”负责。

为什么要先做 spec review 再做质量 review

这是你在评估 subagent-driven-development install 时最值得关注的高价值设计点之一：这个顺序不是随意的，而是刻意安排的。

先运行 spec reviewer，是为了回答：

• 代码有没有实现被要求的内容？
• 有没有漏掉要求？
• 有没有加上未被要求的内容？
• 有没有误解任务？

只有确认这些都没问题之后，才应该让 code quality reviewer 去检查可维护性、拆分方式、文件职责和改动形态。如果顺序反过来，外表“写得不错”的代码很容易掩盖范围错误。

如何用好 spec reviewer

spec-reviewer-prompt.md 这个模板的风格非常直接：它明确要求 reviewer 不要相信 implementer 的自述，而是要逐行对照真实代码进行核验。你在改写这个模板时，应该保留这种语气。reviewer 需要拿到：

• 完整任务要求
• implementer 声称自己完成了什么
• 对变更代码的访问能力

重点是独立验证，不是礼貌性确认。

如何用好 code quality reviewer

这里的代码质量 review 不是泛泛的代码风格检查。在这个技能里，它更强调：

• 每个文件只有一个清晰职责
• 接口定义明确
• 能拆成易于理解的单元
• 是否符合计划中的文件结构
• 这个任务是否新建了过大的文件，或把已有文件继续膨胀得过头

最后一点尤其有用，因为 subagent 很容易为了“把任务做完”，把太多东西硬塞进一次改动里。

在真实 repo 中推荐的工作流

一个实用的 subagent-driven-development usage 闭环通常是这样：

1. 选出下一个独立任务
2. 记录当前 commit 作为 baseline
3. 把完整任务文本派发给 implementer
4. 收集它的结果摘要和修改过的文件
5. 对照需求和代码做 spec review
6. 如果 spec 不通过，把具体缺口返回给 implementer
7. 如果 spec 通过，再做 code quality review
8. 如果质量不过关，要求有针对性的修改
9. 合并，或继续下一个任务

这样 coordinator 始终掌握着任务排序和验收标准。

会影响输出质量的约束条件

这个技能在你尊重其边界时效果最好：

• 独立任务比纠缠在一起的任务更适合
• 明确写出的要求比让 agent 自行推断更好
• 明确限定 repo 范围，比“自己看看再决定”更好
• 短小的任务循环，比大批量多功能打包更好
• 清晰的升级/求助规则，比沉默猜测更好

如果你发现某个 subagent 必须横跨整个代码库去协调很多变化中的因素，那这个任务大概率已经太宽，不适合这个工作流。

常见的采用误区

最大的误区，就是把 subagent-driven-development skill 只当成一个标签来贴，但 prompt 还是写得很松散。这个工作流只有在你认真打包上下文并且严格执行 review 顺序时才真正有价值。否则你得到的只会是编排成本，却得不到质量提升。

subagent-driven-development 技能 FAQ

subagent-driven-development 适合新手吗？

适合，前提是你已经知道自己要构建什么任务。这个工作流足够明确，附带的 prompt 模板也能减少拍脑袋猜写法的情况。但它不能代替规划。对于还没有清晰实现计划的新手来说，这个技能可能并不好上手，因为它默认任务定义已经存在了。

什么情况下不该使用 subagent-driven-development？

以下情况建议跳过 subagent-driven-development：

• 你还在探索问题本身
• 任务之间深度互相依赖
• 需求还不稳定
• 需要一个人类或一个 agent 持续地对整个系统进行通盘推理

它是一种执行模式，不是一种探索模式。

它和“直接让一个 agent 把所有代码都写完”有什么不同？

单个超长 prompt 往往会把规划、实现、验证和 review 全塞进同一个上下文窗口里。这个技能把这些角色拆开了。这样通常能提升专注度，更容易发现需求漂移，也能把 coordinator 的上下文保留给编排，而不是被代码生成过程挤满。

这个技能需要特殊工具吗？

不需要。这个 skill 文件夹里没有额外打包什么特殊脚本。仓库提供的是 markdown prompt 模板，而不是自动化代码。只要你的环境支持派发 subagent、执行代码 review 任务，就可以用这套模式。

subagent-driven-development 只适合大型项目吗？

不是。小改动同样可以用，但当计划里包含多个独立任务，而且漏需求的代价高到值得为 review 多付出一点成本时，它的价值会更明显。

安装前最值得关注哪些仓库证据？

对于这个技能，最关键的证据就是 SKILL.md 和那三个 prompt 模板所体现出的工作流设计。这里没有什么 helper script 或 resource folder 在背后做隐性工作，所以你的安装决策应该重点看：这种 prompt 结构和 review 纪律，是否与你当前交付代码的方式匹配。

如何改进 subagent-driven-development 技能

改进 subagent-driven-development 的关键：给更好的任务包，而不是更长的 prompt

如果你想提升 subagent-driven-development skill 的效果，应该提升精度，而不是单纯增加字数。最有用的补充信息包括：

• 准确的验收标准
• 明确的非目标
• 只与当前任务相关的架构说明
• 文件或目录边界
• 预期行为的示例
• 测试要求

这样既能让 implementer 更聚焦，也能帮助 spec reviewer 更容易识别偏离。

让任务边界更锋利

很多失败并不是实现能力不够，而是任务切分太差。如果一个 subagent 必须同时协调多个变动因素、拍板架构、还要自己推断需求，那就应该继续拆任务。更好的任务应该窄到足以让“是否完全按要求实现”变得容易验证。

保留“先提问再动手”这一步

implementer 模板明确要求执行者在开始前先提问，如果实现过程中又出现意外，也要再次提问。不要把这一步删掉。压制澄清请求，看起来会更快，但输出会更不可靠，这恰恰违背了这个技能存在的意义。

用更强的对比输入提升 review 质量

对于 spec reviewer，建议提供：

• 完整需求文本
• implementer 报告
• 变更文件或 diff 范围
• 任何明确排除项

对于 code quality reviewer，建议提供：

• BASE_SHA
• HEAD_SHA
• 任务摘要
• 相关 plan 章节

这些具体的对比锚点，能让 review 不只是“凭印象给意见”。

留意这些常见失败模式

subagent-driven-development for Agent Orchestration 最常见的问题包括：

• implementer 擅自推断并加做额外功能
• 任务包漏掉关键约束
• reviewer 过度相信 implementer 的摘要
• 在 spec review 之前就先做了 code quality review
• 任务太大，无法清晰验证
• 文件不断膨胀却没人管

这些问题都可以通过更好的任务打包和更严格的 gatekeeping 来避免。

第一轮输出不佳时，要按层定位问题

如果第一轮结果不理想，不要立刻从头再来。先判断是哪一层出了问题：

• spec failure： 需求不清、缺漏，或出现过度实现
• quality failure： 拆分方式、可维护性或文件结构有问题
• coordination failure： 任务切分或上下文打包方式不对

然后只修正出问题的那一层。这样工作流会更高效。

进一步收紧文件结构指引

质量模板里有一个很有用的检查点：实现是否遵循了计划中的文件结构，以及新建文件是不是一开始就已经过大。如果你很在意可维护性，就应该在任务包里提前写明预期的文件边界，而不是寄希望于 reviewer 事后帮你兜底。

建立一份可复用的本地检查清单

如果你会经常使用 subagent-driven-development，建议准备一份简短的 coordinator checklist：

• plan 已存在
• task 是独立的
• 完整任务已贴入
• 约束已包含
• baseline SHA 已记录
• 已要求 implementer 在编码前先澄清
• spec review 已完成
• quality review 已完成

这个小习惯带来的稳定性提升，往往比继续把 prompt 写得更长更明显。

让这个技能更贴合你自己的工作流

这个基础 skill 本来就设计得很轻量。想让它在你的环境里更有效，最好的办法是按你的技术栈和 review 标准去改写这些 prompt 模板：

• 加入你的测试命令
• 加入 repo 特有的架构规则
• 明确定义什么算过度设计
• 规定你偏好的报告格式
• 补充你们代码库里的常见失败模式

这类本地化定制，通常比继续增加理论说明，更能改善 subagent-driven-development usage。