subagent-driven-development

子 Agent 驱动开发

按计划执行:为每个任务派发一个全新的实现子 Agent,每个任务完成后进行一次任务审查(规格合规性 + 代码质量),并在最后进行一次覆盖整个分支的全面审查。

为何使用子 Agent: 你将任务委派给具有隔离上下文的专职 Agent。通过精心编写它们的指令和上下文,你可以确保它们保持专注并成功完成任务。它们绝不应继承你会话的上下文或历史,你要精确构造它们所需的内容。这也能为你自己保留上下文,用于协调工作。

核心原则: 每个任务使用一个全新的子 Agent + 任务审查(规格 + 质量)+ 全面的最终审查 = 高质量、快速迭代

叙述: 在工具调用之间,最多叙述一行简短的话。台账和工具结果已经承载了记录。

持续执行: 不要在任务之间停下来向你的人类搭档确认。执行计划中的所有任务,不要中途停止。只有下面列出的四种情况会让你停止,或者所有任务已完成。“要我继续吗?”之类的询问和进度汇总只会浪费他们的时间。他们要求你执行计划,那就执行。

做出裁决,而非停滞。 计划运行时不应等待人类。冲突、歧义、计划缺陷、你本会请示是否超出的上限,都由你自行决定。规格是具有约束力的权威,计划是其论证,而你的判断可以决定两者都未解答的问题。每项决定都要以 Ruling: <what you decided> — <why> — <what it costs if wrong> 的格式记入台账,然后继续推进。错误的裁决会产生返工,而你的人类搭档可以看到并撤销;让会话停在一个问题上,只会耗费他们整天的时间却毫无收益。

只有以下四种情况会让你停止:不可逆或具破坏性的操作;涉及安全的操作;超出当前工作树、且惯例要求你先询问的副作用(合并、推送到共享分支、发布);以及计划破损到每条前进路径都只能靠猜的程度。遇到这些情况,停下来询问。

何时使用

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Partner chose inline, or no subagent tool?" [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?" -> "Partner chose inline, or no subagent tool?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Partner chose inline, or no subagent tool?" -> "executing-plans" [label="yes"];
    "Partner chose inline, or no subagent tool?" -> "subagent-driven-development" [label="no"];
}

对比执行计划(内联方式):

• 每个任务使用全新的子 Agent(避免上下文污染),而非由一个上下文完成所有任务
• 每个任务后进行审查(规格合规性 + 代码质量),而非仅在最后审查
• 每个任务和每次审查都要付出新上下文的成本;内联方式只需一个上下文加一位最终审查者的成本
• 两者都在本会话中运行,共享同一计划工作区和台账,且绝不在任务之间暂停

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer implements, tests, commits, self-reviews" [shape=box];
        "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
        "Spec ✅ and quality approved?" [shape=diamond];
        "Fix loop: read references/fix-loop.md before every round" [shape=box];
        "Append completion to ledger, mark todo complete" [shape=box];
    }

    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Final review and finish: read references/final-review.md" [shape=box];
    "Final review clean: delete this plan's workspace" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
    "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
    "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
    "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
    "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
    "Spec ✅ and quality approved?" -> "Fix loop: read references/fix-loop.md before every round" [label="no"];
    "Fix loop: read references/fix-loop.md before every round" -> "Append completion to ledger, mark todo complete" [label="addressed, or parked at the cap"];
    "Append completion to ledger, mark todo complete" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Final review and finish: read references/final-review.md" [label="no"];
    "Final review and finish: read references/final-review.md" -> "Final review clean: delete this plan's workspace";
    "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
}

设置

确保工作在隔离的工作区中进行：使用 superpowers:using-git-worktrees 创建一个工作区，或验证现有工作区。 未经人类搭档明确同意，切勿在 main/master 分支上开始实现。

对话记忆无法在压缩后保留。在实际会话中， 丢失进度的控制器曾重新派发整个已完成的任务序列——这是观察到的 代价最高的失误。请在台账文件中跟踪进度，而不只是记录待办事项。

• 每个计划都有自己的工作区：技能开始时，运行此技能的 bash scripts/sdd-workspace PLAN_FILE——它会输出该计划被 git 忽略的 目录（位于 <repo-root>/.superpowers/sdd/ 下），用于存放 此计划的所有产物：台账、简报、报告、审查材料。 你不得读取或写入其他计划的目录。
• 检查此计划的台账是否存在于 <workspace>/progress.md。如果存在， 在做任何其他事情之前，先阅读 references/resuming.md： 它会说明台账属于谁，以及应从哪里继续。
• 创建台账时，第一行写明其标识： # SDD ledger — plan: <plan file path>。
• 台账是你的恢复地图：其中记录的提交都存在于 git 中，即使你的上下文 已不记得创建过它们。压缩后，相信台账和 git log，不要依赖自己的回忆。
• git clean -fdx 会删除工作区（它是被 git 忽略的临时目录）；如果 发生这种情况，请从 git log 中恢复。

阅读一次计划，记下其上下文和全局约束，并为每项任务创建一个 待办事项。如果计划指定了 Spec，也要阅读：Spec 是计划论述所依据的 权威文档；计划内部出现冲突时，以 Spec 为准。如果无法找到计划提及的 Spec，请在台账中注明——没有 Spec 时作出的判断均为暂定结论。

