Back to Details

cs-refactor-ff

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cs-refactor-ff

cs-refactor-ff

用户说"优化一下这个函数"而改动明显很小（单个函数变长了、一个组件里抽个 composable、一段重复代码合并）时，走完整三阶段太重。fastforward 做一件事：让 AI 像平时一样直接改，但守住 refactor 的底线——行为等价、引用经典方法、跑测试自证。
所以这个技能非常轻。没有 scan 清单、没有 design doc、没有 checklist，改完一句话汇报就行。
When a user says "optimize this function" and the changes are clearly minor (a single function gets longer, extract a composable from a component, merge duplicate code), going through the full three-stage workflow is overkill. fastforward does one thing: let AI modify directly like it normally would, but sticks to the bottom line of refactor - behavioral equivalence, using classic methods, and validating itself by running tests.
So this skill is extremely lightweight. No scan checklist, no design doc, no checklist - just a one-sentence report after modification.

入场 3 条硬检查（不过就退出到完整流程）

3 Hard Entry Checks (Exit to Full Workflow if Any Fail)

开写前问自己 3 件事，任一不过就退到 
cs-refactor
走完整流程：
  1. 行为真的不变吗？ 用户描述里夹带了"顺便支持 X / 改成 Y"——这是行为改动，不是 refactor，让用户拆出去走 feature / issue
  2. 范围真的小吗？ 超过 1 个文件、或单文件超过 100 行改动、或预计改动点超过 3 处——退到完整流程
  3. 有测试能自证吗？ 目标代码有覆盖它的测试（单测 / 集成测 / 类型检查能抓到）——没测试就退到完整流程，或先做一个 characterization test 再回来
入场硬检查的 scan 阶段完整版是 7 条，这里压缩成最关键的 3 条——剩下 4 条（跨模块、全口味、生成代码、扫不完）在"范围真的小吗"里已经被隐含排除了。
Before starting, ask yourself 3 questions. If any fail, switch back to the 
cs-refactor
full workflow:
  1. Is behavior truly unchanged? If the user's description includes "also support X / change to Y" - this is a behavioral change, not a refactor. Ask the user to split it into a feature / issue workflow.
  2. Is the scope truly small? If changes involve more than 1 file, or over 100 lines in a single file, or more than 3 expected modification points - switch to the full workflow.
  3. Is there test coverage for self-validation? The target code has tests covering it (unit tests / integration tests / type checks can catch issues) - if no tests exist, switch to the full workflow, or create a characterization test first before returning.
The full scan stage of entry checks has 7 items, which are compressed to the 3 most critical ones here - the remaining 4 items (cross-module, full flavor, generated code, incomplete scan) are already implicitly excluded in "Is the scope truly small?".

用经典方法，不发挥

Use Classic Methods, No Improvisation

fastforward 不读完整方法库，但要守住："每一处改动都能对应到一个经典重构方法"。AI 心里想不出"我这步是 Extract Function / Memoization / Guard Clauses / ..."里的哪一个，就说明这次改动不是简单重构，退到完整流程去查方法库。
常用的几种（覆盖 fastforward 80% 场景）：
  • 提取函数（Extract Function）：一段 > 5 行、内聚、能命名的片段 → 抽出独立函数
  • 提取变量（Extract Variable）：复杂表达式 → 命名变量或 query
  • 守卫语句（Guard Clauses）：开头多层嵌套 if 检查 → 提前 return 拉平
  • 分解条件（Decompose Conditional）：复杂 if 条件 → 命名为布尔函数
  • 抽 composable / hook（Extract Composable）：组件里封闭的状态 + 副作用 → 独立 composable / hook
  • 记忆化（Memoization）：重复计算 → computed / useMemo
  • 守卫清理（Cancellation）：副作用缺 cleanup → 加 onUnmounted / useEffect return
想做的动作不在这几种里也不是开箱即用的经典方法（如涉及 Parallel Change / Strangler Fig / 分层纠偏）——退到完整流程。
fastforward doesn't read the complete method library, but must adhere to: "Every change must correspond to a classic refactor method". If AI can't identify which classic method (e.g., Extract Function / Memoization / Guard Clauses / ...) a change corresponds to, it means this isn't a simple refactor - switch to the full workflow to check the method library.
Common methods (covering 80% of fastforward scenarios):
  • Extract Function: A segment of >5 lines, cohesive, and namable → extract into an independent function
  • Extract Variable: Complex expressions → name as variables or queries
  • Guard Clauses: Multi-layer nested if checks at the start → return early to flatten the structure
  • Decompose Conditional: Complex if conditions → name as boolean functions
  • Extract Composable / hook: Encapsulated state + side effects in a component → extract into an independent composable / hook
  • Memoization: Repeated calculations → use computed / useMemo
  • Cancellation: Missing cleanup for side effects → add onUnmounted / useEffect return
If the intended action isn't among these or isn't an out-of-the-box classic method (e.g., involves Parallel Change / Strangler Fig / layered correction) - switch to the full workflow.

流程

Workflow

1. 一次对齐

1. One-Time Alignment

收到请求后，一句话回用户："我打算做 {方法名}，动 {具体文件/函数}，改动点 {N} 处，预计影响 {范围}。确认就开干。"
用户确认就下一步。用户说"还有个 X 要改"——评估这个 X 是否破坏入场 3 条检查，破坏了就退到完整流程。
After receiving the request, reply to the user in one sentence: "I plan to use {method name}, modify {specific file/function}, with {N} modification points, expected impact {scope}. Confirm to start."
Proceed to the next step if the user confirms. If the user says "also need to change X" - evaluate whether this X violates the 3 entry checks. If it does, switch to the full workflow.

2. 改

2. Modify

