代码重构 Prompt：让 AI 做安全的大规模重构
跨文件重构常改出新 bug，这条 Prompt 强制 AI 先分析影响范围、补回归测试、分步重构、每步验证，最后输出变更清单。适合接口签名变更与跨模块迁移，改动越大越需要这套分步验证流程。
发布 2026-06-21更新 2026-10-21用法
对需要重构的代码，配合下面的 prompt。适合跨文件重构、改接口签名、提取公共逻辑等场景。
Prompt
我需要重构以下代码，请按安全重构流程执行，不要跳步：
## 1. 影响分析（先做这个，不要改代码）
列出这次重构会影响的所有文件和函数：
- 直接影响：被改的文件 / 函数
- 间接影响：调用方 / 被调用方
- 测试影响：哪些测试需要更新
## 2. 测试基线（确保重构前测试通过）
- 跑一遍现有测试，确认全绿
- 如果没有测试，先帮我写覆盖当前行为的测试（不要写期望行为）
- 测试不过就停下，不要继续重构
## 3. 重构计划
把重构拆成 N 个小步骤，每步：
- 改什么（具体到文件 + 函数）
- 为什么这步是安全的
- 这步后测试应该仍然全绿
## 4. 分步执行
按计划逐步执行，每步完成后：
- 跑测试
- 如果测试失败，立即回滚这一步，告诉我原因
- 测试全绿才继续下一步
## 5. 清理
- 删除废弃的旧代码
- 更新相关注释和文档
- 跑完整测试套件最终确认
## 规则
- 不要一次性改超过 3 个文件
- 不要改变公共 API 的行为（签名可以加可选参数，不能删/改已有参数）
- 不要在重构时顺便修 bug（另开任务）
- 每一步都要可独立提交
---
需要重构的代码：
（粘贴代码或描述重构需求）
效果
不加 prompt 时 AI 经常一把梭——一次改 10 个文件，测试挂了不知道哪步出错。
加了这条 prompt 后 AI 被迫分步执行，每步验证，出问题能立即定位到具体步骤。大幅降低重构引入 bug 的概率。
分步执行长什么样
比如"把回调风格的 fetchUser(id, cb) 改成 Promise 风格"，跨 8 个调用点。这条 prompt 会让 AI 这样走：
- 影响分析：
grep出 8 处调用 + 3 个测试文件，列清单。 - 测试基线：先跑现有测试确认全绿；某调用点没测试，先补一个覆盖当前回调行为的测试。
- 计划：拆成"① 新增 Promise 版函数（保留旧版）→ ② 逐个迁移调用点 → ③ 删旧版"三步。
- 分步执行：每迁一个调用点跑一次测试；第 5 个调用点迁移后测试红了，立即回滚这一步并报告"该处依赖了回调的同步副作用"，而不是硬改完 8 个再说。
关键在第 4 步的"红了就停、回滚、报告"——这是和"一把梭"最大的区别。一把梭改完 8 个文件测试挂了，你根本不知道是哪一处引入的。
何时用这条、何时用轻量版
- 改一段代码、不跨文件 → 用 安全重构 Prompt（更轻）
- 跨文件、改签名、提取公共模块 → 用本条
验收判据：怎么判断它真的重构对了
「测试全绿」是必要但不充分的条件。补四条可执行的判据：
- 变异测试（mutation testing）——改一行源码看测试会不会红。测试全绿但改什么都不红，说明这些测试根本没在保护这次重构。 这条最容易被跳过，也最能暴露假绿。
- diff 可逆性检查——
git diff后问自己：每一步能单独revert吗？不能独立回滚的步骤，说明边界划错了。 - 行为等价性断言——重构前后对同一组输入跑一遍，比对输出。签名可以变，行为不能变；如果你说不清"行为不变"具体指什么，先补上这个断言再动手。
- 公共 API 的调用方全量编译——类型检查过不代表所有调用点都改了。跑一遍全量
typecheck/build，别只跑你正在改的目录。
第 1 条在国内团队里用得少，但它正是"重构完一切正常、三个月后线上爆雷"的对策。
变体
| 变体 | 什么时候用 | 在原文基础上加什么 |
|---|---|---|
| A · 保守版 | 改的是核心链路、没有测试保护、或你是第一次接手这份代码 | 把「不要一次性改超过 3 个文件」改成 1 个文件，并加一句「每步完成后输出 git diff 供我 review，我确认后再继续」 |
| B · 提速版 | 有完整测试覆盖、改动机械（如统一命名、批量加参数） | 删掉第 2 步的「先补测试」，改为「确认现有测试覆盖该文件后再开始」，并把步数上限放宽 |
| C · 管道版 | 要在 CI 或批处理里跑 | 配合 claude -p 类非交互模式，把「每步完成后报告」改成输出结构化结果（步骤号 / 改动文件 / 测试结果 / 是否回滚），便于脚本解析 |
变体 C 的管道写法：
claude -p "$(cat prompt.md)" --output-format json > result.json
# 然后在脚本里断言：所有 step 的 tests === 'pass'，否则整条流水线失败退出
什么时候别用这条
- 改一段代码、不跨文件 → 用 安全重构 Prompt，本条的流程开销不划算。
- 你其实是要改行为（不只是改结构）→ 这不是重构，是功能变更。先用这条 prompt 把结构理顺，再另开一次对话做行为变更，混在一起会让 diff 无法 review。
- 代码库没有任何测试且你也跑不起来 → 本条第 2 步会卡住。先把"能跑测试"这件事解决掉，否则这条 prompt 只会让 AI 假装完成了基线。
为什么有效
- 强制先做影响分析：大规模重构翻车几乎都不是因为改错，而是因为没改全——影响面清单是唯一的防线。
- 要求先建测试基线：没有绿测基线，重构后的「通过」毫无意义，这是大规模重构 Playbook 里的第一步。
- 分步执行 + 每步可验证：一次性大改会让 diff 无法 review，分步让每一步都能单独回滚。
进阶（自动化）
用 worktree 隔离重构分支，边改边跑主分支测试对照：
git worktree add ../refactor-branch -b refactor/auth
cd ../refactor-branch && pnpm test # 确认基线绿
# 每完成一步：跑测试 + 单步 commit，便于二分
git commit -am "refactor(auth): step 3 — extract token service"
并行推进多个重构任务时，见 git worktree 并行 Agent 工作流。
反例（AI 默认会写的烂版本）
默认输出：直接给一份「重构后」的完整文件，2000 行 diff，测试跑挂了也不知道是哪一步引入的。
加了 prompt 之后：先输出影响清单（12 个调用点、3 处测试、1 个导出符号），再给 5 步计划，每步一 commit、每步跑测试，第 3 步失败时能直接 revert 到 step 2。
延伸阅读
- 安全重构 Prompt · 测试生成 Prompt
- 大型重构的 AI Agent 工作流 — 把这条 prompt 嵌进完整流程
- git worktree 并行 Agent 工作流 — 变体 C 的隔离前提
更新说明：2026-10-21 新增「验收判据」「变体 A/B/C」「什么时候别用这条」三节。骨架（用法 → Prompt → 效果 → 分步示例 → 何时用 → 为什么有效 → 进阶 → 反例）未改动，仅在板块内补充内容。本次补充为编辑部方法性总结，不含任何厂商或基准数据。