anian0/implementation-planning

实施计划创建

将技术方案拆分为模块任务清单，通过链接引用已有文档。

<HARD-GATE> - 技术方案必须已存在 - 计划不重复技术细节，只编排任务顺序 - 必须**同时**覆盖技术方案的后端与前端模块——遗漏前端模块即不合格 </HARD-GATE>

版本号约定

1.X 为占位符，详见 requirements-workshop/SKILL.md。真实路径必须替换为具体数字（如 workplace/1/plan/）。

工作流程总览

| 步骤 | 内容 | 用户确认 | |------|------|---------| | 1 | 读取技术方案 → 方案理解确认 | 必须确认 | | 2 | 模块拆分讨论 | 必须确认 | | 3 | 确定模块顺序 | — | | 4 | 测试场景讨论（逐模块） | 逐模块确认 | | 5 | 关联验收标准（功能点→测试点→验收脚本/审查清单） | — | | 6 | 编写任务清单文档 → 提交用户确认 | 必须确认 | | 7 | 派发 plan-document-reviewer subagent 审查 | — | | 8 | 产出交接清单 | — |

前置检查：

• 无技术方案 → 提示先做 tech-design
• 技术方案缺前端设计 → 回 tech-design 补全
• 计划必须有至少一个前端模块（除非项目无 UI）

---

文档结构原则

产出文档为目录结构，解决上下文占用和状态追踪：

workplace/1.X/plan/YYYY-MM-DD-xxx/
├── index.md               # 执行索引 + 元数据 + 特别关注点 + 映射表
├── M1-数据库迁移与模型.md   # 完全自含的模块详情
├── M2-创建工单API.md
├── M3-工单创建页.md
└── ...

为什么用目录而非单文件：plan-execution 执行时需要"只看当前模块"，单文件内无法物理隔离——agent 读文件时总会看到全部内容。拆成独立文件后，读 index.md 就只知道索引，读 M1-xxx.md 就只有 M1 的上下文，天然隔离。

两层读取：

• index.md：紧凑任务表 + 元数据 + 特别关注点。plan-execution 初始化时只读此文件
• 模块文件：每个模块独立一个 .md，完全自含。执行某模块时只读对应文件

模块文件自含原则：模块文件不得用"参考 index.md"来省略信息——subagent 只能看到这一个文件，必须包含完成该模块所需的全部上下文（包括与该模块相关的特别关注点、相邻模块的接口契约摘要）。

模块级拆分原则：

• 任务按技术模块/业务模块分组，单模块预计 8-16 小时
• 模块边界 = 上下文切换点，模块内连续实现
• 前端必须独立成模块（不与后端混在同一模块）
• 不创建端到端联调模块：本套 skill 默认只到模块级集成测试为止

---

第一步：读取技术方案 + 方案理解确认

从 workplace/1.X/tech-design/ 读取最近的技术方案文档。

• 若不存在：提示用户先做 tech-design 或提供文档路径
• 若有多个：列出最近 3 个让用户选择

读取技术方案后，从文档顶部的"需求文档"路径读取需求文档（用于提取特别关注点等需求层信息）。

提取核心内容后，向用户确认理解：

我已读取技术方案，理解如下：

核心变更（共N项）：

• 后端变更：[摘要，如新增X接口、修改Y模型]
• 前端变更：[摘要，如新增X页面、修改Y组件]
• 数据模型变更：[摘要]

架构分层：[简述]

前端页面清单（共N个页面）：

• [页面列表，标注变更类型]

功能点与测试点（共N个FP，M个TC）：

• 后端脚本功能点：[列出FP编号]
• 前端审查功能点：[列出FP编号]
• 后端脚本测试点：[列出TC编号]
• 前端审查测试点：[列出TC编号]

测试策略：单元为主，关键路径集成

特别关注点：[从技术方案 §10.1 提取用户强调的内容（源自需求文档附录 7.1 节）；若为 BUGFIX 修复技术方案且 §10.1 缺失，则从 BUGFIX 上下文的修复约束提取]

BUGFIX 上下文（若来自 issue-troubleshooting 联动）：

• 根因：[根因摘要]
• 修复约束：[不能破坏的现有行为、兼容性要求]
• 修复策略：[来自模式分析的修复方向]

请确认我的理解是否准确？

