anian0/implementation-planning-v2

实施计划 v2

创建执行阶段真正会使用的计划。计划是本流程中最详细的产物：每个任务都必须小、具体、有顺序，并且能用真实证据独立验证。

先读取

计划前读取这些引用：

• ../project-development-v2-common/references/delivery-contract.md
• ../project-development-v2-common/references/no-simulation-policy.md
• references/implementation-planning-confirmation-gates.md
• references/plan-quality-gates.md
• references/implementation-plan-template.md
• 如用户要求评估、审查、进入执行前把关，使用 project-development-review-v2。

核心规则

• 必须从已确认的 tech-design-v2 文档开始。
• 保持可追踪链路：R-* -> A-* -> C-* -> T-* -> V-*。
• 计划阶段必须经过固定确认闸门。闸门确认优先级高于“少问问题”策略。
• 当垂直用户路径任务能降低集成风险时，优先按用户路径拆分。只有依赖关系要求时才按技术层拆分。
• 把隐藏的集成工作显式写进计划。默认不要排除 UI smoke、API 契约或构建验证。
• 计划必须先做覆盖审计，再拆任务。发现需求、验收、页面、服务边界或验证缺口时，先补方案或标记阻塞，不要产出粗计划。
• 计划必须先确认技术方案没有阻塞级审查发现；若技术方案缺少审查记录，先按 project-development-review-v2 的技术方案审查口径做最小审查。
• 计划必须设计统一测试资产目录。所有新增测试、fixture、review 清单和 smoke 脚本必须落到 workplace/<version>/test/ 下，不能散落在源码旁。
• 每个 V-* 必须能追踪到测试文件、验证脚本、UI smoke、手动可观察步骤，或明确 not_verified 风险。
• 计划阶段必须写出关键测试场景和验收内容。后端/API/DB/MCP/diagnostics 任务不能只写“运行测试”，必须给出可执行脚本或 smoke 步骤；前端任务不能只写“检查页面”，必须给出组件/页面测试或逐项 review 清单。
• 技术方案包含 UI、页面或前端状态时，计划必须有前端任务；如果本项目无 UI，必须在 index.md 明确声明。
• 每个任务文件必须自含，不能用“参见 index.md”“参见其他任务”省略目标、契约、测试场景、特别关注点或上下游接口摘要。
• 涉及多服务、前后端、运行链路或数据追踪的需求，必须有最终闭环任务作为放行门槛。
• 每个任务必须包含明确的文件或目录、非目标和验证命令/步骤。
• 每个任务必须包含“执行断言”：从计划步骤中抽取必须消失、必须出现、必须传递、必须落盘的具体代码/文件证据。执行断言要可用 rg、文件存在检查、测试命令或运行日志验证。
• 对删除、替换、参数传递、过滤条件移除、trace/log/metadata 贯通、测试文件落盘等任务，计划不能只写自然语言目标，必须写出残留扫描模式、期望新增路径和失败判定。
• 本阶段不写生产代码。

流程

1. 按 delivery-contract.md 解析真实版本目录；在 workplace/<version>/tech-design/ 找到当前技术方案，或使用用户给定路径。
2. 提取所有 R-*、A-*、C-* 和 V-*。
3. 按 references/plan-quality-gates.md 做覆盖审计，列出需求、验收、页面/API/数据/服务边界、验证方式和缺口。
4. 设计测试资产规划：统一测试目录、测试类型、fixtures、review 清单、全局验证命令和每个 V-* 的落点。
5. 列出每个任务的测试场景表：场景、输入、预期、类型、关联 V-*、测试资产路径。
6. 执行确认闸门 G1：输入理解、覆盖审计、前端覆盖和测试资产规划确认。
7. 检查代码库，确认任务边界和依赖关系可执行。
8. 为每个任务创建执行断言：
   • 必须消失：任务要求移除的循环、过滤、fallback、旧字段、旧调用或旧文件，写出搜索模式和目标文件。
   • 必须出现：任务要求新增的函数、参数、调用、字段、事件、metadata、日志或测试文件，写出搜索模式和目标文件。
   • 必须传递：跨函数/服务/事件链路要传递的字段，写出每个必须经过的函数、调用点或 payload。
   • 必须落盘：计划要求的测试、fixture、review 清单、smoke 脚本，写出精确路径。
   • 验证命令：证明断言成立的命令、脚本或可观察步骤。
9. 创建按顺序执行的 T-* 任务：
   • 一个任务通常对应一次聚焦实现。
   • 混合无关领域、无法清晰验证的任务必须拆分。
   • 无法单独完成或验证的任务应合并。
   • 前端页面、后端服务、数据迁移、运行链路、日志/追踪、最终闭环要拆成可验证任务，不要合并成一个粗任务。
   • 默认顺序：数据/迁移 -> 服务/领域逻辑 -> API/适配器 -> 前端基础 -> 前端页面 -> 集成/闭环。
