subagent-driven-development

子代理驱动开发

通过为每个任务分派一个全新的实现子代理、每个任务后进行任务审查（规范合规性 + 代码质量），最后进行全面的全分支审查来执行计划。

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

核心原则： 每个任务使用全新子代理 + 任务审查（规范 + 质量）+ 全面的最终审查 = 高质量、快速迭代

叙述： 在工具调用之间，最多叙述一行简短内容——账本和工具结果承载记录。

持续执行： 不要在任务之间暂停与人类伙伴确认。不间断地执行计划中的所有任务。唯一需要停止的原因是：无法解决的 BLOCKED 状态、真正阻碍进展的歧义，或所有任务完成。"我应该继续吗？"的提示和进度摘要会浪费他们的时间——他们要求你执行计划，所以执行它。

何时使用

digraph when_to_use {
    "有实施计划？" [shape=diamond];
    "任务大部分独立？" [shape=diamond];
    "留在当前会话？" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "手动执行或先进行头脑风暴" [shape=box];

    "有实施计划？" -> "任务大部分独立？" [label="是"];
    "有实施计划？" -> "手动执行或先进行头脑风暴" [label="否"];
    "任务大部分独立？" -> "留在当前会话？" [label="是"];
    "任务大部分独立？" -> "手动执行或先进行头脑风暴" [label="否 - 紧密耦合"];
    "留在当前会话？" -> "subagent-driven-development" [label="是"];
    "留在当前会话？" -> "executing-plans" [label="否 - 并行会话"];
}

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

• 同一会话（无上下文切换）
• 每个任务使用全新子代理（无上下文污染）
• 每个任务后审查（规范合规性 + 代码质量），最后进行全面审查
• 更快的迭代（任务之间无需人工介入）

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "分派实现子代理 (./implementer-prompt.md)" [shape=box];
        "实现子代理提问？" [shape=diamond];
        "回答问题，提供上下文" [shape=box];
        "实现子代理实现、测试、提交、自我审查" [shape=box];
        "编写 diff 文件，分派任务审查子代理 (./task-reviewer-prompt.md)" [shape=box];
        "任务审查报告规范 ✅ 且质量通过？" [shape=diamond];
        "分派修复子代理处理关键/重要发现" [shape=box];
        "在待办列表和进度账本中标记任务完成" [shape=box];
    }

    "阅读计划，记录上下文和全局约束，创建待办" [shape=box];
    "还有更多任务？" [shape=diamond];
    "分派最终代码审查子代理 (../requesting-code-review/code-reviewer.md)" [shape=box];
    "使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "阅读计划，记录上下文和全局约束，创建待办" -> "分派实现子代理 (./implementer-prompt.md)";
    "分派实现子代理 (./implementer-prompt.md)" -> "实现子代理提问？";
    "实现子代理提问？" -> "回答问题，提供上下文" [label="是"];
    "回答问题，提供上下文" -> "分派实现子代理 (./implementer-prompt.md)";
    "实现子代理提问？" -> "实现子代理实现、测试、提交、自我审查" [label="否"];
    "实现子代理实现、测试、提交、自我审查" -> "编写 diff 文件，分派任务审查子代理 (./task-reviewer-prompt.md)";
    "编写 diff 文件，分派任务审查子代理 (./task-reviewer-prompt.md)" -> "任务审查报告规范 ✅ 且质量通过？";
    "任务审查报告规范 ✅ 且质量通过？" -> "分派修复子代理处理关键/重要发现" [label="否"];
    "分派修复子代理处理关键/重要发现" -> "编写 diff 文件，分派任务审查子代理 (./task-reviewer-prompt.md)" [label="重新审查"];
    "任务审查报告规范 ✅ 且质量通过？" -> "在待办列表和进度账本中标记任务完成" [label="是"];
    "在待办列表和进度账本中标记任务完成" -> "还有更多任务？";
    "还有更多任务？" -> "分派实现子代理 (./implementer-prompt.md)" [label="是"];
    "还有更多任务？" -> "分派最终代码审查子代理 (../requesting-code-review/code-reviewer.md)" [label="否"];
    "分派最终代码审查子代理 (../requesting-code-review/code-reviewer.md)" -> "使用 superpowers:finishing-a-development-branch";
}

