| name | req-change-workflow |
| description | 将现有代码库（尤其是 Chrome 扩展）的需求/功能变更标准化，把 “改需求/需求变更/调整交互/改功能/重构流程”转成可重复的流程：明确验收标准、从代码确认现状、 评估影响/风险、设计新逻辑、用小差异实现、跑固定回归清单、更新文档/决策记录。 适用于用户感觉变更流程混乱、改动容易蔓延到多个文件， 或涉及 manifest/service worker/OAuth/存储/UI 且需要可靠验证与回滚规划的场景。
|
需求变更工作流
概览
使用轻量、可重复的流程修改既有需求，避免范围蔓延或“边改边炸”。在每个关卡产出清晰产物，让用户在实现前逐步确认。
工作流（分步闸门）
按顺序执行。未经用户批准第 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：轻量决策记录模板。