按经典方法的步骤改。不产出 design doc、不产出 checklist。代码改动直接落盘。
Modify according to the steps of the classic method. No design doc or checklist is produced. Code changes are directly committed.

3. 自证

3. Self-Validation

  • 跑测试（单元 / 集成 / 类型检查 / lint）
  • grep 检查旧引用是否清理干净（如果做了 Extract Function / Inline Function 这类）
  • 如果改了前端状态逻辑，跑类型检查 + 已有测试；不做 UI 目视验证——要 UI 目视就不该走 fastforward
  • Run tests (unit / integration / type checks / lint)
  • Use grep to check if old references are fully cleaned up (for changes like Extract Function / Inline Function)
  • If front-end state logic is modified, run type checks + existing tests; do not perform UI visual verification - UI visual checks should not use fastforward.

4. 一句话汇报

4. One-Sentence Report

格式：
✓ 已完成。方法：{方法名}。改动：{文件路径:行号范围}。验证：{跑了什么测试 / 通过情况}。
有偏离、或 apply 过程中发现想再改点别的——停下问用户，不要发挥。
Format:
✓ Completed. Method: {method name}. Changes: {file path: line number range}. Validation: {tests run / pass status}.
If there are deviations, or if you want to make additional changes during application - stop and ask the user, do not improvise.

文件产出

File Output

默认不在 
codestable/refactors/
下建目录——fastforward 的价值就在不留存档。
例外：用户明确说"这次小重构要留个记录"——建一个 
codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md
，内容就是上面那句汇报再加一段"做了什么 / 为什么"。不写 design，不写 checklist。
By default, do not create a directory under 
codestable/refactors/
 - the value of fastforward lies in leaving no archives.
Exception: If the user explicitly says "keep a record of this small refactor" - create a 
codestable/refactors/{YYYY-MM-DD}-{slug}/{slug}-refactor-note.md
, whose content is the above report plus a section "What was done / Why". No design doc or checklist is written.

什么时候跳出 fastforward

When to Exit fastforward

改到一半出现下面任一情况，停下来告诉用户"比预期复杂，建议切回完整 refactor 流程"：
  • 改动点从 3 个涨到 5+
  • 发现要动的文件不止 1 个
  • 冒出一个不在常用方法清单里的动作
  • 发现没有测试能覆盖改动
  • 用户追加 "顺便改一下 X" 带入行为改动
  • 改完 AI 自证失败（测试挂了）且不是简单修正能搞定
切回方式：触发 
cs-refactor
，从 scan 阶段开始。已改的部分要么提交保留、要么 
git restore
回到干净状态再扫，看用户决定。
If any of the following situations occur during modification, stop and tell the user "It's more complex than expected, suggest switching back to the full refactor workflow":
  • Number of modification points increases from 3 to 5+
  • Discover that more than 1 file needs to be modified
  • An action not in the common method list emerges
  • Discover no test coverage for the changes
  • User adds "also change X" which introduces behavioral changes
  • AI self-validation fails after modification (tests fail) and it can't be fixed with simple corrections
Switchback method: Trigger 
cs-refactor
, starting from the scan stage. The modified parts can either be committed and retained, or restored to a clean state with 
git restore
before scanning, depending on the user's decision.

不做什么

What Not to Do

  • 不写 scan 清单 / design doc / checklist —— 写了就违背 fastforward 存在的理由
  • 不跨多文件改 —— 跨文件就不是"小重构"
  • 不做需要 HUMAN 目视的改动 —— 前端渲染 / 交互 / 性能感知要人看的，走完整流程
  • 不碰公开接口 —— 改了公开接口要走 Parallel Change，Parallel Change 不是 fastforward 能做的
  • Do not write scan checklists / design docs / checklists - writing them defeats the purpose of fastforward
  • Do not modify across multiple files - cross-file changes are not "small refactors"
  • Do not make changes requiring human visual verification - front-end rendering / interaction / performance perception that requires human review should use the full workflow
  • Do not touch public interfaces - modifying public interfaces requires Parallel Change, which cannot be done via fastforward

容易踩的坑

Common Pitfalls

  • 把"小"判断得太宽：用户说"小重构"但实际要动 3 个文件——AI 要老实说"这不算小，建议走完整流程"
  • 跳过入场 3 条检查就开干：这个技能的意义就在这 3 条
  • 自证偷懒：只跑类型检查不跑单元测试，或完全不 grep 旧引用
  • 改中发挥：看到邻居代码也"顺手改改"——fastforward 的范围在确认那一刻就锁死，后续不扩
  • 行为改动伪装成重构：加个新参数、改返回值格式——这是行为改动，伪装不了
  • Judging "small" too broadly: User says "small refactor" but actually needs to modify 3 files - AI should honestly say "This isn't small, suggest using the full workflow"
  • Starting modification without passing the 3 entry checks: The significance of this skill lies in these 3 checks
  • Cutting corners on self-validation: Only running type checks instead of unit tests, or not using grep to check old references at all
  • Improvising during modification: "Fixing" neighboring code along the way - the scope of fastforward is locked at the time of confirmation, and should not be expanded afterward
  • Disguising behavioral changes as refactors: Adding a new parameter, changing return value format - these are behavioral changes and cannot be disguised

相关

Related

  • cs-refactor/SKILL.md
    — 完整 refactor 流程，复杂时切过来
  • cs-refactor/reference/methods.md
    — 完整方法库（fastforward 用户想查也可以翻，但执行不依赖它）
  • codestable/reference/system-overview.md
    — CodeStable 体系总览
  • cs-refactor/SKILL.md
    - Full refactor workflow, switch to this for complex cases
  • cs-refactor/reference/methods.md
    - Complete method library (fastforward users can refer to it if needed, but execution doesn't depend on it)
  • codestable/reference/system-overview.md
    - CodeStable system overview