飞行前计划审查

在分派任务 1 之前，扫描计划以发现冲突：

• 相互矛盾的任务，或与计划的全局约束冲突的任务
• 计划明确要求但审查标准视为缺陷的内容（例如，没有断言的测试、逻辑块的逐字重复）

将所有发现作为一批问题呈现给你的人类伙伴——每个发现附上要求它的计划文本，询问哪个优先——在执行开始之前，而不是在计划中途逐个中断。如果扫描干净，则无需评论直接继续。审查循环仍然是捕获仅从实现中出现的冲突的网。

模型选择

使用能够处理每个角色的最弱模型以节省成本并提高速度。

机械性实现任务（隔离的函数、清晰的规范、1-2 个文件）：使用快速、廉价的模型。当计划规范明确时，大多数实现任务都是机械性的。

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

架构和设计任务：使用最强大的可用模型。最终的全分支审查属于此类——使用最强大的可用模型分派，而不是会话默认模型。

审查任务：选择具有相同判断力的模型，根据 diff 的大小、复杂性和风险进行调整。小的机械性 diff 不需要最强大的模型；微妙的并发更改则需要。

分派子代理时始终明确指定模型。 省略模型将继承你会话的模型——通常是最强大且最昂贵的——这会在不知不觉中违背本节意图。

轮次数量胜过令牌价格。 墙上时钟和上下文成本与子代理所需的轮次数量成正比，而最便宜的模型在多步骤工作中通常需要 2-3 倍的轮次——总体成本更高。使用中档模型作为审查者和从散文描述工作的实现者的最低标准。当任务的计划文本包含要编写的完整代码时，实现是转录加测试：对该实现者使用最便宜的层级。单文件机械性修复也使用最便宜的层级。

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

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

处理实现者状态

实现子代理报告四种状态之一。适当处理每种状态：

DONE： 生成审查包（scripts/review-package BASE HEAD，从本技能目录运行——它打印写入的唯一文件路径；BASE 是你在分派实现者之前记录的提交——绝不是 HEAD~1，它会静默丢弃多提交任务的最后一个提交之外的所有提交），然后使用打印的路径分派任务审查者。

DONE_WITH_CONCERNS： 实现者完成了工作但标记了疑虑。在继续之前阅读疑虑。如果疑虑涉及正确性或范围，在审查前解决它们。如果它们是观察结果（例如，“这个文件变得很大”），记录下来并继续审查。

NEEDS_CONTEXT： 实现者需要未提供的信息。提供缺失的上下文并重新分派。

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

1. 如果是上下文问题，提供更多上下文并使用相同模型重新分派
2. 如果任务需要更多推理，使用更强大的模型重新分派
3. 如果任务太大，将其分解为更小的部分
4. 如果计划本身有误，升级给人类

绝不忽略升级或强制相同模型在无更改的情况下重试。如果实现者表示卡住，则需要改变某些东西。

处理审查者 ⚠️ 项目

任务审查者可能报告“⚠️ 无法从 diff 验证”项目——这些是存在于未更改代码或跨任务的需求。它们不会阻止审查的其余部分，但你必须自己在标记任务完成之前解决每个项目：你拥有审查者缺乏的计划和跨任务上下文。如果你确认某个项目是真正的差距，将其视为失败的规范审查——将其发送回实现者并重新审查。

构建审查者提示

每个任务的审查是任务范围的关卡。全面审查只进行一次，在最终的全分支审查中。当你填写审查者模板时：

