| name | refactoring |
| version | 1.0.0 |
| last_updated | "2026-04-08T00:00:00.000Z" |
| repository | https://github.com/312362115/claude |
| description | 大规模重构的结构化流程：影响分析→安全网搭建→分步重构→回归验证。 适用于涉及多文件、架构调整、模块解耦、接口重新设计等非平凡重构。 本 skill 是流程 skill（调度型），复用 task-execute 管理进度、task-finish 做收尾、 dependency-map 做影响分析、writing 写方案。 触发词：重构、解耦、架构调整、模块拆分、接口重新设计、refactor。 触发场景：用户明确说要重构、task-start 判定为重构类任务、代码审查后决定重构。 小范围重命名或局部调整不需要本 skill，直接动手即可。
|
大规模重构（Refactoring）
重构最大的风险不是改错，而是改了不知道影响了什么。
本 skill 的核心：先建安全网，再动刀子，每一步都有回退点。
第一步：判断是否需要本 skill
收到重构请求
│
├─ 改动 ≤2 个文件，不涉及公共接口？
│ └─ 直接动手，不需要本 skill
│
├─ 改动 3-5 个文件，局部重构？
│ └─ 走简化流程：第二步（快速版）→ 第四步 → 第五步
│
└─ 涉及公共接口 / 跨模块 / 架构调整 / 数据结构变更？
└─ 走完整流程：第二步 → 第三步 → 第四步 → 第五步 → 第六步
判断信号：
| 信号 | 走完整流程 |
|---|
| 改公共函数/类的签名 | 是 |
| 拆分或合并模块 | 是 |
| 改数据模型/数据库 schema | 是 |
| 改目录结构 | 是 |
| 改导入路径被多处引用 | 是 |
| 纯内部实现优化，接口不变 | 否，简化流程 |
第二步：影响分析
动手之前，先搞清楚"改这里会动到哪里"。
2.1 确定重构范围
- 重构目标：要改什么？改完应该是什么样？（用
AskUserQuestion 和用户对齐）
- 触发原因：为什么要重构？（技术债 / 性能 / 可维护性 / 新需求倒逼）
- 不改什么：明确哪些相关代码这次不动（防止 scope 膨胀）
2.2 依赖关系梳理
对要重构的模块，梳理上下游依赖：
被谁调用（上游）→ [重构目标] → 调用了谁（下游）
具体操作：
- Grep 搜索：搜索要重构的函数名/类名/模块路径，找到所有引用位置
- 导入分析：检查
import/require 关系，画出依赖图
- 数据流追踪：如果涉及数据结构变更，追踪数据从哪来、到哪去
2.3 影响面评估
列出影响清单：
## 影响分析
### 直接影响（必须改）
- `src/services/auth.ts` — 调用了要重构的函数
- `src/api/user.ts` — 引用了要修改的类型
### 间接影响（需要验证）
- `src/pages/login.tsx` — 依赖 auth 服务，接口不变则不受影响
- `tests/auth.test.ts` — 测试用例需要同步更新
### 不受影响（确认安全）
- `src/utils/format.ts` — 无依赖关系
快速版（局部重构）：只做 Grep 搜索确认引用范围，不需要完整的影响清单文档。
第三步：安全网搭建
没有安全网的重构是赌博。安全网 = 测试 + 回退能力。
3.1 确认现有测试覆盖
检查要重构的模块是否有测试：
grep -r "重构目标函数名/模块名" tests/ __tests__/ *.test.* *.spec.*
| 现有测试情况 | 策略 |
|---|
| 有测试且覆盖核心路径 | 先跑通现有测试，确认 baseline 全绿 |
| 有测试但覆盖不足 | 补充关键路径测试后再开始重构 |
| 没有测试 | 必须先补测试，至少覆盖核心路径和边界情况 |
3.2 补充缺失测试
对于没有测试或覆盖不足的情况：
- 不需要追求 100% 覆盖率
- 重点覆盖：要改的函数的核心输入输出、公共接口的契约、边界情况
- 测试应该验证行为（输入→输出），不验证实现细节
- 把测试用例记录到
docs/tests/<模块名>-refactor.md
3.3 创建回退点
git checkout -b refactor/<模块名>
git commit -m "chore: 重构前基线 — 测试全绿"
确保随时可以 git diff refactor/<模块名> 看到所有改动，出问题能快速回退。
第四步：分步重构
大象要一口一口吃。每一步都是可验证的、可回退的。
4.1 制定重构计划
将重构拆分为独立的、可验证的小步骤，每步完成后测试应该通过：
## 重构计划
- [ ] Step 1: <描述> — 预期：测试全绿，行为不变
- [ ] Step 2: <描述> — 预期：测试全绿，行为不变
- [ ] Step 3: <描述> — 预期：测试全绿，新接口生效
- [ ] Step 4: 清理旧代码 — 预期：测试全绿，无废弃代码
拆分原则：
- 每步只做一件事（改结构不改逻辑 / 改逻辑不改结构）
- 每步改完都能编译通过、测试通过
- 步骤间尽量不互相依赖
- 危险操作（删代码、改数据结构）放后面，确认安全了再做
4.2 常用重构策略
| 场景 | 推荐策略 |
|---|
| 改公共接口签名 | 先新后删：新接口 → 迁移调用方 → 删旧接口 |
| 拆分大文件/大函数 | 提取 → 内联引用 → 验证 → 删旧 |
| 改目录结构 | 先移文件 → 修导入 → 验证 → 提交（单独一步，不混逻辑改动） |
| 替换依赖/框架 | 适配器模式：新旧共存 → 逐步迁移 → 移除旧依赖 |
| 改数据模型 | 双写过渡：新旧字段并存 → 迁移读写逻辑 → 清理旧字段 |
4.3 执行纪律
每完成一个步骤：
- 跑测试：确认现有测试全部通过
- 跑 lint：确认没有引入格式问题
- 快速 review：看一眼 diff，确认只改了该改的
- 提交：每步一个 commit，message 说清楚做了什么
git commit -m "refactor(auth): step 1 — 提取 token 验证为独立函数"
如果某一步测试挂了：
- 先看是不是测试本身需要更新（因为接口变了）
- 如果是意料之外的挂掉 → 停下来分析，不要硬继续
- 实在搞不清 → 回退到上一步的 commit，重新想策略
第五步：回归验证
重构的目标是"行为不变，结构更好"。验证行为是否真的没变。
5.1 运行全量测试
npm test
npm run test:e2e
5.2 人工验证核心路径
测试不能覆盖一切。对于以下场景，手动验证：
- 页面渲染是否正常（前端重构）
- API 响应是否符合预期（后端重构）
- 关键业务流程走通（端到端）
5.3 对比验证
git diff refactor/<模块名>..HEAD --stat
检查：
- 没有混入不相关的改动
- 没有遗留 debug 代码
- 没有遗留注释掉的旧代码
第六步：收尾
6.1 清理
- 删除废弃的旧代码（不是注释掉，是删掉）
- 更新相关文档（如果重构改了目录结构、接口、配置等）
- 更新
docs/tests/ 中的测试用例（重构过程中新增的测试要沉淀）
6.2 交给 task-finish 进行 CR 自检
重构完成后，交给 task-finish 执行深度自检：
- 改动范围是否符合重构目标？
- 有无混入不相关变更？
- 有无遗留调试代码？
6.3 复盘沉淀（由 task-manager 触发）
重构完成后，当用户将需求标 done 时，由 task-manager 触发复盘。重构类任务建议做完整复盘，记录到 docs/decisions/：
- 重构的动机和目标达成了吗？
- 哪些步骤顺利？哪些卡住了？
- 影响分析是否准确？遗漏了什么？
- 下次类似重构有什么经验可复用？
与其他 skill 的衔接
task-start
│ 判定为重构任务
↓
refactoring（本 skill）
│
├─ 第二步 ← dependency-map（影响分析，如果有的话）
├─ 第二步 ← writing（写重构方案，大型重构时）
├─ 第四步 ← task-execute（跨会话进度管理）
├─ 第五步 ← perf-profiling（性能相关重构时对比前后）
│
├─ 收尾 → task-finish（CR 自检）
└─ 需求标 done → task-manager → 触发复盘
反模式清单
| 反模式 | 后果 | 正确做法 |
|---|
| 没有安全网就开始改 | 改完不知道哪里坏了 | 先确认测试覆盖，再动手 |
| 一次改太多 | 出问题无法定位 | 小步提交，每步可验证 |
| 重构时顺手加功能 | scope 膨胀，风险叠加 | 重构和功能开发分开做 |
| 改结构的同时改逻辑 | 无法区分是结构改动还是逻辑改动引起的问题 | 一步只做一件事 |
| 注释掉旧代码不删 | 代码越来越脏 | 确认不用了就删 |
| 跳过回归测试 | 上线后才发现问题 | 每步跑测试，最后全量回归 |
| 不记录影响面 | 下次改同样的地方又不知道影响谁 | 影响分析写下来 |
