实施计划创建

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

版本号约定

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

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

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

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

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

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

核心变更（共N项）：

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

架构分层：[简述]

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

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

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

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

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

---

第二步：模块拆分讨论

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

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

拆分原则：

• 单模块预计 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

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

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

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

---

第三步：确定模块顺序

输出文档分两层，解决上下文占用和状态追踪：

• 执行索引：紧凑任务表（含状态列）。每次执行只读这一节
• 模块详情：每个模块独立成节。执行某模块时只读对应章节

关键原则：模块级拆分

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

工作流程

1. 从 workplace/1.X/tech-design/ 读取技术方案（含前端设计） → 方案理解确认
2. 模块拆分讨论（与用户讨论拆分策略）
3. 确定模块顺序（默认：数据层 → 服务层 → 接口层 → 前端基础 → 前端页面）
4. 测试场景讨论（逐模块讨论测试场景）
5. 关联验收标准，测试文件位置统一指向 workplace/1.X/test/ 下对应子目录（单元 + 必要集成；不含 e2e）
6. 生成下方模板，提交用户确认
7. 派发 plan-document-reviewer subagent 审查
8. 产出交接清单，进入执行阶段

检查：

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

---

第四步：测试场景讨论

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

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

---

模块M1：[模块名]

建议测试场景：

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

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

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

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

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

---

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

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

---

第五步：关联验收标准

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

# {项目名} 任务清单

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

---

## 执行索引

> **使用方式**：每次执行前只读这个表，找第一个"待执行"模块。
> 开始模块时改为"执行中"，完成后改为"完成"。

| 模块 | 描述 | 层 | 状态 | 前置 | 参考 |
|------|------|----|------|------|------|
| M1 | 数据库迁移与模型 | 后端-数据 | 待执行 | 无 | 技术方案 §2 |
| M2 | 业务服务层 | 后端-服务 | 待执行 | M1 | 技术方案 §1, §2 |
| M3 | REST API 层 | 后端-接口 | 待执行 | M2 | 技术方案 §3 |
| M4 | 前端基础（路由/状态/API 客户端） | 前端-基础 | 待执行 | M3 | 技术方案 §4.1, §4.4, §4.5 |
| M5 | 前端页面 A | 前端-页面 | 待执行 | M4 | 技术方案 §4.2.A |
| M6 | 前端页面 B | 前端-页面 | 待执行 | M4 | 技术方案 §4.2.B |

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

**层标签建议**：`后端-数据` / `后端-服务` / `后端-接口` / `前端-基础` / `前端-页面` / `前端-组件`

---

## 模块详情

> **使用方式**：执行某模块时通过标题跳转，只读该节。

### M1: {模块名称}

**目标**：[一句话]
**层**：[标签]
**前置依赖**：无
**工作目录**：[源码主要落地目录]

**子步骤**（按顺序，不逐步骤审核）：
1. [子步骤1] → 参考 §2.1
2. [子步骤2] → 参考 §2.2

**模块边界与接口契约**：
- 输入：[模块开始前的状态/数据]
- 输出：[模块完成后的交付物]
- 对外接口：[暴露给其他模块的接口/数据结构]

**测试场景**：
| 场景编号 | 场景描述 | 输入 | 预期结果 | 测试类型 |
| T-1 | [具体场景] | [输入数据] | [预期输出] | 单元 |
| T-2 | [边界条件] | [边界输入] | [预期行为] | 单元 |
| T-3 | [异常情况] | [异常输入] | [错误处理] | 单元 |

**测试文件位置**：`workplace/1.X/test/<层>/<类型>/<本模块>/`
- 共享 fixtures：`workplace/1.X/test/fixtures/`
- 不得在源码旁创建测试文件
- 以**单元测试为主**；仅在关键路径（API + 数据库写入）补充集成测试