• 不要添加开放式指令，如“检查所有用法”或“如果有用则运行竞态测试”，除非有具体的、任务特定的原因
• 不要要求审查者重新运行实现者已经在相同代码上运行过的测试——实现者的报告包含测试证据
• 不要预先判断审查者的发现——绝不要指示审查者忽略或不标记特定问题。如果你认为某个发现会是误报，让审查者提出并在审查循环中裁决。如果你正在编写的提示包含“不要标记”、“不要将 X 视为缺陷”、“最多 Minor”或“计划选择了”——停止：你正在预先判断，通常是为了避免审查循环。
• 你交给审查者的全局约束块是其注意力透镜。从计划的全局约束部分或规范中逐字复制绑定要求：确切的值、确切的格式以及组件之间声明的关系（“与 X 相同的布局”、“匹配 Y”）。审查者的模板已经包含过程规则（YAGNI、测试卫生、审查方法）——约束块用于本项目规范要求的内容。
• 将 diff 作为文件交给审查者：运行本技能的 scripts/review-package BASE HEAD 并将打印的文件路径传递给审查者（或者，如果没有 bash：git log --oneline、git diff --stat 和 git diff -U10 用于范围，重定向到一个唯一命名的文件）。输出永远不会进入你自己的上下文，审查者通过一次 Read 调用看到提交列表、统计摘要和带有上下文的完整 diff。使用你在分派实现者之前记录的 BASE——绝不是 HEAD~1，它会静默截断多提交任务。
• 分派提示描述一个任务，而不是会话的历史。不要将累积的先前任务摘要（“任务 1-3 后的状态”）粘贴到后续分派中——一个真实会话的分派达到了 42k 字符，其中 99% 是粘贴的历史。一个全新的子代理需要它的任务、它接触的接口以及全局约束。没有别的。
• 为关键和重要发现分派修复子代理。将次要发现记录在进度账本中，并在最终的全分支审查中指向该列表，以便它能够分类哪些必须在合并前修复。无人阅读的汇总就是静默丢弃。
• 标记为计划强制要求的发现——或任何与计划文本要求冲突的发现——是人类的决定，就像任何计划矛盾一样：呈现发现和计划文本，询问哪个优先。不要因为计划要求而驳回发现，也不要分派与计划矛盾的修复而不询问。
• 最终的全分支审查也获得一个包：运行 scripts/review-package MERGE_BASE HEAD（MERGE_BASE = 分支开始的提交，例如 git merge-base main HEAD）并在最终审查分派中包含打印的路径，以便最终审查者读取一个文件而不是用 git 命令重新推导分支 diff。
• 每个修复分派都带有实现者契约：修复子代理重新运行覆盖其更改的测试并报告结果。在分派中命名覆盖的测试文件——一行修复不需要整个套件。在重新分派审查者之前，确认修复报告包含覆盖的测试、运行的命令和输出；一旦三者都存在，分派重新审查。
• 如果最终的全分支审查返回发现，分派一个修复子代理处理完整的发现列表——而不是每个发现一个修复者。每个发现的修复者都会重建上下文并重新运行套件；一个真实会话的最终审查修复波的成本超过了所有任务的总和。

文件交接

你粘贴到分派提示中的所有内容——以及子代理打印回的所有内容——都会在你会话的剩余时间内驻留在你的上下文中，并在每次后续轮次中重新读取。将工件作为文件传递：

• 任务简报： 在分派实现者之前，运行本技能的 scripts/task-brief PLAN_FILE N——它将任务的完整文本提取到一个唯一命名的文件并打印路径。编写分派时，让简报保持为需求的唯一来源。你的分派应包含：(1) 一行说明此任务在项目中的位置；(2) 简报路径，介绍为“首先阅读此文件——它是你的需求，包含要逐字使用的确切值”；(3) 来自早期任务且简报无法知道的接口和决策；(4) 你对简报中注意到的任何歧义的解决方案；(5) 报告文件路径和报告契约。确切的值（数字、魔法字符串、签名、测试用例）仅出现在简报中。
• 报告文件： 将实现者的报告文件命名为与简报对应的名称（简报 …/task-N-brief.md → 报告 …/task-N-report.md）并将其放在分派提示中。实现者将完整报告写入那里，并仅返回状态、提交、一行测试摘要和疑虑。
• 审查者输入： 任务审查者获得三个路径——相同的简报文件、报告文件和审查包——加上绑定任务的全局约束。
• 修复分派将其修复报告（包含测试结果）附加到相同的报告文件并返回简短摘要；重新审查读取更新后的文件。

持久进度

对话记忆在压缩后不会保留。在真实会话中，失去位置的控制器已经重新分派了整个已完成的任务序列——这是观察到的最昂贵的失败。在文件中跟踪进度，而不仅仅在待办中。

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

提示模板

• implementer-prompt.md - 分派实现子代理
• task-reviewer-prompt.md - 分派任务审查子代理（规范合规性 + 代码质量）
• 最终全分支审查：使用 superpowers:requesting-code-review 的 code-reviewer.md

