---
name: implement-spec
description: 由多个子代理并行完成整份规格，在磁盘记录进度并最终统一评审，交付整份规格的 PR 或在本地完成。少量任务在当前会话完成时使用 implement。
disable-model-invocation: true
---

你拿到了一份规格，以及实现它的开发任务。目标是实现整份规格，并按开始时与用户确认的方式交付：整份规格一个 PR，或只在本地分支完成。

issue 追踪器配置应该已经提供给你；如果没有，告诉用户运行 `/setup-dev-skills`。

## 角色

你是**协调者**。实现、合并和评审都交给子代理完成。你的上下文留给协调工作：阅读报告、作出代行决策、更新进度记录、派发当前可执行的任务。亲自修改代码会占用你的上下文。

与子代理的沟通尽量精简，主要使用**上下文指针**：指向规格、任务、进度记录、报告文件和之前的提交。

- 指针能提供的信息，不在派发提示中重复。
- 不要把前面任务的历史摘要贴进后续派发。
- 你贴进提示的内容和子代理打印回来的内容都会一直占用你的上下文，所以产物以文件形式交接。

## 按依赖关系调度任务

任务之间有前置依赖，因此任何时刻都有一组**当前可执行任务**：前置依赖都已完成、现在就能领取的任务。这些任务并行推进，以获得**最大并行度**。一项任务完成后，可执行任务集合会变化，立即为新解锁的任务派出实现者。

并行的前提是互不干扰：

- 每个实现者在**自己的工作树**和分支上工作，分支基于集成分支的当前头部。工作树的检测、创建和依赖安装见 `implement` skill 目录下的 [WORKTREE.md](../implement/WORKTREE.md)。
- 两项可执行任务会修改同一个模块或同一个接口时，改为串行：先完成一项并合并，再派发另一项。

### 同类小改动合并派发

每派发一次，子代理都要重新建立上下文并运行测试。几项当前可执行任务都是同一种小改动时（在多个文件中做同样的一行修复、修改同一个常量、添加同一个字段），把它们合成**一个批次**，只派发一次：

- 派一个实现者，派发提示列出批次中每项任务的指针，以及每个文件要做的改动。
- 批次在一个工作树和分支上完成，合并后批次中每项任务各写一行完成记录。
- 把这次合批作为代行决策写入进度记录。

需要独立判断、独立测试的任务，保持一项任务派发一次。

## 自行决策，不停下等待

规格执行期间不等待用户回复。遇到冲突、歧义、任务缺陷或需要突破的上限时，由你决定。

- **规格是最终依据**，任务是对规格的拆解。功能清单和设计依据是规格的依据文档，同样以它们为准。
- 规格和任务都没有回答的问题，由你判断。

每个代行决策都写入进度记录：

```
决策：<决定了什么> | 理由：<为什么> | 如果错了：<会造成什么影响>
```

然后继续推进。错误决策造成的返工，用户能看到、也能纠正；停在一个问题上等回复，会浪费用户一整天。

只有以下五类情况需要停下来询问用户：

1. 不可逆或破坏性操作
2. 安全敏感操作
3. 当前工作树之外、按惯例需要先询问的副作用（推送到受保护共享分支、直接发布），开始时已获授权的除外（见“准备”第 4 步）
4. 任务或规格缺陷严重，任何推进方式都只能靠猜测
5. **缩减范围**：把功能项改为“不做”、删掉某个状态或把它移到更晚的批次、页面做得达不到设计依据。这类改动会让交付物缺功能，只能由用户决定，不能作为代行决策

增加范围可以作为代行决策：发现漏掉的功能项或状态时，补进对应任务，写入进度记录后继续。

## 准备

1. **阅读规格和任务。** 读到足以理解任务依赖关系即可：每项任务的标题、前置依赖、验收标准，以及规格的全局约束和依据文档。无需读入每项任务的细节，实现者会阅读自己负责的任务。

2. **进度记录。** 进度记录用于在上下文压缩或会话中断后恢复状态，格式见 [LEDGER.md](LEDGER.md)。
   - 路径：`<仓库根>/.dev-skills/implement-spec/<规格-slug>/ledger.md`，并确保 `.dev-skills/` 被 git 忽略。
   - 已有进度记录且第一行指向这份规格时，从记录恢复：已标为完成的任务不再派发，根据进度记录和 `git log` 重建状态。两者与你的记忆不一致时，以它们为准。
   - 第一行指向其他规格时，那是另一份规格的进度。保持原样，为当前规格新建记录。

3. **预检。** 派发第一项任务之前，检查任务之间的依赖与约束，边检查边写入进度记录：
   - 任务依赖拓扑：检查是否存在循环依赖、是否存在遗漏前置任务或不合理的顺序
   - 与规格全局约束或已商定测试接缝矛盾的任务
   - 任务的验收标准是否清晰且可独立验证
   - 若项目维护了功能清单，对照核实当前批次范围是否有缺口；缺口按增加范围处理，补建任务并写入进度记录

   预检的输出是进度记录中的一张表，不是一句“没问题”。每发现一个冲突，就当场作出代行决策并记录，然后开始执行。

