req-change-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Req Change Workflow

需求变更工作流

Overview

概述

Use a lightweight, repeatable workflow to modify an existing requirement without scope creep or “边改边炸”. Produce clear artifacts at each gate so the user can approve before the implementation starts.

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

Workflow (gated loop)

工作流（阶段式循环）

Follow the steps in order. Do not implement code changes until the user approves Step 4.

按顺序执行以下步骤。在用户批准步骤4之前，请勿进行代码变更。

Step 0: Set the plan (optional but recommended)

步骤0：制定计划（可选但推荐）

Use
```
update_plan
```
to create 5–7 short steps: clarify → baseline → impact → design → implement → validate → document.
Keep exactly one step
```
in_progress
```
at a time and advance as you finish.

使用
```
update_plan
```
创建5-7个简短步骤：澄清→基准确认→影响评估→设计→实现→验证→文档更新。
同一时间仅保留一个步骤处于
```
in_progress
```
状态，完成后再推进到下一个步骤。

Step 1: Clarify the change (lock scope first)

步骤1：澄清变更内容（先锁定范围）

Ask the user for the minimal inputs, then rewrite them into a clear “change brief”:

Target (1 sentence): what outcome changes.
Out of scope (1 sentence): explicitly what must NOT change.
Acceptance criteria (3–6 bullets): observable behaviors that can be verified.
“Must keep” constraints: compatibility, performance, security, no new dependencies, no network, etc.
Rollback expectation: can we revert by reverting a diff, or does it require data migration/backfill?

Use the template in

references/change-brief-template.md

向用户索要必要的最少信息，然后将其改写为清晰的“变更简报”：

目标（1句话）：要改变的结果是什么。
范围外内容（1句话）：明确说明哪些内容绝对不能改变。
验收标准（3-6条）：可验证的可观测行为。
“必须保留”的约束条件：兼容性、性能、安全性、无新依赖、无网络请求等。
回滚预期：我们能否通过回滚代码差异来恢复，还是需要数据迁移/回填？

使用

references/change-brief-template.md

中的模板。

Step 2: Confirm current behavior from code (baseline)

步骤2：从代码中确认当前行为（基准确认）

Do not trust memory or assumptions. Locate the real entrypoints + current data flow and summarize it in 5–10 lines:

UI entrypoints (e.g.,
```
sidepanel/
```
,
```
options/
```
) and where user actions are wired.
Background orchestration (e.g.,
```
service_worker.js
```
).
Core modules (e.g.,
```
src/core/...
```
) and storage (
```
src/core/local/...
```
).
Config/permissions changes (e.g.,
```
manifest.json
```
).

Use

scripts/impact_scan.sh

to quickly find likely files, then read only the necessary ones.

Output artifact: “Current behavior summary” + a short file list (with why each file matters).

不要依赖记忆或假设。找到真实的入口点和当前数据流，并用5-10行内容总结：

UI入口点（例如
```
sidepanel/
```
、
```
options/
```
）以及用户操作的绑定位置。
后台调度逻辑（例如
```
service_worker.js
```
）。
核心模块（例如
```
src/core/...
```
）和存储（例如
```
src/core/local/...
```
）。
配置/权限变更（例如
```
manifest.json
```
）。

使用

scripts/impact_scan.sh

快速找到候选文件，然后仅阅读必要的内容。

产出物：“当前行为总结”+简短的文件列表（说明每个文件的重要性）。

Step 3: Impact + risk assessment (change budget)

步骤3：影响与风险评估（变更范围确认）

Before proposing a new design, list:

Files/modules that must change and why.
Risks: auth/session, storage migration, concurrency, caching, permission scopes, UX regressions.
Testing checkpoints: what to verify manually (use
```
references/regression-checklist.md
```
).
Rollback plan: what is safe to revert; what needs cleanup.

If changes touch

manifest.json

service_worker.js

, require a manual reload step in the validation plan (Chrome extensions cache aggressively).

Output artifact: “Impact & risk list” + “Rollback plan (1–3 bullets)”.

在提出新设计之前，列出以下内容：

