cs-refactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

cs-refactor

AI 自己重构代码有两个稳定的失败模式：一是不知道模块的真实需求和约束，改出来的东西功能不等价；二是一次吞掉的范围超过上下文承载，改到后面忘了前面的约束。这条流程在"想优化"和"动手改"之间塞了一份扫描清单 + 方法库，让 AI 只接自己能稳定做对的活，剩下的老实停下来让路。

整套流程：

scan（扫出优化点清单）→ design（和用户定做哪几条、按什么顺序）→ apply（逐条执行，每步人工放行）

核心纪律：行为等价是底线。一旦这次动作会改变外部可观察行为，不走 refactor，走 feature（需求变）或 issue（bug 修）。

AI has two consistent failure modes when refactoring code independently: first, it lacks awareness of the module's actual requirements and constraints, leading to functionally inequivalent modifications; second, it takes on a scope that exceeds the context capacity, forgetting earlier constraints as it proceeds. This process inserts a scan checklist + method library between "wanting to optimize" and "starting to modify", allowing AI to only undertake tasks it can reliably complete correctly, and pause honestly for the rest.

Full process:

scan (generate optimization point checklist) → design (confirm which items to implement and the order with the user) → apply (execute item by item, with manual approval for each step)

Core Discipline: Behavioral equivalence is the bottom line. If an action will alter externally observable behavior, do not use the refactor workflow; route to feature (requirement change) or issue (bug fix).

Fastforward 模式（小重构走这里）

Fastforward Mode (use for small refactors)

改动明显很小——单函数、单组件、1-3 处优化、有测试可自证、不需要 HUMAN 目视——走完整三阶段太重。触发

cs-refactor-ff

：AI 直接识别、一次对齐、原地改、跑测试自证，不产出 scan / design / checklist。

触发信号：用户说"小重构"、"快速重构"、"简单优化下 XX 函数"、"直接改"、"别那么多步骤"。

什么时候别走 fastforward：

改动跨 > 1 个文件
预计动点超过 3 处
需要目视验证（前端效果、性能感知）
改到公开接口（要走 Parallel Change）
没有测试覆盖
跨模块

遇到这些就劝用户走标准流程。fastforward 开干后发现变复杂，切回完整流程从 scan 开始。

When changes are obviously minor — single function, single component, 1-3 optimization points, self-verifiable with tests, no need for human visual inspection — going through the full three stages is overkill. Trigger

cs-refactor-ff

: AI directly identifies, aligns once, modifies in-place, runs tests for self-verification, and does not produce scan / design / checklist.

Trigger signals: Users say "small refactor", "quick refactor", "simply optimize XX function", "modify directly", "skip the steps".

When not to use fastforward:

Changes span > 1 file
Expected modification points exceed 3
Requires visual verification (frontend effects, performance perception)
Modifies public interfaces (needs to use Parallel Change)
No test coverage
Cross-module

In such cases, advise users to follow the standard process. If fastforward starts and the task becomes complex, switch back to the full process starting from scan.

文件放哪儿

Where to place files

refactor 产物聚在

codestable/refactors/

下，每次独立目录：

codestable/
└── refactors/
    └── {YYYY-MM-DD}-{slug}/
        ├── {slug}-scan.md              ← 阶段 1 产出的优化点清单
        ├── {slug}-refactor-design.md   ← 阶段 2 的执行方案（选哪几条、顺序、验证）
        ├── {slug}-checklist.yaml       ← 阶段 2 生成，阶段 3 推进
        └── {slug}-apply-notes.md       ← 阶段 3 的执行记录（每步做了什么、验证结果、偏离）

目录命名和 feature / issue 一致：

YYYY-MM-DD-{英文 slug}

，日期是首次创建当天、定了不动；slug 用小写字母数字连字符，短到能一眼看出改的是什么（

user-form-split

、

export-perf

这种）。

为什么单独开目录而不是混进 features/：refactor 产物是"代码当前状态的扫描 + 执行记录"，时效性强，价值随时间衰减；feature 产物是"这个能力为什么这样设计"，时效性弱。归档逻辑不一样，混一起后面找不到。

