subagent-driven-development

# 子智能体驱动开发

通过为每个任务分派一个全新的实现子智能体来执行计划：每个任务完成后做一次任务审查（规格合规性 + 代码质量），全部任务结束后再做一次覆盖整个分支的宽范围审查。

**为什么用子智能体：** 你把任务委派给具有隔离上下文的专用智能体。通过精心设计它们的指令和上下文，确保它们专注并成功完成任务。它们绝不应继承你会话的上下文或历史记录——你要精确构造它们所需的一切。这样也能为你自己保留用于协调工作的上下文。

**核心原则：** 每个任务一个全新子智能体 + 任务审查（规格 + 质量）+ 结尾宽范围审查 = 高质量、快速迭代

**旁白：** 工具调用之间最多说一句简短的旁白——进度账本和工具结果本身就是记录。

**持续执行：** 不要在任务之间停下来向你的人类伙伴确认。不间断地执行计划里的所有任务。唯一该停下的理由是：你无法解决的 BLOCKED 状态、确实妨碍推进的歧义，或所有任务已完成。"我该继续吗？"之类的询问和进度小结都在浪费他们的时间——他们让你执行计划，那就执行。

## 何时使用

```dot
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="否 - 并行会话"];
}
```

**与 Executing Plans（并行会话）的对比：**
- 同一会话（无上下文切换）
- 每个任务全新子智能体（无上下文污染）
- 每个任务后做审查（规格合规性 + 代码质量），结尾做宽范围审查
- 更快的迭代（任务间无需人工介入）

## 流程

```dot
digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="每个任务";
        "分派实现子智能体 (./implementer-prompt.md)" [shape=box];
        "实现者有疑问?" [shape=diamond];
        "回答问题，提供上下文" [shape=box];
        "实现者实现、测试、提交、自审" [shape=box];
        "生成审查包，分派任务审查者 (./task-reviewer-prompt.md)" [shape=box];
        "规格 ✅ 且质量通过?" [shape=diamond];
        "发现与计划原文冲突?" [shape=diamond];
        "询问人类伙伴以哪个为准" [shape=box];
        "第 R/5 轮修复: R≤3 唤回原实现者; R≥4 换全新实现者 + 更强模型" [shape=box];
        "分派定向复审 (./re-review-prompt.md)" [shape=box];
        "所有发现都已解决?" [shape=diamond];
        "R = 5?" [shape=diamond];
        "逐条裁定未解决的发现" [shape=box];
        "存在承重的发现?" [shape=diamond];
        "停止: 向人类伙伴报告 BLOCKED" [shape=box];
        "把发现连同裁定搁置进账本" [shape=box];
        "往账本追加完成行，标记待办完成" [shape=box];
    }

    "准备: 工作树、查账本、读计划、起飞前审查" [shape=box];
    "还有任务?" [shape=diamond];
    "分派最终代码审查者 (../requesting-code-review/code-reviewer.md)" [shape=box];
    "最终审查有发现? 一次修复分派、一次定向复审、裁定残留项" [shape=box];
    "最终审查干净: 删除本计划的工作区" [shape=box];
    "使用 superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "准备: 工作树、查账本、读计划、起飞前审查" -> "分派实现子智能体 (./implementer-prompt.md)";
    "分派实现子智能体 (./implementer-prompt.md)" -> "实现者有疑问?";
    "实现者有疑问?" -> "回答问题，提供上下文" [label="是"];
    "回答问题，提供上下文" -> "实现者实现、测试、提交、自审";
    "实现者有疑问?" -> "实现者实现、测试、提交、自审" [label="否"];
    "实现者实现、测试、提交、自审" -> "生成审查包，分派任务审查者 (./task-reviewer-prompt.md)";
    "生成审查包，分派任务审查者 (./task-reviewer-prompt.md)" -> "规格 ✅ 且质量通过?";
    "规格 ✅ 且质量通过?" -> "往账本追加完成行，标记待办完成" [label="是"];
    "规格 ✅ 且质量通过?" -> "发现与计划原文冲突?" [label="否"];
    "发现与计划原文冲突?" -> "询问人类伙伴以哪个为准" [label="是"];
    "询问人类伙伴以哪个为准" -> "第 R/5 轮修复: R≤3 唤回原实现者; R≥4 换全新实现者 + 更强模型";
    "发现与计划原文冲突?" -> "第 R/5 轮修复: R≤3 唤回原实现者; R≥4 换全新实现者 + 更强模型" [label="否"];
    "第 R/5 轮修复: R≤3 唤回原实现者; R≥4 换全新实现者 + 更强模型" -> "分派定向复审 (./re-review-prompt.md)";
    "分派定向复审 (./re-review-prompt.md)" -> "所有发现都已解决?";
    "所有发现都已解决?" -> "往账本追加完成行，标记待办完成" [label="是"];
    "所有发现都已解决?" -> "R = 5?" [label="否"];
    "R = 5?" -> "第 R/5 轮修复: R≤3 唤回原实现者; R≥4 换全新实现者 + 更强模型" [label="否 - 进入下一轮"];
    "R = 5?" -> "逐条裁定未解决的发现" [label="是 - 熔断触发"];
    "逐条裁定未解决的发现" -> "存在承重的发现?";
    "存在承重的发现?" -> "停止: 向人类伙伴报告 BLOCKED" [label="是"];
    "存在承重的发现?" -> "把发现连同裁定搁置进账本" [label="否"];
    "把发现连同裁定搁置进账本" -> "往账本追加完成行，标记待办完成";
    "往账本追加完成行，标记待办完成" -> "还有任务?";
    "还有任务?" -> "分派实现子智能体 (./implementer-prompt.md)" [label="是"];
    "还有任务?" -> "分派最终代码审查者 (../requesting-code-review/code-reviewer.md)" [label="否"];
    "分派最终代码审查者 (../requesting-code-review/code-reviewer.md)" -> "最终审查有发现? 一次修复分派、一次定向复审、裁定残留项";
    "最终审查有发现? 一次修复分派、一次定向复审、裁定残留项" -> "最终审查干净: 删除本计划的工作区";
    "最终审查干净: 删除本计划的工作区" -> "使用 superpowers:finishing-a-development-branch";
}
```