4. **分支与交付确认。** 与用户确认一次交付方式：
   - **一份规格一个 PR**（默认推荐）：新建集成分支并创建草稿 PR（注明关闭规格 issue 和任务 issue），所有任务合并到集成分支，最后统一评审。
   - **只在本地分支完成**：不推送远端，在集成分支完成全部实现，最后使用 `finish-work` skill。

   确定交付方式后，在集成分支运行一次完整测试套件作为基线，结果写入进度记录。基线失败时的处理见 [WORKTREE.md](../implement/WORKTREE.md) 第 3 步。

5. **可选：探索子代理。** 任务需要大量探索（相关代码文件、外部文档）时，派一个探索子代理，把 Markdown 笔记写到仓库外、所有后续子代理都能访问的目录，供后续实现者参考。

## 每项任务的循环

### 1. 派发实现者

记下 BASE（集成分支当前头部的 SHA）。按 [WORKTREE.md](../implement/WORKTREE.md) 为这项任务创建基于 BASE 的工作树和分支并安装依赖，然后派发实现者。提示按 [IMPLEMENTER-PROMPT.md](IMPLEMENTER-PROMPT.md) 填写：

- 任务指针（链接或路径），作为实现需求
- 全局约束与依据文档指针
- 前面任务已完成的相关模块、测试接缝与已有决策
- 报告文件路径：`<进度记录目录>/ticket-<NN>-report.md`

**能力选择：** 根据任务难度选择合适的能力等级：

| 工作                                       | 能力等级               |
| ------------------------------------------ | ---------------------- |
| 任务已写清完整行为，只涉及一两个文件       | 快速、低成本           |
| 需要协调多个文件，或需要参照已有模式作判断 | 标准                   |
| 涉及核心架构、复杂并发或最终整分支综合评审 | 高                     |
| 重试第 3 轮                                | 比卡住的档位至少高一档 |

### 2. 处理报告与自测结果

实现者负责自测与 TDD 验证，完成后向报告文件写入实现细节与测试证据，并向协调者返回简短状态：

| 状态                   | 处理方式                                                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **DONE**               | 核对报告已包含改动摘要与通过的测试命令，准备合并                                                                              |
| **DONE_WITH_CONCERNS** | 阅读顾虑。涉及正确性或范围的，解决后再合并；仅为观察建议的，写入进度记录备查，继续合并                                        |
| **NEEDS_CONTEXT**      | 补充缺少的上下文，重新派发                                                                                                    |
| **BLOCKED**            | 判断原因：缺上下文就补充；能力不足就升配；任务缺陷就作出代行决策写入进度记录后重新派发。重试规则见 [FIX-LOOP.md](FIX-LOOP.md) |

### 3. 合并到集成分支

任务完成且自测通过后，派一个**合并子代理**（或在无冲突时直接合并），把任务分支合入集成分支：

- 遇到冲突时，使用 `resolving-merge-conflicts` skill。
- 合并后在集成分支运行与该改动相关的测试套件，确保无集成回归。
- 集成测试失败时，派发实现者针对失败进行修复。

合并成功后，记录进度：

```
任务 NN：完成（提交 <base7>..<head7>）
```

然后更新追踪器上的任务状态，删除该任务对应的工作树。

### 4. 派发新解锁的任务

合并会改变当前可执行任务集合：立即为新解锁的任务派出实现者，维持最大并发度。

**等待子代理时**：有本地工作（更新进度记录、阅读已完成报告）就继续做。空闲时，等待后台通知，避免盲目轮询；定期清点运行中的子代理状态。

## 最终评审与收尾

所有任务合并到集成分支后，进行全量把关：

1. **整分支代码评审**：使用 `code-review` skill，比较基准是集成分支的起点提交，规格来源是本规格，使用高能力等级。把进度记录中所有代行决策和观察顾虑提供给评审。
2. **集中修复**：评审发现严重或重要问题时，派**一个**修复子代理集中处理，提供完整发现清单。修复完成后只进行**一次**聚焦复审。达到上限仍有争议的问题，按 [FIX-LOOP.md](FIX-LOOP.md) 作出代行决策。
3. **完成验证**：使用 `verifying-completion` skill，确认完整测试套件全部通过，验收标准均已满足，规格关键路径验证闭环。

## 交付与清理

1. **汇报代行决策**：整理进度记录中每一条决策与“如果错了”的影响，在最终总结中完整列出。这是代替用户作出的决策透明传达给用户的途径。
2. **汇报成果**：列出完成的任务，以及需要用户最终体验验收的事项。
3. **交付**：已创建草稿 PR 的，将 PR 标为可评审（Ready for review）；只在本地分支完成的，使用 `finish-work` skill。
4. **清理**：删除所有任务工作树。保留进度记录供用户核对，用户确认后可归档删除。

## 常见借口与对应事实

| 借口                     | 事实                                                                   |
| ------------------------ | ---------------------------------------------------------------------- |
| “我自己修一下更快”       | 协调者亲自修改代码会占用主上下文并破坏任务状态隔离。派子代理处理。     |
| “这个状态不重要，先不做” | 删减状态就是缩减范围，只能停下来由用户决定。                           |
| “差不多符合任务要求了”   | 验收标准未满足就是未完成，自测失败不得合并。                           |
| “再来一轮就能收敛”       | 超过重试上限的循环往往存在结构性分歧，应果断作出代行决策或升配。       |
| “写进度记录太麻烦”       | 进度记录是上下文压缩后唯一的持久化依据。没有它，协调者会丢掉全局状态。 |