等待用户确认后才进入下一步。若用户指出理解偏差，调整理解后重新确认。

---

第二步：模块拆分讨论

与用户讨论拆分策略，而非直接自主拆分：

根据技术方案，我建议按以下策略拆分模块：

拆分原则：

• 单模块预计 8-16 小时
• 模块边界 = 上下文切换点
• 前端独立成模块

建议模块拆分：

| 序号 | 模块名 | 层 | 预估工时 | 主要变更 | |------|--------|----|----------|----------| | M1 | 数据库迁移与模型 | 后端-数据 | 8h | D-1, D-2 | | M2 | 业务服务层 | 后端-服务 | 12h | B-1, B-2 | | M3 | REST API 层 | 后端-接口 | 8h | B-3, B-4 | | M4 | 前端基础 | 前端-基础 | 10h | F-1, F-2 | | M5 | 前端页面A | 前端-页面 | 12h | F-3 |

你认为这个拆分是否合理？

• 是否需要调整模块边界？
• 是否有模块过大/过小需要合并/拆分？
• 是否有特殊依赖需要调整顺序？

等待用户确认后才进入下一步。若用户提出调整，修改拆分策略后重新确认。

---

第三步：确定模块顺序

基于第二步的拆分结果，确定执行顺序。

默认顺序：数据层 → 服务层 → 接口层 → 前端基础 → 前端页面

排序原则：

• 被依赖的模块先执行
• 同层内按业务重要性排序
• 前端模块在后端接口完成后执行

---

第四步：测试场景讨论

逐模块讨论测试场景，而非仅指定测试命令：

现在讨论每个模块的测试场景：

---

模块M1：[模块名]

建议测试场景：

| 场景编号 | 场景描述 | 输入 | 预期结果 | 测试类型 | |----------|----------|------|----------|----------| | T-1 | 正常创建 | 有效数据 | 成功返回 | 单元 | | T-2 | 边界条件-空输入 | 空 | 验证失败 | 单元 | | T-3 | 异常-重复创建 | 已存在数据 | 错误提示 | 单元 |

测试文件位置：workplace/1.X/test/<层>/<类型>/<本模块>/

你认为这些测试场景是否覆盖了关键功能？

• 是否有遗漏的业务场景？
• 是否有边界条件需要补充？

[用户确认后继续下一模块]

---

模块M2：[模块名]...

每个模块确认后才继续下一模块。若用户提出补充场景，添加到测试场景表后重新确认。

---

第五步：关联验收标准

基于技术方案的功能点清单（FP-N）和测试点清单（TC-N），为每个模块创建验收标准。

核心原则：

• 每个任务模块对应一组功能点
• 每个功能点有且只有一种验收方式：后端py脚本 或 前端subagent审查清单
• 计划阶段必须编写具体的验收脚本或审查清单内容
• 基础设施模块（无对应功能点，如数据库迁移、项目骨架）使用 TC-0 编号，验收脚本验证基础结构而非业务功能

关联流程：

1. 按模块映射功能点：从技术方案的功能点清单中，将每个 FP-N 分配到对应模块
2. 解析测试点路径占位符：将技术方案测试点清单中的 {module} 占位符替换为当前模块编号（如 M1、M2），确保验收脚本路径与模块对应。注意：目录中的 {module} 保持模块编号大小写（如 M1、M2），文件名中的 {module} 转为小写（如 m1、m2）
3. 逐模块编写验收标准与接口契约：
   • 后端模块：编写 py 验收脚本（含 assert 语句），覆盖该模块所有 FP-N 对应的 TC-N。脚本须可直接运行、输出 M{N} ALL PASS
   • 前端模块：编写审查清单（含逐项勾选框），覆盖该模块所有 FP-N 对应的 TC-N。每项须描述具体操作与预期结果；此外标注前端测试文件目录（单元/组件测试至少一类，前端模块必备）
   • 接口契约：为每个模块定义"提供"（本模块暴露给下游的接口/数据）和"依赖"（本模块消费的上游接口/数据），来源为技术方案的 API 设计、数据模型、前端设计章节。计划执行阶段 implementer 和 module-reviewer 均需要此信息
4. 确认覆盖完整性：核对功能点-模块映射表，确保每个 FP-N 和 TC-N 都有对应的验收标准

---