10. 执行确认闸门 G2：任务拆分、顺序和依赖确认。
11. 每个任务写清：

• 目标。
• 所需上下文。
• 文件/目录。
• 步骤。
• 服务/API/数据/UI 契约和上下游依赖。
• 相邻接口摘要：上游提供什么、下游需要什么。
• 与本任务相关的特别关注点；没有则写“无”。
• 禁止的捷径。
• 验证方式。
• 测试场景表。
• 验收脚本、smoke 步骤或 review 清单内容。
• 测试文件或验证脚本落点。
• 执行断言和残留扫描。
• 完成证据。

12. 如果是 BUGFIX 计划，每个任务补充关联根因、风险点、回退方案和“原缺陷残留扫描”，最后一个任务必须是回归验证。
13. 执行确认闸门 G3：验证方案、最终闭环和执行风险确认。
14. 按 project-development-review-v2 的计划审查口径做交付前自检，确认没有粗任务、漏任务、缺少执行断言、缺少测试资产落点或 mock/fallback 完成路径。
15. 保存计划目录：

• workplace/<version>/plan/YYYY-MM-DD-<slug>/index.md
• workplace/<version>/plan/YYYY-MM-DD-<slug>/T-001-<name>.md
• 每个 T-* 一个任务文件。

16. 输出交接清单，包含计划路径、需求路径、技术方案路径、任务数量、验证数量、测试资产根目录、执行断言数量、前端覆盖、最终闭环和特别关注点。
17. 最终只请求用户确认是否可进入 plan-execution-v2。

任务质量标准

任务必须让另一个 agent 不依赖完整对话也能完成。任务文件要自含，但不能臃肿。

必填字段：

• 追踪：关联的 R-*、A-*、C-*、V-*。
• 目标：一句话目标。
• 文件：具体路径或路径模式。
• 特别关注点：用户强调或技术方案标出的约束；没有则写“无”。
• 步骤：有顺序的实现动作。
• 契约和依赖：本任务提供什么、依赖什么、下游如何消费。
• 相邻接口摘要：上游输入和下游消费的字段、事件、状态或 API 摘要。
• 不要做：捷径和范围边界。
• 测试场景：场景、输入、预期、类型、关联 V-*、测试资产路径。
• 验证：命令和预期证据。
• 验收内容：脚本内容、smoke 步骤或 review 清单内容；不能只写“运行测试”或“检查页面”。
• 测试文件：新增或修改的测试、fixture、review 清单、smoke 脚本位置；不新增时必须写理由。
• 执行断言：必须消失、必须出现、必须传递、必须落盘和对应检查方式。
• 完成标准：精确完成标准。
• 证据日志：留给执行阶段填写。

反模拟计划规则

相关时要显式写入禁止项：

• 不得用静态假数据替代真实 API 响应。
• 不得把 fallback 路径当作主实现。
• 未检查真实渲染路径，不得标记 UI 完成。
• 未运行相关命令或说明 not_verified 风险，不得标记后端完成。

输出标准

使用 references/implementation-plan-template.md。

index.md 必须包含：

• 来源需求和技术方案路径。
• 确认记录。
• 覆盖审计表。
• 执行顺序。
• 带状态的任务表。
• 可追踪矩阵。
• 测试资产规划。
• 前端覆盖声明。
• 最终闭环/放行门槛。
• 全局验证命令。
• 未解决风险或阻塞。
• 交接清单。

每个 T-* 文件都要足够小，可直接用于执行。

交付前自检

检查：

• G1 到 G3 均有确认记录，或明确记录用户要求跳过哪一项及其风险。
• 每个 C-* 至少出现在一个任务中。
• 每个 V-* 至少出现在一个任务或全局验证中。
• 每个需求页面、API、数据实体、服务边界和用户路径都在任务中有落点。
• 技术方案存在 UI 时，至少有前端任务；无 UI 时有明确声明。
• 多服务或前后端需求有最终闭环任务；没有时必须写明为什么不需要。
• 每个任务都有真实验证。
• 每个任务都有执行断言；涉及删除/替换/传递/测试落盘时有可执行的残留扫描或文件存在检查。
• 每个任务都有测试场景表。
• 每个关键验证都有脚本内容、smoke 步骤或 review 清单内容。
• 每个 V-* 都有测试资产、验证脚本、UI smoke 或可观察步骤落点。
• 所有新增测试资产都位于 workplace/<version>/test/ 下的统一目录。
• 计划要求的每个测试资产都有精确文件路径，不只写目录或测试类型。
• 每个任务文件自含，没有用“参见 index.md”或“参见其他任务”省略执行所需信息。
• BUGFIX 计划包含根因、风险、回退方案和回归验证任务。
• 除非明确交付物就是文档、mock、stub 或清单，否则任务不能只靠这些内容完成。
• 计划足够具体，执行时不需要重新发明需求。
• 审查记录中没有未处理的阻塞级发现。