subagent-driven-development

概览

subagent-driven-development 是什么？

subagent-driven-development 是一种用于 orchestrate（编排）代理的技能，用来将实现计划拆分为一系列相互独立的任务，每个任务由一个全新的 subagent 执行。对于每一个任务，你会：

1. 启动一个专门负责实现的 implementer subagent。
2. 启动一个负责规格符合性检查的 spec compliance reviewer subagent。
3. 启动一个负责代码质量检查的 code quality reviewer subagent。

这三类 subagent 都被限制在高度受控的上下文中，只关注当前任务；同时你的主会话保持干净，用于统筹与决策。

这项技能适合谁？

subagent-driven-development 主要面向以下开发者和团队：

• 使用 AI 编码助手（如 Claude / claude-code），并希望获得更可靠结果的人。
• 有一份书面实现计划，并已拆分为离散任务的人。
• 需要在单个 AI 会话中完成代码实现与评审、且流程可重复的人。
• 不仅关心“能跑起来”，还在意是否满足规格以及代码质量的人。

它特别适合以 GitHub 为中心的工作流场景，你可以将 SHA、计划文件和 diff 传入各个 subagent。

它解决了哪些问题？

在用单个 AI agent 做端到端开发时，这个技能针对一些常见问题：

• 上下文臃肿（Context bloat）： 一个 agent 积累过多历史，逐渐失去聚焦能力。
• 规格漂移（Spec drift）： 实现逐渐偏离最初的计划或需求。
• 评审薄弱： 写代码的同一上下文顺便“评审”自己，容易漏错。

subagent-driven-development 强制执行一种模式：每个任务一个全新的 agent、严格控制上下文，再加上两阶段评审（先规格再质量）。这有助于提升正确性、控制变更范围，并让你更容易逐步推理整个实现计划。

什么时候适合使用 subagent-driven-development？

在以下情况下使用这项技能：

• 你已经有一份实现计划，并已拆分为多个任务。
• 这些任务大多彼此独立——不需要持续的跨任务协调。
• 你打算在当前会话内完成这份计划，而不是分散到几天时间。

如果你尚未有计划，或者任务之间强耦合、变化很快，你可能需要先：

• 通过其他技能或手工方式先进行头脑风暴或方案设计。
• 在探索性阶段使用更自由的单 agent 工作流。

使用方法

安装

1. 将技能添加到你的环境

从 obra/superpowers 仓库安装 subagent-driven-development 技能：

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

该命令会将技能定义和相关 prompt 模板拉取到你的 skills-enabled 环境中，便于你为计划中的每个任务 orchestrate 对应的 subagent。

2. 查看核心文件

安装完成后，在仓库中的技能目录（或通过你的 skills 浏览器）查看并阅读：

• SKILL.md – 高层描述、适用场景和核心工作流。
• implementer-prompt.md – implementer subagent 的模板。
• spec-reviewer-prompt.md – spec compliance reviewer subagent 的模板。
• code-quality-reviewer-prompt.md – code quality reviewer subagent 的模板。

把它们当作模板，自由复制或调整，集成进你自己的自动化或工具流程中。

准备你的实现计划

1. 编写或完善任务清单

在使用 subagent-driven-development 之前，先准备一份实现计划，并保证各任务：

• 范围清晰，便于测试。
• 彼此大多独立。
• 描述足够详细，使 implementer subagent 无需“猜测”即可执行。

每个任务都应可以直接复制粘贴到 implementer prompt 中，作为 “FULL TEXT of task from plan”。

2. 确定工作目录和 Git 策略

这些 prompt 模板默认假设你使用 Git 工作流，并有一个具体的工作目录：

• 选择 implementer 将要工作的 directory。
• 决定如何跟踪变更（例如为每个任务设置 BASE_SHA 和 HEAD_SHA）。

你会在规格评审和代码质量评审的 prompt 中传入这些值，以便进行准确的审查。

按任务运行工作流

1. 派发 implementer subagent

对于每个任务 N，基于 implementer-prompt.md 模板创建一个新的 implementer subagent。

模板中的关键点：

• 明确告诉 implementer：“You are implementing Task N: [task name]”。
• 将该任务的完整文本粘贴到 ## Task Description 部分。
• 填写：
  • Context – 该任务在系统中的位置与背景。
  • directory – 需要修改的目录。

implementer 会被指示去：

1. 在开始前，如有不清楚之处先提出澄清问题。
2. 严格按任务要求来实现功能。
3. 在合适的时候编写并运行测试。
4. 验证实现结果。
5. 提交本次工作。
6. 产出一份清晰的工作报告。

由于你为每个任务都创建一个全新的 subagent，它只会看到你提供的上下文，不会继承主会话中与本任务无关的历史。

2. 执行规格符合性评审

当 implementer 完成并返回报告后，使用 spec-reviewer-prompt.md 启动一个spec compliance reviewer subagent。

在该模板中，你需要：

• 将任务需求粘贴到 ## What Was Requested 中。
• 将implementer 的报告粘贴到 ## What Implementer Claims They Built 中。

spec reviewer 会被明确要求不要信任 implementer 的报告，而是必须：

• 直接阅读实际代码。
• 将代码逐行与需求比对。
• 找出缺失的需求、多余/不需要的实现，以及理解上的偏差。

如果 spec reviewer 发现问题，你需要再次与 implementer 反馈（可以是同一个 worker，也可以是新的 subagent），在继续下一个任务前先补齐这些差距。

3. 执行代码质量评审