必须修改的文件/模块及其原因。
风险：认证/会话、存储迁移、并发、缓存、权限范围、UX回归等。
测试检查点：需要手动验证的内容（参考
```
references/regression-checklist.md
```
）。
回滚计划：哪些内容可以安全回滚；哪些内容需要清理。

如果变更涉及

manifest.json

或

service_worker.js

，需在验证计划中加入手动重新加载步骤（Chrome扩展的缓存机制较强）。

产出物：“影响与风险清单”+“回滚计划（1-3条）”。

Step 4: Propose the new design (get approval)

步骤4：提出新设计方案（获取审批）

Describe the new behavior using:

New flow (bullet sequence) including edge cases.
State model: key states, transitions, and failure recovery.
Change boundaries: what stays unchanged.
Observability: logs/events/UI hints for debugging.

Then ask the user to approve:

The acceptance criteria (Step 1) as final.
The file list (Step 2/3) as the change budget.
The proposed design (this step).

Do not start editing code until the user says “同意/OK/按这个做”.

通过以下内容描述新行为：

新流程（分点说明），包括边缘情况。
状态模型：关键状态、状态转换以及故障恢复机制。
变更边界：哪些内容保持不变。
可观测性：用于调试的日志/事件/UI提示。

然后请求用户审批以下内容：

最终确认步骤1中的验收标准。
确认步骤2/3中的文件列表为变更范围。
确认本步骤提出的设计方案。

在用户回复“同意/OK/按这个做”之前，不要开始编写代码。

Step 5: Implement with minimal, localized diffs

步骤5：以最小化、本地化的代码差异实现

Implementation rules:

Prefer root-cause fixes over patches, but keep diffs small and focused.
Avoid scattering logic across multiple entrypoints; centralize in one module when possible.
Keep ES module imports explicit; avoid implicit globals.
Add short JSDoc for exported functions when introducing new exports.
User-visible logs: actionable Chinese messages (explain what to do next).

If the change involves async flows/cross-module calls/fallbacks, add Chinese comments explaining assumptions and failure handling.

实现规则：

优先选择从根源修复而非打补丁，但要保持代码差异小且聚焦。
避免将逻辑分散到多个入口点；尽可能集中到一个模块中。
明确保留ES模块导入；避免隐式全局变量。
当新增导出函数时，添加简短的JSDoc注释。
用户可见的日志：使用可操作的中文提示信息（说明下一步该做什么）。

如果变更涉及异步流程/跨模块调用/降级处理，添加中文注释说明假设条件和故障处理逻辑。

Step 6: Validate (fixed regression loop)

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

Run the manual pages referenced in
```
references/regression-checklist.md
```
.
If
```
manifest.json
```
or
```
service_worker.js
```
changed: reload the extension before retesting.
Record what you tested and the observed outcome (even if it is manual).

执行
```
references/regression-checklist.md
```
中提到的手动测试项。
如果
```
manifest.json
```
或
```
service_worker.js
```
有变更：重新加载扩展后再进行测试。
记录测试内容和观测结果（即使是手动测试）。

Step 7: Maintain (docs + decision log)

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

Update project docs or inline notes for future maintainers.
Add a short “Decision log” entry: why this design, what alternatives were rejected, and how to roll back.

Use the template in

references/decision-log-template.md

更新项目文档或内联注释，以便后续维护人员参考。
添加简短的“决策日志”条目：选择此设计的原因、被否决的替代方案以及回滚方法。

使用

references/decision-log-template.md

中的模板。

Resources

资源

scripts/

脚本/（scripts/）

```
scripts/impact_scan.sh
```
: fast file candidate scan via
```
rg
```
for keywords + common extension entrypoints.

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

references/

参考文档/（references/）

```
references/change-brief-template.md
```
: input template to lock scope + acceptance criteria.
```
references/regression-checklist.md
```
: manual regression checklist for this repo’s Chrome extension.
```
references/decision-log-template.md
```
: lightweight decision record template.

```
references/change-brief-template.md
```
：用于锁定范围和验收标准的输入模板。
```
references/regression-checklist.md
```
：针对此仓库中Chrome扩展的手动回归检查清单。
```
references/decision-log-template.md
```
：轻量级决策记录模板。