收到重构请求
  │
  ├─ 改动 ≤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 创建回退点

# 在重构开始前创建一个明确的 commit 或 branch
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  # 或 pytest

# 如果有 e2e 测试
npm run test:e2e

5.2 人工验证核心路径

测试不能覆盖一切。对于以下场景，手动验证：

页面渲染是否正常（前端重构）
API 响应是否符合预期（后端重构）
关键业务流程走通（端到端）

5.3 对比验证

# 对比重构前后的 git diff，确认改动范围符合预期
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 膨胀，风险叠加	重构和功能开发分开做
改结构的同时改逻辑	无法区分是结构改动还是逻辑改动引起的问题	一步只做一件事
注释掉旧代码不删	代码越来越脏	确认不用了就删
跳过回归测试	上线后才发现问题	每步跑测试，最后全量回归
不记录影响面	下次改同样的地方又不知道影响谁	影响分析写下来

refactoring

大规模重构（Refactoring）

第一步：判断是否需要本 skill