派发 Task 1 之前，阅读 references/preflight.md 并运行其中说明的冲突扫描。将扫描表格和裁定记录在台账中。

模型选择

使用能够胜任各角色的最低能力模型，以节省成本并提高速度。

机械式实现任务（独立函数、明确规格、1–2 个文件）：使用快速、低成本的模型。计划规定清晰时，大多数实现任务都是机械式的。

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

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

审查任务：根据差异的规模、复杂度和风险，选择相应判断能力的模型。小型机械式差异不需要能力最强的模型；细微的并发变更则需要。小型修复差异的定向复审可使用低到中档模型。

修复循环升级（第 4–5 轮）：使用至少比陷入困境的实现者高一档的模型。

**派发子代理时务必明确指定模型。**如果省略模型，将继承会话模型——通常是能力最强、成本最高的模型——这会悄然违背本节要求。

**轮次数比 Token 单价更重要。**子代理的耗时和上下文成本会随着轮次数增加，而最便宜的模型在多步骤工作中通常需要多出 2–3 倍的轮次——总体成本反而更高。对于审查者，以及依据文字描述工作的实现者，至少使用中档模型。若任务计划中已包含要编写的完整代码，实现只是转录加测试：为该实现者使用最低成本档。单文件机械式修复也使用最低成本档。

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

• 涉及 1–2 个文件且规格完整 → 低成本模型
• 涉及多个文件且存在集成问题 → 标准模型
• 需要设计判断或广泛理解代码库 → 能力最强的模型

任务循环

**少量同类工作：**当计划列出跨多个文件的几项小型同类修改时，分派前请阅读 references/batching.md。

你粘贴到分派提示词中的所有内容，以及子 Agent 打印返回的所有内容，都会在本次会话的剩余时间内留在你的上下文中，并在之后的每一轮中重新读取。请通过文件移交产物。

**等待已分派的子 Agent：**不要使用较短的超时轮询等待接口，也不要一直陷入无声、无期限的等待。当你还有本地工作时——更新台账、准备下一轮审查材料、阅读报告——就继续工作；子任务结果会自行到达。真正空闲时，分段进行有界等待（平台允许时，每次等待五到十分钟），并在每段等待之间发布一行状态，核对正在运行的子任务：列出它们，并跟进已完成但未报告的任务。有界等待几乎能保留长时间等待的全部效率，同时确保几分钟内就能发现卡住或失联的子任务，而不是等到会话结束才发现。

1. 分派实现者

分派前记录 BASE（git rev-parse HEAD）——审查材料包和修复轮次的差异都需要它。

• **任务说明：**分派实现者前，运行此技能的 bash scripts/task-brief PLAN_FILE N——它会将任务的完整文本提取到一个唯一命名的文件，并打印该文件路径。撰写分派内容时，应让任务说明始终作为唯一的需求来源。分派内容应包含：(1) 说明该任务在项目中所处位置的一行文字；(2) 任务说明的路径，并以“请先阅读此文件——它是你的需求依据，具体值必须逐字照用”引出；(3) 任务说明无法知晓的先前任务接口和决策；(4) 你对任务说明中任何歧义的处理方式；(5) 报告文件路径和报告约定。具体值（数字、魔法字符串、签名、测试用例）只能出现在任务说明中。绝不要让子 Agent 阅读整个计划文件。
• **报告文件：**实现者的报告文件应以任务说明命名（任务说明 …/task-N-brief.md → 报告 …/task-N-report.md），并将路径写入分派提示词。实现者应在该文件中撰写完整报告，返回内容仅包含状态、提交记录、一行测试摘要和关注事项。
• 分派提示词只描述一个任务，不描述本次会话的历史。不要在后续分派中粘贴累积的先前任务摘要（“任务 1–3 后的状态”）——一次实际会话的分派内容达到 42k 个字符，其中 99% 都是粘贴的历史记录。新的子 Agent 只需要了解自己的任务、涉及的接口和全局约束，无需其他内容。
• 分派内容必须包含不得使用子 Agent 的约定（实现者模板中已有此约定）：实现者绝不分派子 Agent——既不分派助手，也不分派审查者。报告返回后，由你进行审查。在实际会话中，工作者创建的每个审查者都会重复控制者已分派的任务审查——每个任务都额外占用一个完整的审查席位。
• 如果较早的任务曾在本任务涉及的区域记录待处理发现，分派时需提供指向该台账条目的引用。
• 记录分派结果中的实现者 Agent 身份——修复循环第 1–3 轮要恢复使用该 Agent。
• 绝不要并行分派多个实现子 Agent（会产生冲突）。

模板：implementer-prompt.md

2. 处理报告

实现者子 Agent 会报告四种状态之一。请根据状态妥善处理：

DONE： 生成审查包（在此技能目录中运行 bash scripts/review-package PLAN_FILE BASE HEAD——它会打印写入文件的唯一文件路径；BASE 是你在派发实现者之前记录的提交，绝不要用 HEAD~1，否则多提交任务中除最后一个提交外的所有提交都会被静默遗漏），然后将打印出的路径交给任务审查者。

