execute-plan

执行计划

概述

严格遵循范围、顺序和验证要求，执行已获批准的计划。将计划视为一份持续更新的文档，在执行过程中记录进度、发现、决策和结果。

输入通常为：execute-plan docs/.plans/YYMMDD-HHmm-<plan-slug>/SUMMARY.md

执行过程中不要重新设计计划。如果出现歧义或阻碍，请停止并询问。

工作流

步骤 1：初始化

1. 定位计划

   • 确认计划路径存在且可读取。
   • 如果提供的是目录，请在其中查找 SUMMARY.md。

2. 加载执行上下文

   • 仅加载与计划相关的项目上下文：
     • 如果 docs/SUMMARY.md 存在，请先阅读。
     • 仅加载与任务相关的详细文档。
     • 优先参考 Code Standard 文档中的实现约定。
     • 如果文档与代码或用户意图冲突，请依据现有输入或提问后再进行大范围更改。
   • 查看计划的阶段文件、上下文／方向说明、依赖项、验收标准、幂等性／恢复说明、决策日志和未解决问题。
   • 如果旧计划缺少持续更新计划所需的章节（Progress、Surprises & Discoveries、Decision Log、Outcomes & Retrospective），且计划整体明确，请在执行前补上这些章节。

3. 选择执行模式（明确规则）

   • 默认模式：批处理
   • 满足以下任一条件时，使用 交互式 模式：
     • 高风险更改（身份验证、支付、迁移、安全关键逻辑）
     • 不可逆操作（数据迁移、破坏性脚本）
     • 验收标准不明确
     • 用户明确要求设置检查点
   • 如果模式不明确，请询问一次，并按照用户的选择继续。

4. 查找下一个待处理阶段

   • 查找第一个 [ ] 阶段。
   • 如果没有，则查找第一个 [-] 阶段。
   • 如果没有待处理或进行中的阶段，则进入最终验证。

5. 关键计划合理性检查

   • 确保每个阶段都包含：
     • 明确的目标
     • 目标文件
     • 验证命令
     • 可观察的验收标准
   • 如果缺少可观察的验收标准，但可以根据明确的阶段验证方式和退出标准推断得出，请在执行前将其补入该阶段。
   • 如果缺少关键细节或内容相互矛盾，请停止并请求澄清。

第 2 步：执行各阶段循环

按顺序处理每个阶段：

1. 跳过已完成的阶段

   • 如果状态为 [x]，则继续处理下一阶段。

2. 标记为进行中

   • 在进行更改之前，将阶段状态更新为 [-]。
   • 在 SUMMARY.md 中添加带时间戳的 Progress 条目，描述阶段开始情况。

3. 严格按要求执行

   • 仅实现该阶段定义的任务。
   • 未经批准，不得扩大范围。
   • 编写满足阶段要求所需的最少代码。不要添加推测性功能，不要为只使用一次的代码创建抽象，也不要处理不可能发生的错误场景。参见下方的 Simplicity first 和 Surgical changes 规则。
   • 如果实现过程中发现重大意外，请将其记录在 SUMMARY.md 的 Surprises & Discoveries 下。
   • 如果需要做出决定才能不超出范围，请先在 Decision Log 下记录决定及理由，然后再继续。

4. 验证阶段

   • 运行计划中针对该阶段的验证命令。
   • 至少运行与已修改文件相关的测试和检查。
   • 在 SUMMARY.md 的 Progress 下或该阶段要求的证据位置，简要记录验证证据。

5. 处理失败

   • 如果验证失败：
     • 在该阶段范围内尝试有针对性的修复。
     • 重新运行验证。
   • 如果仍然失败或根本原因超出范围，请停止并报告阻碍因素。

6. 标记为已完成

   • 只有验证通过后，才能将阶段状态更新为 [x]。
   • 添加带时间戳的 Progress 条目，记录验证结果以及该阶段修改的文件。

7. 进度报告

   • 交互模式： 报告进度，并等待确认后再进入下一阶段。
   • 批处理模式： 简要报告后立即继续。

第 3 步：最终验证

所有阶段完成后：

1. 项目级验证

   • 运行完整的 lint 和类型检查套件。
   • 运行所有相关测试（如果计划有要求，则运行完整测试套件）。
   • 如适用，运行构建验证。

2. 稳定化

   • 修复执行过程中引入的回归问题。
   • 重新运行失败的检查，直至全部通过或确认受阻。

3. 人工验证检查点

   • 如果需要用户或人工 QA，请明确提出并暂停：
     • 回复 Verified 表示接受
     • 或提供反馈以进行后续迭代

4. 更新结果

   • 在 SUMMARY.md 中填写 Outcomes & Retrospective，记录最终结果、验证摘要、获批的偏离项以及后续事项。

第 4 步：完成产物

1. 同步文档

   • 如果行为、架构或代码库预期发生变化，请更新 docs 文档。

2. 创建执行报告

   • 文件：docs/.plans/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md
   • 包含下方列出的所有必需章节。

3. 准备最终确认

   • 在获得用户最终确认前，不要归档。用户可能选择 Need verify，执行必须继续使用同一个计划路径。

第 5 步：最终确认关卡

完成产物后，使用输入/提问工具向用户请求最终确认，选项必须严格如下：

• Confirm: End session
• Need verify

根据所选选项执行以下操作：

1. Confirm: End session

   • 将计划文件夹归档到 docs/.plans/archived/。
   • 通知：Execution complete. Report archived at docs/.plans/archived/YYMMDD-HHmm-<plan-slug>/EXECUTION-REPORT.md.
   • 结束执行会话。

2. Need verify

   • 允许用户提供验证反馈或详情。
   • 不要归档。
   • 继续执行循环以处理反馈，然后根据需要重新运行验证并完成后续步骤。

执行报告规范

EXECUTION-REPORT.md 必须使用以下模板：references/execution-report-template.md

规则

• 遵循项目标准：遵循 docs/ 和相关项目文档。
• 严格遵循计划：不得悄然更改范围。
• 遇到阻碍时停止：缺少依赖、指令相互矛盾或出现无法解释的失败时，应停止。
• 不作猜测：不确定时，请求澄清。
• 完成前验证：检查未通过时，绝不标记阶段已完成。
• 持续更新计划：执行过程中，在 SUMMARY.md 中更新进度、发现、决策和结果。重要的执行状态不要只留在聊天记录中。
• 幂等性：优先采用安全且可重复执行的操作。
• 先求简洁：只实现满足阶段退出标准所需的最少代码。不要添加计划未要求的功能。单次使用的代码不要抽象化。不要添加未提出要求的可配置项。如果写了 200 行，而 50 行就能实现，应重写。
• 精准修改：只改动本阶段要求的内容。不要顺手“改进”相邻代码、注释或格式。不要重构未损坏的内容。即使你会采用不同写法，也要遵循现有风格。只有当你的改动导致导入项、变量或函数变得无用时，才删除它们；除非计划有要求，否则不要删除原有的无用代码。每一处改动都必须对应某项阶段任务。
• 使用与当前会话相同的语言编写产物。