第六步：编写任务清单文档 + 用户确认

按「任务清单模板」编写任务清单文档，完成后提交用户确认。

文件路径：workplace/1.X/plan/YYYY-MM-DD-{项目名}-任务清单/（目录）

生成以下文件：

1. index.md — 执行索引 + 元数据 + 特别关注点 + 功能点映射表
2. M{N}-{模块名}.md — 每个模块一个文件，完全自含

任务清单已编写完成，保存至 [路径]。请确认：

• 模块拆分是否与之前讨论一致？
• 验收标准是否覆盖所有功能点？
• 依赖关系是否正确？

等待用户确认后才进入下一步。

---

第七步：subagent 审查

读取 references/plan-document-reviewer-prompt.md，将 [PLAN_FILE_PATH] 和 [TECH_DESIGN_FILE_PATH] 替换为实际路径后派发 subagent。

| 状态 | 处理 | |------|------| | 通过 | 进入第八步 | | 发现问题 | 修复后无需重审 |

---

第八步：产出交接清单

审查通过后，产出交接清单并宣布进入执行阶段：

任务清单已完成并确认。进入执行阶段时请携带以下信息：

交接清单：

• 任务清单路径：workplace/1.X/plan/YYYY-MM-DD-xxx/（目录，含 index.md 和各模块文件）
• 需求文档路径：workplace/1.X/requirements/YYYY-MM-DD-xxx.md
• 技术方案路径：workplace/1.X/tech-design/YYYY-MM-DD-xxx.md
• 模块数量：N个（列出编号和名称）
• 功能点总数：K个（列出FP编号）
• 后端脚本测试点：X个（列出TC编号）
• 前端审查测试点：Y个（列出TC编号）
• 变更项数量：后端A项、前端B项、数据模型C项（列出编号）
• 特别关注点：[从技术方案 §10.1 提取（源自需求文档附录 7.1 节）；若为 BUGFIX 方案且 §10.1 缺失，则从修复约束提取]

执行时请按模块顺序逐个实施，每个模块完成后运行对应验收脚本或委派subagent审查。 只需读 index.md 获取索引，执行某模块时只读对应的 M{N}-xxx.md 文件。

---

任务清单模板

产出为目录结构，包含一个索引文件和若干模块文件。

index.md 模板

# {项目名} 任务清单

**目标**：[一句话]
**技术方案**：[技术方案文档路径]
**需求文档**：[需求文档路径]

---

## 确认记录

> 记录关键步骤的用户确认情况。

| 步骤 | 确认内容 | 状态 |
|------|---------|------|
| 方案理解确认 | 已确认对技术方案核心变更、功能点、测试点的理解 | ✅ |
| 模块拆分确认 | 已确认模块划分、顺序、边界 | ✅ |
| 任务清单确认 | 已确认任务清单完整性、验收标准覆盖、依赖关系正确 | ✅ |

---

## 执行索引

> **使用方式**：每次执行前只读本文件，找第一个"待执行"模块。
> 开始模块时改为"执行中"，完成后改为"完成"。
> 执行某模块时，只读对应的 `M{N}-xxx.md` 文件。

| 模块 | 描述 | 对应功能点 | 对应测试点 | 状态 | 前置 | 验收方式 | 对应变更项 | 模块文件 |
|------|------|-----------|-----------|------|------|---------|----------|----------|
| M1 | 数据库迁移与模型 | — | TC-0 | 待执行 | 无 | 后端脚本 | D-1 | M1-数据库迁移与模型.md |
| M2 | 创建工单API | FP-1, FP-2, FP-3 | TC-1, TC-2, TC-3 | 待执行 | M1 | 后端脚本 | B-1, B-2, B-3 | M2-创建工单API.md |
| M3 | 工单创建页 | FP-4, FP-5, FP-6 | TC-4, TC-5, TC-6 | 待执行 | M2 | 前端审查 | F-1, F-2 | M3-工单创建页.md |

**状态值**：`待执行` / `执行中` / `完成` / `跳过`

---

## 特别关注点

> 用户强调的约束、风险或偏好，执行过程中务必注意。

- [各关注点，来自技术方案 §10.1 的"特别关注点"（源自需求文档附录 7.1）；若为 BUGFIX 方案且 §10.1 缺失，则从修复约束提取]

