需求变更工作流

概览

使用轻量、可重复的流程修改既有需求，避免范围蔓延或“边改边炸”。在每个关卡产出清晰产物，让用户在实现前逐步确认。

工作流（分步闸门）

按顺序执行。未经用户批准第 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）。

先用 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 小而聚焦。
• 避免把逻辑散落多个入口；尽量在一个模块集中。
• ES Module 导入保持显式；避免隐式全局。
• 新导出函数补充简短 JSDoc。
• 用户可见日志输出可执行的中文提示（说明下一步）。

若涉及异步流程/跨模块调用/回退策略，补充中文注释说明假设与失败处理。

第 6 步：验证（固定回归）

• 执行 references/regression-checklist.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：本仓库 Chrome 扩展的手动回归清单。
• references/decision-log-template.md：轻量决策记录模板。