用途
safe-refactor 面向“重构”这一特定任务：重新组织代码结构而不改变其可观察行为。适用于重命名、提取函数或类、移动文件、清理遗留模块等场景，也适用于任何需要可复现地回答“改完之后还能正常跑吗”的变更。它明确不用于添加功能或修复缺陷。
基本原则
- 开始前测试必须全绿。若测试未通过，应先修复测试环境，因为失败的测试无法判断重构是否破坏了行为。
- 重构提交零行为变更。每个重构提交只做纯结构改动；新功能、缺陷修复和改变含义的文档更新应放在单独提交中。
- 小步机械化推进，每步之间运行测试。一步只改一件事：重命名一个符号、提取一个函数、移动一个文件。每步后运行相关测试再提交。
- 重命名使用真实工具。不要手动 sed/grep 全树替换，应使用语言感知的重构工具，如 IDE 的重命名、git mv 或语言相关 codemod（jscodeshift、comby、rope）。
- 关注影响范围。共享模块中的重命名可能影响数十个文件，需检查导入/导出、类型存根、文档和生成文件；不确定时先追踪符号的所有使用点。
完成标准
重构完成需同时满足：所有现有测试通过（如 npm test / pytest 返回 0）；无行为变更（diff 只显示移动、重命名、提取等结构改动，无逻辑编辑）；无孤立引用（linter 通过，如 ruff、eslint、tsc --noEmit，无未解析导入）；无遗留死代码（重构区域覆盖率不低于重构前基线）；Git 日志清晰（每步一个提交，信息具描述性，如 refactor: rename Order.total() to Order.calculate_total()）；CI 通过（推送后最终分支 CI 运行成功）。
工作流
- 基线：新建分支 git checkout -b refactor/<description>；运行完整测试套件，失败则先修复测试环境；记录当前覆盖率和测试数量。
- 规划步骤序列：写下每个原子变换。以重命名函数为例：先并列添加新函数，再更新内部调用方使用新名，然后删除旧函数，最后更新外部/导出引用。判断标准：若不能用一句短话描述该步骤，就还不够原子。
- 执行一步：只做计划中的一步改动；运行相关测试模块（而非整套测试，以保持快速反馈）；通过则以 refactor: 开头提交，描述改了什么而非为什么；失败则回退（git checkout -- .）并更谨慎重做。绝不要通过修改测试来迁就错误代码，应回退代码改动。
- 迭代：对计划中每个原子变换重复第 3 步；每 3–5 步或触碰共享/公共接口时运行完整测试套件。
- 最终验证：再跑一次完整测试；用最严格配置运行 linter；如可用则运行语言类型检查器；推送分支并确认 CI 通过；以“Refactor: ”为描述开 PR 并链接计划。
常见陷阱
- 重构中夹带缺陷修复：先在单独分支提交修复，再开始重构。
- 一次重命名提交触及 20 个文件：使用语言感知重命名，多数 IDE 和 git mv 可自动处理。
- “顺便修这个小问题”：先提交重构，再在新分支修复。
- 测试要跑 20 分钟：隔离变更所在测试模块用于快速内循环，仅在检查点跑完整套件。
- 忘记更新类型存根或文档字符串：将 .d.ts / .pyi / docstring 文件纳入提交前检查清单。
- 本地 CI 通过但服务器失败：匹配 CI 环境（Node 版本、操作系统、依赖锁），可使用 CI Docker 镜像或本地 act。
相关衔接
合并重构 PR 前的代码审查可衔接 github-code-review；验证重构未破坏功能可衔接 test-driven-development 或项目测试框架；规划前的代码库深入分析可衔接 understand；快速验证重构方案可衔接 spike；撰写重构分支 PR 描述可衔接 github-pr-workflow。