---

## 功能点-模块映射表

| 功能点 | 所属模块 | 测试点 | 验收方式 |
|--------|---------|--------|---------|
| FP-1 | M2 | TC-1 | 后端脚本 |
| FP-2 | M2 | TC-2 | 后端脚本 |
| FP-3 | M2 | TC-3 | 后端脚本 |
| FP-4 | M3 | TC-4 | 前端审查 |
| FP-5 | M3 | TC-5 | 前端审查 |
| FP-6 | M3 | TC-6 | 前端审查 |

> 执行状态以"执行索引"表的模块状态列为准，本表只做覆盖完整性核查。

**核查规则**：技术方案中的所有功能点必须在本表中出现，任一遗漏即不合格。

M{N}-xxx.md 模板（每个模块一个文件）

# M{N}: {模块名}

**目标**：[一句话]

**对应功能点**：[FP-N 列表，或"无（基础设施模块）"]

**对应测试点**：[TC-N 列表，或 TC-0]

**对应变更项**：[变更编号列表]

**源码目录**：`src/xxx/`（参考技术方案 §X）

**前置模块**：[M{N-1} 等，或"无"]

**接口契约**：
- 提供：[本模块暴露给下游的接口/数据，格式和字段名必须精确]
- 依赖：[本模块消费的上游接口/数据，包括来源模块编号和接口格式]

**相邻模块接口摘要**（供审核 subagent 做边界检查）：
- 上游模块 M{N-1} 提供：[接口/数据格式摘要]
- 下游模块 M{N+1} 需要：[本模块须提供的接口/数据格式]

**子步骤**：
1. [子步骤1] → 参考技术方案 §X.X
2. [子步骤2] → 参考技术方案 §X.X
3. ...

**验收标准**：
- 验收方式：[后端脚本 / 前端审查]
- 验收脚本/清单路径：`workplace/1.X/test/...`

[后端模块示例]
```
# m{N}_test.py - 计划阶段编写
[完整的验收脚本代码，含 assert 语句]
```
- 验收命令：`python workplace/1.X/test/...`
- 通过标准：输出 `M{N} ALL PASS`

[前端模块示例]
- 审查清单：`workplace/1.X/test/review/m{N}_checklist.md`
- 前端测试文件：`workplace/1.X/test/frontend/...`（前端模块须含单元/组件测试至少一类）

```markdown
# M{N} 前端审查清单
## TC-X: FP-X [场景描述]
- [ ] [具体操作与预期结果]
...
```
- 验收方式：委派 subagent 按清单逐项检查
- 通过标准：清单全部勾选

**特别关注点**（与本模块相关的）：
- [从 index.md 的"特别关注点"中筛选与该模块相关的条目；若无则写"无"]

自含校验：写完每个模块文件后，确认该文件包含 subagent 完成该模块所需的全部信息。如果发现某项信息写成了"参见 index.md"，必须将实际内容内联到此文件中。

---

特殊情况

• 模块过大：超过 16 小时则拆为子模块（M1-a, M1-b），保持接口契约
• 无测试命令：后端模块仍须写 py 验收脚本（可简化为仅调用接口验证返回值）；前端模块写审查清单替代
• 简单项目（<3 个模块）：跳过里程碑，精简清单
• 跨模块协调：放入前置模块末尾或单独作微型模块
• 跳过模块：状态可标 跳过，注明原因和受影响下游；下游若依赖被跳过模块的输出，必须更新前置依赖或加替代实现
• 纯后端服务（无 UI）：可不含前端模块，但需在文档开头声明"本项目无前端"，否则审核默认要求前端模块
• BUGFIX 计划（来自 issue-troubleshooting 联动）：每个模块名加 [BUGFIX] 前缀；每个模块详情额外包含"关联根因"、"风险点"、"回退方案"三个字段；最后一个模块为"回归验证"（运行全量测试+验证原bug已修复+检查关联功能）

关联 skill

| Skill | 关系 | |-------|------| | tech-design | 本 skill 的输入来源：读取技术方案的功能点/测试点/变更清单 | | plan-execution | 本 skill 的下游：任务清单确认后，由 plan-execution 按模块执行开发 | | issue-troubleshooting | 修复规模大时联动：创建 [BUGFIX] 修复计划，增加回归验证模块 |