示例工作流

你：我正在使用子代理驱动开发来执行此计划。

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

任务 1：钩子安装脚本

[为任务 1 运行 task-brief；使用简报 + 报告路径 + 上下文分派实现者]

实现者：“在我开始之前——钩子应该安装在用户级别还是系统级别？”

你：“用户级别 (~/.config/superpowers/hooks/)”

实现者：“收到。正在实现...”
[稍后] 实现者：
  - 实现了 install-hook 命令
  - 添加了测试，5/5 通过
  - 自我审查：发现我遗漏了 --force 标志，已添加
  - 已提交

[运行 review-package，使用打印的路径分派任务审查者]
任务审查者：规范 ✅ - 所有需求满足，没有多余内容。
  优点：测试覆盖良好，代码干净。问题：无。任务质量：通过。

[标记任务 1 完成]

任务 2：恢复模式

[为任务 2 运行 task-brief；使用简报 + 报告路径 + 上下文分派实现者]

实现者：[无问题，直接进行]
实现者：
  - 添加了验证/修复模式
  - 8/8 测试通过
  - 自我审查：一切正常
  - 已提交

[运行 review-package，使用打印的路径分派任务审查者]
任务审查者：规范 ❌：
  - 缺失：进度报告（规范说“每 100 项报告一次”）
  - 多余：添加了 --json 标志（未要求）
  问题（重要）：魔法数字 (100)

[使用所有发现分派修复子代理]
修复者：移除了 --json 标志，添加了进度报告，提取了 PROGRESS_INTERVAL 常量

[任务审查者再次审查]
任务审查者：规范 ✅。任务质量：通过。

[标记任务 2 完成]

...

[所有任务完成后]
[分派最终代码审查者]
最终审查者：所有需求满足，准备合并

完成！

优势

与手动执行对比：

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

与执行计划对比：

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

效率提升：

• 控制器精确策划所需上下文；批量工件作为文件移动，而非粘贴文本
• 子代理预先获得完整信息
• 问题在工作开始前提出（而非之后）

质量关卡：

• 自我审查在交接前捕获问题
• 任务审查带有两个裁决：规范合规性和代码质量
• 审查循环确保修复实际有效
• 规范合规性防止过度/不足构建
• 代码质量确保实现构建良好

成本：

• 更多子代理调用（每个任务实现者 + 审查者）
• 控制器做更多准备工作（预先提取所有任务）
• 审查循环增加迭代次数
• 但早期捕获问题（比以后调试更便宜）

红旗

绝不：

• 在没有明确用户同意的情况下在 main/master 分支上开始实现
• 跳过任务审查，或接受缺少任一裁决的报告（规范合规性和任务质量都是必需的）
• 在未修复问题的情况下继续
• 并行分派多个实现子代理（冲突）
• 让子代理阅读整个计划文件（而是交给它任务简报——scripts/task-brief）
• 跳过场景设置上下文（子代理需要理解任务的位置）
• 忽略子代理的问题（在让他们继续之前回答）
• 在规范合规性上接受“差不多”（审查者发现规范问题 = 未完成）
• 跳过审查循环（审查者发现问题 = 实现者修复 = 再次审查）
• 让实现者的自我审查替代实际审查（两者都需要）
• 告诉审查者不要标记什么，或在分派提示中预先评定发现的严重性（“最多视为 Minor”）——计划的示例代码是起点，而不是其弱点被选择的证据
• 在没有 diff 文件的情况下分派任务审查者——先生成它（scripts/review-package BASE HEAD）并在提示中命名打印的路径
• 在审查仍有未解决的关键/重要问题时进入下一个任务
• 重新分派进度账本已标记完成的任务——在压缩或恢复后检查账本（和 git log）

如果子代理提问：

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

如果审查者发现问题：

• 实现者（同一子代理）修复它们
• 审查者再次审查
• 重复直到通过
• 不要跳过重新审查

如果子代理任务失败：

• 使用具体指令分派修复子代理
• 不要尝试手动修复（上下文污染）

集成

所需的工作流技能：

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

子代理应使用：

• superpowers:test-driven-development - 子代理为每个任务遵循 TDD

替代工作流：

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