## 准备

确保工作发生在一个隔离的工作区里：用 superpowers:using-git-worktrees 创建一个，或者核实已有的那个。没有你人类伙伴的明确同意，绝不在 main/master 分支上开始实现。

会话记忆无法在上下文压缩（compaction）中存活。在真实会话里，丢失了位置的控制者曾重新分派整段已经完成的任务序列——这是观察到的最昂贵的失败。把进度记在一个账本文件里，而不只是记在待办里。

- **每个计划拥有自己的工作区：** 技能启动时，运行本技能的 `scripts/sdd-workspace PLAN_FILE`——它会打印这个计划专属的、被 git 忽略的目录（`<repo-root>/.superpowers/sdd/<计划文件名>/`），**本计划**的一切产物都放在那里：账本、简报、报告、审查包。别的计划的目录不属于你，不读也不写。
- 到 `<工作区>/progress.md` 查本计划的账本。如果它的第一行点名的是你的计划文件，那么带有 `Task <N>: complete` 行的任务就是**已完成**——不要重新分派它们；从第一个没有该行的任务处继续。如果某个任务的最后一行是一轮修复，说明它正卡在修复循环中：从下一轮继续。如果账本第一行点名的是**另一个**计划文件——或者你在旧的扁平路径 `.superpowers/sdd/progress.md` 发现了一个游离的账本——那是别人的进度：原地别动，另起你自己的新账本。
- 创建账本时，把它的身份写在第一行：`# SDD ledger — plan: <计划文件路径>`。
- 这个账本是你的恢复地图：它点名的那些提交，即使你的上下文已经不记得创建过它们，也确实存在于 git 中。压缩之后，相信账本和 `git log`，而不是你自己的记忆。
- `git clean -fdx` 会毁掉这个工作区（它是被 git 忽略的临时文件）；万一发生了，就从 `git log` 恢复。

把计划**读一遍**，记下它的上下文和全局约束，并为每个任务建一条待办。

在分派任务 1 之前，把计划通扫一遍找冲突：

- 互相矛盾的任务，或与计划的"全局约束"矛盾的任务
- 计划明确要求、但审查标准会判为缺陷的东西（比如一个什么都不断言的测试、一整块逻辑的逐字复制）

把你找到的所有问题**一次性打包成一个问题**呈现给你的人类伙伴——每条发现都并列上要求它的那段计划原文，问以哪个为准——在执行开始之前问，而不是执行过程中每发现一个就打断一次。如果扫描是干净的，就不要多说，直接开始。审查循环仍然是那些只有在实现中才浮现的冲突的兜底网。

## 模型选择

在能胜任的前提下，为每个角色选用最弱的模型，以节省成本、提升速度。

**机械性实现任务**（孤立的函数、清晰的规格、1-2 个文件）：用快而便宜的模型。计划写得好时，大多数实现任务都是机械性的。

**集成与判断类任务**（跨文件协调、模式匹配、调试）：用标准模型。

**架构与设计类任务**：用可用的最强模型。覆盖整个分支的最终审查就属于这一类——用可用的最强模型去分派它，不要用会话默认模型。

**审查任务**：用同样的判断来选模型，并按 diff 的体量、复杂度和风险来缩放。一个小的机械性 diff 不需要最强模型；一个微妙的并发改动需要。小修复 diff 的定向复审用便宜到中档的层级即可。

**修复循环的升级（第 4-5 轮）**：用比那个卡住了的实现者**至少高一档**的模型。

**分派子智能体时永远显式指定模型。** 省略模型会继承你会话的模型——往往是最强也最贵的那个——这会悄无声息地让本节的努力全部失效。

**轮次数比 token 单价更要紧。** 墙钟时间和上下文成本是随子智能体花掉多少轮次而增长的，而最便宜的模型在多步工作上经常要花 2-3 倍轮次——总账反而更贵。审查者、以及依据散文式描述工作的实现者，都以中档模型为下限。当任务的计划原文里已经包含了要写的完整代码时，实现就是抄写加测试：这种实现者用最便宜的层级。单文件的机械性修复也用最便宜的层级。

**任务复杂度信号（实现类任务）：**
- 涉及 1-2 个文件且规格完整 → 便宜模型
- 涉及多个文件且有集成考量 → 标准模型
- 需要设计判断或对代码库的广泛理解 → 最强模型

## 任务循环

你粘进分派提示词里的一切、以及子智能体打印回来的一切，都会在本次会话余下的时间里常驻你的上下文，并且在之后每一轮被重新读一遍。**产物要用文件来交接。**

### 1. 分派实现者

分派之前记录 BASE（`git rev-parse HEAD`）——审查包和各轮修复的 diff 都要用它。

- **任务简报：** 分派实现者之前，运行本技能的 `scripts/task-brief PLAN_FILE N`——它把该任务的完整文本抽取到一个唯一命名的文件并打印路径。组织你的分派，让这份简报保持为需求的唯