重构（Refactoring）

归属：docs/guides/sops/ 触发：不改行为、只改结构——提升可读性、可测试性、可维护性关联概念：improve-codebase-architecture、flow-tdd、flow-review

场景定义

在不改变外部可观察行为的前提下，改进既有代码结构。核心判据是「行为保持」：重构前后，系统对外行为完全一致。

目标与不做什么

目标：用测试作安全网，小步安全地改善结构（模块深度、接口清晰度、可测试性）。
不做：不夹带新功能、不修 bug（那是 01-bug-fix）、不做行为变更（那是 03-business-adjustment）。

标准方法论（行业通行）

借鉴 Fowler 重构原则与结构化重构实践：

行为保持：重构是一系列保持行为的小变换；任何一步都不改变外部行为。
测试作安全网：前置条件是目标区域有充分且通过的测试；重构前后全量回归必须全绿。
识别重构机会（improve-codebase-architecture）：用 deletion test、模块深度、seam、locality 判断哪些模块浅/耦合/难测；从领域语言（CONTEXT.md）给好 seam 命名。
小步提交：每步重构独立提交，每步测试绿；失败可回退到最近绿状态。
接口与实现分离：公共接口保持稳定，允许接口向内聚变化；测试通过公开接口验证行为，而非实现细节。

本项目落地流程

确认行为保持：与用户确认重构边界与「不得改变的行为集合」。
前置检查：目标区域测试存在且绿；若无充分测试，先补关键路径测试（RED→GREEN），再重构。
识别重构机会（可选委派 improve-codebase-architecture）：产出候选清单（涉及文件、问题、方案、收益），与用户确认要探索哪些。
小步重构：在独立分支 refactor/<slug> / worktree 内，按 RED（可选）→ GREEN → refactor 循环；每步提交并保持测试绿。
行为对比验证：重构完成后跑全量回归 + 针对性行为对比（快照 / 差分 / 关键路径测试），确认无行为差异。
审查：复用 flow-review，但审查轴改为行为保持（对比重构前后行为），而非规格轴对照 PRD（重构没有 PRD）。
合并：CI 绿 + 行为保持审查通过后合并。

验证与门禁

[ ] 前置：目标区域测试存在且绿
[ ] 重构前后全量回归（npm test）均绿
[ ] 无外部行为差异（快照 / 差分 / 关键路径验证）
[ ] 每步小提交独立可回退
[ ] 行为保持审查通过 + CI 绿

产出物

重构候选清单（如需识别阶段）
多个小步提交的 refactor/<slug> PR
行为保持验证记录

复用与新增资产

复用：flow-tdd（refactor 阶段）、flow-code（worktree 编码）、flow-review（自定义行为保持轴）、improve-codebase-architecture（识别机会）。
新增（缺口）：重构「行为保持」审查轴；refactor/<slug> 分支约定。

反模式 / 注意事项

目标区域没有测试就重构（无安全网）。
在重构中夹带新功能或 bug 修复。
大爆炸式重构（一步改完）——失去小步可回退能力。
测试耦合实现细节，重构时测试就碎（说明测试在测「形状」而非行为）。
重构后声称「行为未变」却无任何验证证据。