# 提示词：安全重构

> 重构前先用测试钉住现有行为，再分小步修改，每一步都运行测试并单独提交，让智能体在不改变外部行为的前提下整理结构，随时可回退。

## 适用场景

某个文件或模块已经难以维护：函数过长、重复逻辑多、命名混乱，你想整理但又怕改坏。重构的定义是不改变外部行为，所以关键不在「怎么改」，而在「怎么证明没改坏」。

智能体做重构有一个典型风险：一口气改很多文件，顺手「优化」了行为，最后测试全红，你既不知道哪一步出的问题，也回不去了。这份提示词把重构拆成可验证、可回退的小步。

## 模板

```text
重构目标：【例如：把 order.ts 中 400 行的 processOrder 拆成职责清晰的几个函数】
范围：只允许修改【文件或目录】。
硬性约束：外部行为不变——公共函数签名、返回值、抛出的错误、副作用、日志格式都不变。

请按这个流程来，不要跳步：

第 0 步，评估。
阅读目标代码和它的调用方，说明：现状的主要问题、你打算采用的重构手法
（提取函数、消除重复、重命名、拆分模块等）、预计要改动哪些文件。
同时指出任何你认为有风险的地方（隐式依赖、全局状态、反射、时间相关逻辑）。
等我确认后再继续。

第 1 步，钉住现有行为。
运行现有测试并记录基线。如果目标代码的覆盖不足，先补「特征测试」：
用当前真实行为作为期望值，包括奇怪的行为，不要在这一步纠正它们。
特征测试通过后单独提交，提交信息以 test: 开头。

第 2 步，小步重构。
每一步只做一种变换，并且改动要小到我能在两分钟内读完 diff。
每一步完成后：运行全部相关测试 → 全绿才继续 → 单独提交（提交信息以 refactor: 开头，写清这一步做了什么）。
如果测试变红，立刻撤销这一步，不要在红色状态下继续叠加改动。

第 3 步，收尾。
运行完整的测试、Lint 和类型检查，贴出真实输出。
对比重构前后的公共接口，确认没有变化。
汇报：做了哪些步骤、每步的提交、仍然存在但本次没动的坏味道。

不要做的事：顺手修 bug（发现的 bug 记录下来告诉我）、升级依赖、改动范围外的文件、
修改任何已有测试的期望值。
```

## 怎么用 / 怎么改

- **分支与回退。** 先在新分支上进行，每个小步一个提交。任何一步不满意，直接用版本控制回退到上一个绿色状态，成本很低。
- **规模大时用并行。** 大范围的机械式改动，比如把一个旧 API 的调用全部迁移，可以交给多个会话各自在独立的 worktree 里处理，详见本站「用 git worktree 并行开发」。
- **没有任何测试的老代码。** 第 1 步会比较吃力，让它先列出「最可能被破坏的行为」，只为这些行为写特征测试，不追求全面。
- **想要更激进的重构。** 在提示词里明确写出允许的变化（例如「可以调整内部模块边界，但不改动对外导出」），并要求第 0 步给出方案对比。

## 常见问题或注意事项

- **「小步」被理解成「一次改一个文件」。** 要求以变换种类为单位，而不是文件。改一个函数名要同步改所有调用点，这是一步。
- **智能体顺手修了 bug。** 把 bug 修复放到重构之后，单独提交。混在一起会让评审者无法判断行为变化是否有意为之。
- **测试全绿仍可能改坏行为。** 测试只能证明被测到的部分。对性能敏感或没有测试的路径，要求补一个简单的对照检查，例如对比重构前后的输出。
- **类型检查和 Lint 也算验证。** 动手前先确认它们本来是绿的，否则无法判断红色是谁引入的。