planning

规划技能

何时使用

当用户要求制定计划、路线图、将规范拆解为实现任务，或希望记录决策时，使用此技能。

模式

选择满足需求的最简模式。

quick-plan

适用于：

• 任务规模较小或中等，且不会造成破坏性变更
• 不涉及迁移或多阶段推出

输出：

• 3–8 个工作项（WI-###），每项包含测试和验收标准

full-plan（默认）

适用于：

• 迁移／持久化变更
• API／契约变更（公开工具、架构、SDK）
• 多阶段路线图
• 对性能敏感的工作

输出：

• 结构化计划章节（参见“计划文件模板”）

流程

1. 明确目标

   • 重述期望行为和约束。
   • 找出模糊之处；如果用户未作决定，则提出默认方案。
   • 记录约束与依赖（运行时版本、操作系统、外部服务、功能标志、必需工具）。
   • 记录差距：列出此步骤中发现的需求／行为差距或尚未作出的决策。

2. 梳理当前行为

   • 追踪入口点 → 状态／存储 → 副作用 → 持久化。
   • 列出关键文件／模块及其依赖的不变量。
   • 注意所有权／优先级规则（窗口、工作区、文件）。
   • 记录差距：列出当前行为与既定目标不一致之处。

3. 定义目标规则

   • 将目标转化为明确的规则和优先级。
   • 每条规则都应包括：触发条件／上下文、预期行为、范围、约束和排除项。
   • 边缘情况检查：涵盖空值／无值、无效／格式错误、边界大小、状态冲突、多界面协调、持久化／恢复以及 I/O 故障。
   • 记录差距：列出缺少实现支持或与当前行为冲突的规则。
   • 创建决策日志：
     • 决策、考虑过的选项、理由，以及拒绝其他方案的原因。
   • 创建待解决问题列表：
     • 影响正确性的问题、决策人，以及未作决定时采用的默认方案。

4. 组织计划

   • 拆分为工作项（WI-###），每项包含：
     • 目标
     • 验收标准（可衡量）（视情况涵盖正确性、性能和 UX）
     • 测试（优先编写）（文件名和测试意图；按需使用单元／集成／端到端测试）
     • 涉及范围（文件路径及关键函数／类／符号）
     • 依赖项（其他 WI、外部工具／服务）
     • 风险与缓解措施
     • 回滚策略
   • 添加优先级和估算（S/M/L），并明确 WI 之间的顺序／依赖关系。
   • 记录差距：将每项差距对应到至少一个 WI（或标记为“超出范围”）。
   • 计划检查（必需）：
     • 包含所有章节（目标、约束、当前行为、目标规则、工作项、测试）。
     • WI 编号连续且引用一致。
     • 每个 WI 都包含测试和验收标准。

5. 编写计划文件

   • 如果此技能附带 templates/TEMPLATE.md，则使用其中的模板；否则遵循上述结构。
   • 将计划写入 dev-docs/plans/YYYYMMDD-HHMM-<topic>.md。
   • 始终报告已保存的计划路径。

测试要求

• 每个 WI 都必须明确列出在实现前编写的测试（文件名和测试意图）。
• 如果无法编写测试，请明确说明，并提出能支持测试的最小接缝。
• 在计划中加入“测试流程”章节，列出必需的命令及运行时机。
• 计划末尾附上简短的“手动测试检查清单”。

验收标准指南

验收标准必须可衡量且可验证：

• 好：“搜索为每个结果返回包含 locator_v1 的 v1 架构（单元测试）。”
• 不好：“搜索体验更好。”

计划 → 验证交接（必需）

在计划末尾加入：

• 每个 WI 需要收集的证据（测试、日志、手动步骤）。
• 所需的任何测试夹具或样本数据。

迁移 / 持久化要求（如适用）

如果计划会更改任何持久化内容（数据库、磁盘缓存、配置文件、客户端会存储的 API）：

• 添加 数据模型 部分（表 / 列 / 键、版本）。
• 添加 迁移计划：
  • 正向迁移步骤
  • 回滚步骤
  • 兼容性保证（旧客户端与新服务端）
• 添加 不变量 + 验证查询（迁移后需要检查的内容）。
• 如有需要，添加 回填 / 重建索引策略。

可观测性要求（如适用）

如果计划涉及索引 / 搜索 / 对性能敏感的路径：

• 定义指标（延迟、吞吐量、内存、数据库大小增长）。
• 定义日志的位置，以及如何启用详细跟踪。
• 添加验收阈值（例如，“在机器 Y 上，索引 1000 篇文档用时 < X 分钟”）。

发布要求（如适用）

如果行为变化会影响用户可见内容或存在风险：

• 添加 发布计划（功能标志、分阶段启用、默认关闭还是默认开启）。
• 定义“紧急停止开关”的触发条件，以及如何快速回退。

输出要求

• 始终生成计划文件，并在回复中注明其路径。
• 只有在会改变规则时，才最多提出 1–2 个澄清问题。