Refactor outputs are gathered under

codestable/refactors/

, with an independent directory for each refactor:

codestable/
└── refactors/
    └── {YYYY-MM-DD}-{slug}/
        ├── {slug}-scan.md              ← Optimization point checklist generated in Stage 1
        ├── {slug}-refactor-design.md   ← Execution plan from Stage 2 (selected items, order, verification)
        ├── {slug}-checklist.yaml       ← Generated in Stage 2, used to advance Stage 3
        └── {slug}-apply-notes.md       ← Execution records from Stage 3 (what was done in each step, verification results, deviations)

Directory naming aligns with feature / issue:

YYYY-MM-DD-{english slug}

, the date is set on the day of first creation and remains unchanged; slug uses lowercase letters, numbers, and hyphens, short enough to clearly indicate what is being modified (e.g.,

user-form-split

export-perf

Why use a separate directory instead of mixing with features/: Refactor outputs are "scans + execution records of the current code state", which are time-sensitive and their value decays over time; feature outputs are "why this capability is designed this way", which have weak timeliness. The archiving logic is different, so mixing them will make it hard to find content later.

三个阶段

Three Stages

阶段	子流程	产出	谁主导
1 scan	扫出优化点清单	{slug}-scan.md	AI 扫代码 + 做前置检查，用户勾选
2 design	定执行方案	{slug}-refactor-design.md + {slug}-checklist.yaml	AI 起草，用户整体 review
3 apply	逐条执行	代码改动 + {slug}-apply-notes.md	AI 执行，每步人工放行

阶段之间有 checkpoint。scan 的清单用户不勾选不进 design；design 用户不放行不动代码；apply 里标了 HUMAN 验证的条目人不点头不推进下一步。

Stage	Sub-process	Output	Lead
1 scan	Generate optimization point checklist	{slug}-scan.md	AI scans code + runs pre-checks, user selects items
2 design	Finalize execution plan	{slug}-refactor-design.md + {slug}-checklist.yaml	AI drafts, user conducts overall review
3 apply	Execute item by item	Code changes + {slug}-apply-notes.md	AI executes, manual approval for each step

There are checkpoints between stages. The scan checklist cannot enter design until the user selects items; no code modifications are made until the design is approved by the user; items marked for HUMAN verification in apply cannot proceed to the next step without user confirmation.

阶段 1：scan（扫出优化点清单）

Stage 1: scan (Generate optimization point checklist)

先跑前置检查（7 条），命中就停

First run pre-checks (7 items), stop if any are hit

动笔扫之前先跑一遍前置检查。命中任何一条就中止 scan，给出路由建议，不要硬凑清单。7 条检查和输出格式见同目录

reference/refusal-routing.md

。

零条合法输出——扫完真的没发现值得做的就老实说，不要凑。

Run pre-checks before starting the scan. If any item is hit, abort scan and provide routing suggestions, do not force a checklist. The 7 checks and output format are in

reference/refusal-routing.md

in the same directory.

Zero valid outputs — if no worthwhile optimizations are found after scanning, state this honestly instead of forcing entries.

扫描范围锁定

Lock scan scope

进 scan 前先和用户确认一件事：这次扫哪些文件。默认规则：

用户点名了具体文件/组件 → 就扫那些
用户说"这个页面" → 扫该页面入口组件 + 它直接 import 的内部模块，不追公共依赖
用户说"这个模块" → 扫该模块目录下的文件，不追出模块边界
范围 > 15 文件或 > 3000 行 → 触发第 6 条前置检查，请用户先缩范围

范围里要包含测试文件（用来判断第 2 条前置检查的测试覆盖情况）。

Before starting the scan, confirm one thing with the user: which files to scan this time. Default rules:

User specifies specific files/components → scan only those
User says "this page" → scan the page's entry component + directly imported internal modules, do not trace public dependencies
User says "this module" → scan files in the module directory, do not go beyond module boundaries
Scope > 15 files or > 3000 lines → trigger the 6th pre-check, ask the user to narrow the scope

Include test files in the scope (to judge test coverage for the 2nd pre-check).

扫的时候看什么

What to look for during scanning

按方法库的四层分类当模板在代码里找：

L1 行为等价迁移信号：某个函数被很多处调用，但接口/实现要改 → 候选 Parallel Change；某整块老逻辑要被新实现替换 → 候选 Strangler Fig
L2 代码级重构信号：超长函数（> 50 行 / 圈复杂度 > 10）、重复的条件片段、神秘临时变量、多层嵌套 if-else
L3 结构拆分信号：组件 > 300 行、一个文件承担多件事、容器/展示混在一起、相同逻辑在多个组件里各写一份（前端）；Controller 里直接调 DB、Service 层缺失、Repository 被绕开（后端）
L4 性能信号：重复计算（可 memo）、N+1 查询、列表无虚拟化/分页、事件监听无清理、大对象深响应（Vue）

方法库完整清单在同目录

reference/methods.md

，扫描时要全量加载作为匹配表。

Use the four-layer classification of the method library as a template to search in the code:

L1 Behavioral Equivalence Migration Signals: A function is called in many places but its interface/implementation needs modification → candidate for Parallel Change; a whole block of old logic needs to be replaced with a new implementation → candidate for Strangler Fig
L2 Code-level Refactoring Signals: Overly long functions (> 50 lines / cyclomatic complexity > 10), repeated conditional fragments, mysterious temporary variables, deeply nested if-else
L3 Structure Splitting Signals: Components > 300 lines, one file handles multiple tasks, container/presentation logic mixed, identical logic written separately in multiple components (frontend); Controller directly calls DB, missing Service layer, Repository bypassed (backend)
L4 Performance Signals: Repeated calculations (memoizable), N+1 queries, list without virtualization/pagination, event listeners not cleaned up, deep reactivity for large objects (Vue)

The complete method library list is in

reference/methods.md

in the same directory, which must be fully loaded as a matching table during scanning.

产出格式

Output format

{slug}-scan.md

由两部分组成：

顶部总览（一段）：扫描范围 / 发现条数 / 按分类分布 / 按风险分布 / 建议先做哪几条 / 建议慎做哪几条
清单条目（一条一块 markdown）：字段顺序和硬约束见同目录
```
reference/scan-checklist-format.md
```

扫完把

{slug}-scan.md

整份交给用户看，用户勾选要做的条目（打 ✓）、标注疑问或否决（打 ✗ 并写理由），再进阶段 2。不要自己替用户勾选。

{slug}-scan.md

consists of two parts:

Top Overview (one paragraph): Scan scope / number of findings / distribution by category / distribution by risk / recommended priority items / recommended cautious items
Checklist Items (one markdown block per item): Field order and hard constraints are in
```
reference/scan-checklist-format.md
```
in the same directory

After scanning, submit the entire

{slug}-scan.md

to the user. The user selects items to implement (mark ✓), marks questions or rejections (mark ✗ and write reasons), then proceed to Stage 2. Do not select items on behalf of the user.

阶段 2：design（定执行方案）

Stage 2: design (Finalize execution plan)

输入

Input

用户勾选过的
```
{slug}-scan.md
```
（✓ 的条目是本次要做的，✗ 的归档留痕）
方法库
```
reference/methods.md
```
（每条勾选项必须映射到一个方法号 M-Ln-NN）

```
{slug}-scan.md
```
with user selections (✓ items are to be implemented this time, ✗ items are archived for traceability)
Method library
```
reference/methods.md
```
(each selected item must map to a method ID M-Ln-NN)

做的事

Tasks

排顺序。勾选条目之间有依赖的排在前面（如 L1 的 Parallel Change 往往要先跑，L2 的提取跟在后面）。独立的按"低风险 + AI 可自证"优先，HUMAN 验证项排后面批量处理。
每条补执行细节：引用的方法号、具体步骤、前置条件、退出信号、验证责任方（AI / HUMAN）、回滚策略（出问题怎么还原）。
识别前置依赖：测试覆盖不够的条目要前置一个"补刻画测试"的步骤；改动涉及公开接口的要前置一个"搜调用方"的步骤。
整体 review：把
```
{slug}-refactor-design.md
```
整稿交给用户，用户放行后改 frontmatter 的
```
status
```
为
```
approved
```
。
抽 checklist：从 design 抽出
```
{slug}-checklist.yaml
```
，steps 对应执行顺序，checks 对应每步的退出信号。

Sort order. Items with dependencies are placed first (e.g., L1 Parallel Change often needs to run first, followed by L2 extraction). Independent items are prioritized by "low risk + AI self-verifiable", and HUMAN verification items are grouped at the end.
Add execution details for each item: Referenced method ID, specific steps, preconditions, exit signals, verification responsible party (AI / HUMAN), rollback strategy (how to restore if problems occur).
Identify pre-dependencies: Items with insufficient test coverage need a pre-step of "supplement characterization tests"; items modifying public interfaces need a pre-step of "search for callers".
Overall review: Submit the full draft of
```
{slug}-refactor-design.md
```
to the user. After user approval, change the
```
status
```
in the frontmatter to
```
approved
```
.
Extract checklist: Extract
```
{slug}-checklist.yaml
```
from the design, with steps corresponding to execution order and checks corresponding to exit signals for each step.

design 文件结构

Design file structure

markdown

---
doc_type: refactor-design
refactor: {YYYY-MM-DD}-{slug}
status: draft | approved
scope: {扫描范围一句话}
summary: {本次要做的几条是什么，一句话}
---

markdown

---
doc_type: refactor-design
refactor: {YYYY-MM-DD}-{slug}
status: draft | approved
scope: {one sentence describing scan scope}
summary: {one sentence describing the items to be implemented}
---

{slug} refactor design

1. 本次范围

1. Scope of this refactor

从 scan 里勾选了哪几条（编号列出）
明确不做的条目（被 ✗ 的）和理由
预估总工作量 / 总风险档位

Which items were selected from the scan (listed by number)
Items explicitly not implemented (marked ✗) and reasons
Estimated total workload / total risk level

2. 前置依赖

2. Pre-dependencies

测试覆盖补齐动作（如果需要）
调用方搜索动作（如果需要）
其他一次性准备

Test coverage supplement actions (if needed)
Caller search actions (if needed)
Other one-time preparations

3. 执行顺序

3. Execution order

按步骤列，每步一块：

步骤 N：{一句话动作}
引用方法：M-Ln-NN {方法名}
具体操作：{照方法库的步骤落到本项目的具体文件/函数}
退出信号：{AI 跑什么测试 / HUMAN 看什么页面}
验证责任：AI 自证｜ HUMAN
回滚：{出问题怎么还原，通常是 git revert 某步}

List by step, one block per step:

Step N: {one sentence action}
Referenced method: M-Ln-NN {method name}
Specific operations: {apply method library steps to specific files/functions in this project}
Exit signals: {tests AI runs / pages HUMAN checks}
Verification responsibility: AI self-verification ｜ HUMAN
Rollback: {how to restore if problems occur, usually git revert the step}

4. 风险与看点

4. Risks and key points

高风险步骤汇总（本次 design 里风险=高的步骤单独拎出来提醒）
容易出错的点（比如跨步骤的数据流变化）

---

Summary of high-risk steps (separately highlight steps with high risk in this design)
Error-prone points (e.g., cross-step data flow changes)

---

阶段 3：apply（逐条执行）

Stage 3: apply (Execute item by item)

推进规则

Advancement rules

一步一做，不批量。严格按 checklist 顺序，当前步不完成不开下一步。
每步完成后走验证：
- AI 自证项：跑指定测试 / 类型检查 / lint / grep 无残留旧引用。通过了记在 apply-notes 里，继续下一步。
- HUMAN 验证项：停下来，汇报"第 N 步已完成，请在 {具体页面 / 操作步骤} 下目视确认，确认后我继续"。用户不明确说"继续"就不推进。
偏离当场记：执行中发现方案里没考虑到的情况（比如有个调用方在动态 import 里），停下来汇报，不要自己发挥。和用户对齐后把偏离点追加到 apply-notes，必要时回阶段 2 改 design。
行为等价自检：每步结束额外问自己——"这一步有没有可能改了外部可观察行为？"。有怀疑就退回当步，不带到下一步。

One step at a time, no batch operations. Strictly follow the checklist order; do not start the next step until the current step is completed.
Verify after each step:
- AI self-verification items: Run specified tests / type checks / lint / grep for no residual old references. Record in apply-notes if passed, then proceed to the next step.
- HUMAN verification items: Pause, report "Step N has been completed, please visually confirm at {specific page / operation steps}, I will continue after confirmation". Do not proceed without explicit "continue" from the user.
Record deviations immediately: If unconsidered situations are found during execution (e.g., a caller in dynamic import), pause and report, do not act on your own. Align with the user, add the deviation to apply-notes, and return to Stage 2 to modify the design if necessary.
Self-check for behavioral equivalence: After each step, ask yourself — "Could this step change externally observable behavior?". If in doubt, roll back the step and do not proceed.

apply-notes 格式

apply-notes format

markdown

---
doc_type: refactor-apply-notes
refactor: {YYYY-MM-DD}-{slug}
---

markdown

---
doc_type: refactor-apply-notes
refactor: {YYYY-MM-DD}-{slug}
---

{slug} apply notes

步骤 1: {动作}

Step 1: {action}

完成时间: {date}
改动文件: {file list}
验证结果: {测试输出 / HUMAN 确认语录}
偏离: {无 / 具体描述}

Completion time: {date}
Modified files: {file list}
Verification result: {test output / HUMAN confirmation quote}
Deviations: {none / specific description}

步骤 2: ...

Step 2: ...

undefined

undefined

全部完成后

After completion

跑一遍全量测试 + 类型检查 + lint
最后一次请用户整体目视确认（尤其是前端：打开主要页面点一圈）
确认通过后收尾 commit，commit message 引用 refactor 目录

Run full tests + type checks + lint
Ask the user for a final overall visual confirmation (especially for frontend: open key pages and test functions)
After confirmation, finalize the commit, with the commit message referencing the refactor directory

退出条件

Exit conditions

scan 前置检查跑过，命中的已按路由引导用户，没命中的才进 scan
```
{slug}-scan.md
```
用户已勾选（✓/✗），未勾选的不进 design
```
{slug}-refactor-design.md
```
每条勾选项都映射到了方法库的方法号
design 用户整体 review 通过，status=approved
```
{slug}-checklist.yaml
```
已生成且通过 validate-yaml.py
apply 阶段每步都有验证记录（AI 自证的贴日志，HUMAN 的贴用户确认语录）
全量测试 / 类型检查 / lint 通过
用户最后一次目视确认通过

Scan pre-checks have been run; if any were hit, the user was guided to the correct route, and only non-hit cases entered scan
User has selected items (✓/✗) in
```
{slug}-scan.md
```
; unselected items did not enter design
Each selected item in
```
{slug}-refactor-design.md
```
is mapped to a method ID in the method library
Design has passed user overall review, status=approved
```
{slug}-checklist.yaml
```
has been generated and validated via validate-yaml.py
Each step in the apply stage has verification records (AI self-verification logs attached, HUMAN confirmation quotes attached)
Full tests / type checks / lint have passed
User has passed the final visual confirmation

容易踩的坑

Common pitfalls

AI 硬凑清单：前置检查明显命中却找理由绕过，扫出一堆 "代码可以更优雅" 这种无量化问题的条目——应直接停下给路由建议
夹带行为改动：在重构中间"顺便修了一个 bug / 优化了一下提示文案"——应停下，拆成独立 issue 或 feature
跨步骤合并动作：为了快，一次提交里做了 2-3 步——失去"出问题单步回滚"的能力
把口味项列进清单：命名偏好、引号、箭头函数 vs function——这些走 decisions，不走 refactor
扫一个大模块就直接动手：> 15 文件 / > 3000 行的范围不拆就进 scan，产出一份没法决策的长清单
HUMAN 验证项自己跳过：前端效果 AI 看不到，不能用 "类型检查过了" 替代人工目视
覆盖率不够硬上：没测试的模块直接改，所谓"行为等价"只是口头承诺

AI forces checklist entries: Clearly hits pre-checks but finds excuses to bypass, and generates entries with non-quantifiable issues like "code can be more elegant" — should pause immediately and provide routing suggestions
Includes behavior changes: "Incidentally fixed a bug / optimized a prompt" during refactoring — should pause and split into an independent issue or feature
Combines cross-step actions: Submits 2-3 steps in one commit for speed — loses the ability to roll back a single step if problems occur
Includes preference items: Naming preferences, quotes, arrow functions vs function — these go to decisions, not refactor
Directly starts scanning a large module: Enters scan without splitting a scope of >15 files / >3000 lines, resulting in an unmanageable long checklist
Skips HUMAN verification items: Frontend effects cannot be seen by AI; cannot replace manual visual inspection with "type checks passed"
Proceeds with insufficient coverage: Modifies modules without tests, with "behavioral equivalence" only a verbal promise

与相邻工作流的边界

Boundaries with adjacent workflows

feature：加新能力 / 改需求 → feature。refactor 里一旦冒出"顺便实现 X"，停下拆出去。
issue：修 bug / 行为错了 → issue。refactor 里发现的 bug 记成新 issue，不在本次 PR 里偷偷修。
decisions：全项目长期约束（"以后都用 composable"、"禁用 mixin"）→ decisions。refactor 执行时可以引用已有 decision 作为依据，但不产出 decision。
architecture：跨模块边界重划 / 分层调整 → architecture + decisions。单次 refactor 不跨模块，跨模块的工作要拆成"更新架构文档 + 记决策 + N 个模块级 refactor"。
tricks / learning：refactor 中发现可复用的手法 → tricks；踩的坑 → learning。

feature: Adding new capabilities / modifying requirements → feature. If "incidentally implement X" comes up during refactoring, pause and split it out.
issue: Fixing bugs / correcting behavior → issue. Bugs found during refactoring should be recorded as new issues, not secretly fixed in the current PR.
decisions: Project-wide long-term constraints ("use composable from now on", "disable mixin") → decisions. Refactor can reference existing decisions as basis, but does not produce decisions.
architecture: Cross-module boundary restructuring / layer adjustment → architecture + decisions. A single refactor does not cross modules; cross-module work should be split into "update architecture documentation + record decisions + N module-level refactors".
tricks / learning: Reusable techniques found during refactoring → tricks; pitfalls encountered → learning.

cs-refactor

Original

Translation

cs-refactor

cs-refactor

Fastforward 模式（小重构走这里）

Fastforward Mode (use for small refactors)

文件放哪儿

Where to place files

三个阶段

Three Stages

阶段 1：scan（扫出优化点清单）

Stage 1: scan (Generate optimization point checklist)

先跑前置检查（7 条），命中就停

First run pre-checks (7 items), stop if any are hit

扫描范围锁定

Lock scan scope

扫的时候看什么

What to look for during scanning

产出格式

Output format

阶段 2：design（定执行方案）

Stage 2: design (Finalize execution plan)

输入

Input

做的事

Tasks

design 文件结构

Design file structure

{slug} refactor design

{slug} refactor design

1. 本次范围

1. Scope of this refactor

2. 前置依赖

2. Pre-dependencies

3. 执行顺序

3. Execution order

4. 风险与看点

4. Risks and key points

阶段 3：apply（逐条执行）

Stage 3: apply (Execute item by item)

推进规则

Advancement rules

apply-notes 格式

apply-notes format

{slug} apply notes

{slug} apply notes

步骤 1: {动作}

Step 1: {action}

步骤 2: ...

Step 2: ...

全部完成后

After completion

退出条件

Exit conditions

容易踩的坑

Common pitfalls

与相邻工作流的边界

Boundaries with adjacent workflows

相关文档

Related documents