req-change-workflow

需求变更工作流

概述

使用轻量、可重复的工作流修改现有需求，避免范围蔓延或“边改边炸”。在每个关卡产出清晰的交付物，让用户可以在开始实现前进行审批。

工作流（关卡循环）

按顺序执行以下步骤。用户批准第 4 步之前，不要实现代码变更。

第 0 步：制定计划（可选但建议）

• 使用 update_plan 创建 5–7 个简短步骤：澄清 → 基线 → 影响 → 设计 → 实现 → 验证 → 文档。
• 始终只将一个步骤标记为 in_progress，完成后再推进。

第 1 步：澄清变更（先锁定范围）

向用户询问最少的必要信息，然后将其整理成清晰的“变更简报”：

• 目标（1 句话）：说明要改变什么结果。
• 范围外事项（1 句话）：明确哪些内容绝不能改变。
• 验收标准（3–6 个项目）：列出可观察、可验证的行为。
• “必须保持”约束：兼容性、性能、安全性、不引入新依赖、不联网等。
• 回滚预期：能否通过回退 diff 撤销，还是需要进行数据迁移／回填？

使用 references/change-brief-template.md 中的模板。

第 2 步：通过代码确认当前行为（基线）

不要依赖记忆或假设。找到实际入口点和当前数据流，并用 5–10 行进行总结：

• UI 入口点（例如 sidepanel/、options/）以及用户操作的接线位置。
• 后台编排（例如 service_worker.js）。
• 核心模块（例如 src/core/...）和存储（src/core/local/...）。
• 配置／权限变更（例如 manifest.json）。

对于 Chrome 扩展项目，scripts/impact_scan.sh 可以帮助定位可能涉及的文件。对于其他项目，请使用其实际入口点和搜索工具。然后阅读相关实现，确认当前行为。

输出交付物：“当前行为摘要”＋简短的文件清单（说明每个文件为何重要）。

第 3 步：影响与风险评估（变更预算）

在提出新设计之前，列出：

• 必须变更的文件／模块及原因。
• 风险：身份验证／会话、存储迁移、并发、缓存、权限范围、UX 回归。
• 测试检查点：需要手动验证的内容（使用 references/regression-checklist.md）。
• 回滚计划：哪些内容可以安全回退；哪些需要清理。

如果变更涉及 manifest.json 或 service_worker.js，验证计划中必须包含手动重新加载步骤（Chrome 扩展会积极缓存）。

输出交付物：“影响与风险清单”＋“回滚计划（1–3 个项目）”。

第 4 步：提出新设计（获取批准）

使用以下内容描述新行为：

• 新流程（项目序列），包括边缘情况。
• 状态模型：关键状态、状态转换和故障恢复。
• 变更边界：哪些内容保持不变。
• 可观测性：用于调试的日志／事件／UI 提示。

然后请用户批准：

• 第 1 步中的验收标准，作为最终标准。
• 第 2／3 步中的文件清单，作为变更预算。
• 本步骤提出的设计。

用户说“同意／OK／按这个做”之前，不要开始编辑代码。

第 5 步：以最小化、局部化的 diff 实现

实现规则：

• 优先从根因修复问题，而非打补丁，但要保持 diff 小而聚焦。
• 避免将逻辑分散到多个入口点；尽可能集中到一个模块中。
• 明确编写 ES 模块导入，避免隐式全局变量。
• 引入新的导出项时，为导出函数添加简短的 JSDoc。
• 面向用户的日志应使用可执行的中文提示（说明接下来该怎么做）。

如果变更涉及异步流程、跨模块调用或回退方案，请添加中文注释，说明相关假设和故障处理方式。

步骤 6：验证（固定回归循环）

• 根据实际项目和变更，从 references/regression-checklist.md 中选择自动化和手动检查。记录命令及观察到的结果。Chrome 扩展示例见 references/chrome-extension-regression-example.md。
• 如果 manifest.json 或 service_worker.js 有变更：重新加载扩展后再测试。
• 记录测试内容和观察到的结果（即使是手动测试也要记录）。

步骤 7：维护（文档 + 决策日志）

• 更新项目文档或行内注释，方便未来的维护者。
• 添加一条简短的“决策日志”记录：说明为何采用此设计、否决了哪些替代方案，以及如何回滚。

使用 references/decision-log-template.md 中的模板。

资源

scripts/

• scripts/impact_scan.sh：通过 rg 搜索关键词和常见扩展入口点，快速扫描候选文件。

references/

• references/change-brief-template.md：用于明确范围和验收标准的输入模板。
• references/regression-checklist.md：适用于各类项目的回归检查清单。
• references/chrome-extension-regression-example.md：可选的 Chrome 扩展示例。
• references/decision-log-template.md：轻量级决策记录模板。