当规格符合性评审通过后，使用 code-quality-reviewer-prompt.md 派发一个code quality reviewer subagent。

该模板预期你提供一个类似代码评审任务的描述，例如：

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

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

reviewer 将检查：

• 实现的整洁性与可维护性。
• 各文件的职责划分与接口设计（尽量做到“一文件一职责”）。
• 新增或改动文件的体量和拆分是否合理。
• 测试覆盖率，以及各单元是否易于理解和独立测试。

它会以结构化方式返回反馈：优点、问题（Critical / Important / Minor），以及整体评估。

随后你可以决定：

• 直接接受此变更。
• 要求 implementer 进行后续重构或改进。

让工作流适配你的环境

1. 为你的技术栈定制 prompts

implementer-prompt.md、spec-reviewer-prompt.md 和 code-quality-reviewer-prompt.md 中的模板都是刻意保持通用的。你可以按照自己的情况调整，比如：

• 使用的编程语言和框架。
• 测试习惯（如 pytest、Jest、Go test 等）。
• 仓库目录布局和命名规范。

即使做定制，也请保持核心结构不变——每个任务使用 fresh subagent、清晰的分节结构、明确的角色描述。

2. 自动化重复步骤

当你熟悉这个模式后，可以将其脚本化或工具化：

• 将三个 subagent 调用（implementer → spec reviewer → code quality reviewer）封装成每个任务一个命令。
• 从计划文件自动生成任务相关的 prompts。
• 通过读取 Git 元数据自动填充 BASE_SHA 和 HEAD_SHA。

这样可以把 subagent-driven-development 打造成你团队的一套可重复的工作流自动化方案。

3. 什么时候不适合使用这项技能

在以下情况下，你可能需要另一种方法：

• 任务之间高度相互依赖，无法干净地拆分。
• 你还没有清晰的实现计划。
• 需要长时间运行、跨会话的工作，必须保留多天的上下文。

遇到这些情况，可以优先使用聚焦于规划、架构或长期 agent 的技能或流程；当准备好执行明确的离散任务时，再回到 subagent-driven-development。

常见问题（FAQ）

“subagent-driven-development” 在实际使用中意味着什么？

在实践中，subagent-driven-development 的含义是：你不再让一个“全能” agent 来负责规划、编码和评审全部工作，而是：

• 在主会话中保持整体协调和全局上下文。
• 对于每个任务，仅用其所需信息构建一个全新的 subagent。
• 先让这个 subagent 完成实现，再用另外两个 subagent 对其进行评审。

这种方式实现了关注点分离，让上下文保持可控，并提升实现计划每一步的可靠性。

这和普通的单 agent 编码会话有何不同？

在单 agent 模式下，以往的对话和代码修改会不断累积在同一个上下文中，容易导致：

• 新旧需求混淆。
• 同一套推理模式既用来写代码，又用来评审代码。

而 subagent-driven-development 的做法是：

• 为实现和评审分别使用不同的 prompts 和角色。
• 为每个 subagent 提供经筛选的上下文，而不是整个会话的全部历史。
• 强制执行先规格评审、再质量评审的顺序。

这通常能带来更精确的实现和更诚实的评审。

一定要完全照模板来用吗？

不需要。仓库中的模板只是示例，用来展示如何组织 implementer、spec reviewer 和 code quality reviewer 这三类 prompts。你只需要：

• 保持整体模式：implementer → spec review → quality review。
• 保留关键行为（例如 spec reviewer 必须阅读真实代码，而不是只看报告）。

在这个结构之内，你可以调整措辞、加入项目特定的说明，并与现有工具和规范集成。

可以在不用 Git 的情况下使用 subagent-driven-development 吗？

code quality reviewer 的模板中假设存在 BASE_SHA 和 HEAD_SHA 之类字段，这些在 Git 工作流中很自然。如果你不用 Git：

• 仍然可以照搬核心理念——使用 fresh subagents 和两阶段评审。
• 将 SHA 替换为你自己的“前后状态”引用方式（比如归档 ID 或快照路径）。

这项技能并不会强制你使用 Git，它只是提供了面向 Git 的示例。

这项技能依赖特定的 AI 模型吗？

仓库并不会硬性绑定某个特定模型，但明显是针对现代通用型代码模型设计的，例如 Anthropics 的 Claude / claude-code。建议你：

• 使用能阅读并理解代码和测试的模型。
• 确保你的环境支持基于自定义 prompts 启动多个 subagent。

如果你的技术栈支持 agent tools 或 task runner，你可以把这些模板直接接入现有系统。

我如何判断该用 subagent-driven-development 还是其他 superpowers 技能？

SKILL.md 中给出了决策标准：当你已经有实现计划，且任务大多相互独立，并且打算在当前会话内完成时，适合使用 subagent-driven-development。如果上述条件有任何一条不满足，你可能更适合：

• 先用规划或头脑风暴类技能生成实现计划。
• 对于强耦合、跨会话的工作，选择其他执行或规划模式。

我在仓库里该从哪里开始看？

如果你正在评估是否安装或采用这项技能，可以从以下文件入手：

1. SKILL.md – 了解设计初衷和高层工作流。
2. implementer-prompt.md – 查看 implementer subagents 的设定方式。
3. spec-reviewer-prompt.md – 理解规格符合性检查的重点。
4. code-quality-reviewer-prompt.md – 了解额外的质量和结构检查点。

从这里开始，你可以将这些模板改造成适配自己环境的 agent 编排方式或工作流自动化方案，充分发挥 subagent-driven-development 的价值。