**验收标准**：
- 测试命令（按本模块所属层选择）：
  - 后端单元：`pytest workplace/1.X/test/backend/unit/<module> -v` 或 `npm test -- workplace/1.X/test/backend/unit/<module>`
  - 后端集成（仅关键模块）：`pytest workplace/1.X/test/backend/integration/<module>`
  - 前端单元：`npm run test:unit -- workplace/1.X/test/frontend/unit/<page>`
  - 前端组件：`npm run test:component -- workplace/1.X/test/frontend/component/<comp>`
  → 全部 PASS
- 覆盖检查：所有测试场景均通过
- 参考：[技术方案 §X](相对路径)

---

### M2: {模块名称}

**目标**：[一句话]
**层**：[标签]
**前置依赖**：M1
**工作目录**：[源码目录]

**子步骤**：
1. [子步骤1] → 参考 §3.1
2. [子步骤2] → 参考 §3.2

**模块边界**：
- 输入：[依赖 M1 的接口/数据]
- 输出：[本模块交付物]
- 对外接口：[暴露给其他模块]

**测试要求**：
- 新增测试目录：`workplace/1.X/test/<层>/<类型>/<本模块>/`
- 不得在源码旁建测试文件

**验收标准**：
- 测试命令：[具体命令] → PASS
- 检查：[检查点]
- 参考：[技术方案 §X](相对路径)

---

## 里程碑（可选，模块数>3 或跨层时使用）

| 里程碑 | 验收点 | 包含模块 |
|--------|--------|----------|
| P1 后端完成 | API 单元/集成测试通过 | M1, M2, M3 |
| P2 前端完成 | 前端单元/组件测试通过 | M4, M5, M6 |

---

第八步：产出交接清单

用户确认后，产出交接清单并宣布进入执行阶段：

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

交接清单：

• 任务清单路径：workplace/1.X/plan/YYYY-MM-DD-xxx.md
• 模块数量：N个（列出编号和名称）
• 前端模块数量：M个
• 测试场景总数：K个
• 特别关注点：[用户强调的内容]

执行时请按模块顺序逐个实施，每个模块完成后运行对应测试。

---

渐进式验证原则

本skill采用渐进式验证，核心原则：

• 分阶段确认：方案理解、模块拆分、测试场景三个阶段分别确认
• 逐模块确认：测试场景讨论采用逐模块确认，避免批量确认遗漏
• 确认内容具体化：列出具体测试场景让用户确认，而非抽象问"是否完整"
• 允许回溯调整：用户不满意时可返回该阶段调整

---

工作原则

• 聚焦编排：不重复技术细节，链接引用技术方案章节
• 按需加载：索引紧凑，详情按章节独立读
• 状态持久：执行后立即更新索引状态并保存
• 验收可执行：每个模块有整体验收标准（测试命令或人工检查点）
• 模块优先：按技术层次/业务模块拆分，单模块 8-16 小时；模块内子步骤不独立审核
• 边界清晰：模块间通过接口契约衔接
• 前后端均覆盖：前端必须独立模块出现
• 测试集中：所有测试统一落在 workplace/1.X/test/，按 backend/frontend/fixtures 分类（不含 e2e 目录）
• 不做 E2E：默认范围只到模块级集成测试
• 讨论先行：模块拆分和测试场景必须与用户讨论确认，不直接生成

特殊情况

• 模块过大：超过 16 小时则拆为子模块（M1-a, M1-b），保持接口契约
• 无测试命令：改为"检查：[人工验收步骤]"，并在 workplace/1.X/test/ 下放手测脚本/checklist
• 简单项目（<3 个模块）：跳过里程碑，精简清单
• 跨模块协调：放入前置模块末尾或单独作微型模块
• 跳过模块：状态可标 跳过，注明原因和受影响下游；下游若依赖被跳过模块的输出，必须更新前置依赖或加替代实现
• 纯后端服务（无 UI）：可不含前端模块，但需在文档开头声明"本项目无前端"，否则审核默认要求前端模块