其他任何状态（DONE_WITH_CONCERNS、NEEDS_CONTEXT、BLOCKED）：每次收到此类状态时，都要阅读 references/handling-reports.md 并按其要求处理。

如果实现者提出问题——无论是在开始前还是任务进行中——都要清晰、完整地回答，并在需要时提供更多背景信息；不要催促其开始实现。

3. 审查任务

每项任务的审查都是仅针对该任务的关卡。全面审查只在最终的整个分支审查中进行。绝不要跳过任务审查，也绝不要接受缺少任一判定的报告——必须同时满足规范合规性和任务质量要求。实现者的自审不能代替任务审查；两者都不可或缺。

• 将差异文件交给审查者：运行此技能的 bash scripts/review-package PLAN_FILE BASE HEAD，并传递其打印出的文件路径（如果没有 bash，则运行 git log --oneline、git diff --stat 和该范围的 git diff -U10，并将输出重定向到一个唯一命名的文件）。输出不会进入你自己的上下文；审查者可以通过一次 Read 调用查看其中的提交列表、统计摘要，以及包含上下文的完整差异。使用你在派发实现者之前记录的 BASE——绝不要用 HEAD~1，否则会静默截断多提交任务。没有差异文件时，绝不要派发任务审查者。
• 审查者输入： 任务审查者会收到三个路径——同一份任务说明文件、报告文件和审查包——以及约束该任务的全局约束。
• 提供给审查者的全局约束块是其关注重点。请从计划的 Global Constraints 部分或规范中逐字复制具有约束力的要求，包括确切值、确切格式，以及组件之间明确规定的关系（例如“与 X 的布局相同”“与 Y 匹配”）。审查者模板已包含流程规则（YAGNI、测试规范、审查方法）——约束块只需写明本项目规范对这项任务的具体要求。
• 不要添加“检查所有用法”或“必要时运行竞态测试”等没有具体任务原因的开放式指令。
• 不要要求审查者重新运行实现者已在相同代码上运行过的测试——测试证据会包含在实现者的报告中。
• 不要预先判断审查者的发现——绝不要指示审查者忽略或不要标记某个具体问题。如果你认为某项发现是误报，就让审查者提出，然后在审查循环中进行裁定。如果你撰写的提示词中出现“不要标记”“不要把 X 视为缺陷”“最多为 Minor”或“计划选择了”，请停下：这就是在预先判断，通常是为了省去一轮审查。 如果审查者报告了“⚠️ 无法通过差异验证”的项目，在标记任务完成前，请阅读 references/cannot-verify.md。

模板：task-reviewer-prompt.md

4. 修复循环

当审查结果为规范 ❌、存在任何 Critical 或 Important 发现，或存在你确认确属实际缺陷的 ⚠️ 项时，就会触发修复循环。

触发后，请阅读 references/fix-loop.md 并按其要求执行。每轮开始前都要重新阅读，即使本次会话中之前读过：其中规定了轮数上限、中止机制，以及每轮要写入的记录行；上下文压缩后，你对这些内容的记忆不会保留。

5. 完成任务

当审查结果干净——或每项未解决的问题都已达到上限并作出裁定——请在记账的同一条消息中，将完成行追加到台账：

• Task <N>: complete (commits <base7>..<head7>, review clean)
• 触发熔断器后：Task <N>: complete (commits <base7>..<head7>, <K> parked)

然后将待办标记为已完成，并继续下一项。在审查中仍有未修复、也未在上限处搁置并作出裁定的 Critical/Important 问题时，绝不要开始下一个任务。

最终审查

所有任务完成后，阅读 references/final-review.md 并遵循其中的说明。该文档涵盖整个分支的审查、唯一一轮修复，以及收尾方式。

常见借口

借口	事实
“大体符合规范就行”	审查发现规范缺漏 = 尚未完成。修复，或达到上限后作出裁定——只有这两种出路。
“我自己修就好，派发任务只是额外开销”	控制器直接修复会污染上下文并跳过审查。应恢复实施者的工作。
“再来一轮就能解决”	超过上限后，继续几轮也无法解决——问题出在结构上。作出裁定并分派处理。
“审查者反正还会发现新问题”	有范围限制的复审用于验证修复，不能随意扩展。未触及代码中的新发现应记入台账，而不是加入修复循环。
“这个问题显然不成立，我就忽略它”	只能在达到上限时作出裁定，而且每项裁定都必须记入台账。禁止默默丢弃问题。
“修复很小，跳过复审吧”	回归问题往往由未经审查的修复引发。每一轮结束时都必须进行范围限定的复审。
“审查会拖慢循环”	没有审查的循环只是在反复忙碌，却未经验证。审查是循环的刹车与方向盘。
“记台账只是额外开销”	台账能在上下文压缩后保留信息。没有台账的控制器曾重新派发整套已完成的任务。
“实施者自己启动了审查者——这不是额外保障吗？”	这只是重复审查同一差异的冗余角色；任务审查才是关卡。工作者自行启动审查者是应标记的缺陷，而不是严谨。