用 AI Agent 跑大型重构：不翻车工作流

适用场景

任何符合下列任意一条的重构都属于"大型重构"：

• 影响超过 30 个文件
• 涉及 API 签名变更（调用方需要同步改）
• 涉及数据格式变更（DB schema / 序列化协议）
• 跨模块、跨进程
• 需要保留向后兼容

这类任务用 IDE 手改太慢，让 AI 一次性跑完又容易翻车。 本工作流的目标是：让 AI 跑大头，但每一步可验证、可回滚。

核心原则

1. 任务必须拆

不要给 AI："把整个项目从 Pinia 1 迁到 Pinia 2"。

要给 AI：

• Step A: 找出所有用 Pinia 1 API 的文件，输出清单
• Step B: 改第 1-10 个文件，跑测试
• Step C: 改第 11-20 个，跑测试
• ...
• Step Z: 全跑通后删 Pinia 1 依赖

每步独立 commit。

2. 每步都有 checkpoint

checkpoint = 一个可机器验证的状态。比如：

• pnpm typecheck 通过
• pnpm test 通过
• 启动 dev server 后 curl /health 返 200

没有 checkpoint 的步骤不要放进工作流——因为你没法知道它对不对。

3. git 隔离

每个大任务开独立分支。每个 step 一个 commit。 不要让 AI 直接 push 到主干，永远先 PR。

完整工作流：6 阶段

阶段 1：调研（人工 + AI，30 min）

让 AI 帮你回答 4 个问题：

针对【重构目标】，请回答：

1. 影响面：哪些文件会被修改？给出完整列表 + 行数估算
2. 阻塞依赖：有没有外部库 / API 升级也需要做？
3. 不可逆操作：有没有数据迁移 / 二进制格式变更？
4. 测试覆盖：现有测试能 cover 多少？哪些路径无测试？

不要开始改代码，只产出调研报告。

输出物：一份 markdown 报告。人工 review 这份报告再决定是否继续——很多时候你会发现"这个重构不该做"或"该用别的方案"。

阶段 2：拆任务（人工 + AI，20 min）

基于调研报告，请把整个重构拆成 N 个 step。每个 step 满足：

- 影响 ≤ 5 个文件
- 有明确的 checkpoint（typecheck / 测试 / 编译）
- 每步独立可 commit、可回滚
- step 之间有依赖时显式标出

输出 markdown 表格：step 编号 | 描述 | 影响文件 | checkpoint | 依赖 step

人工 review 这份拆解——如果某 step 影响超过 5 文件，强制再拆。

阶段 3：建脚手架（AI，10 min）

git checkout -b refactor/pinia-2-migration
mkdir -p .refactor
# 把拆解后的 task list 存进去

关键文件：.refactor/STATUS.md

# Pinia 2 Migration Status

- [ ] step-01: 列出所有 Pinia 1 调用点
- [ ] step-02: 改 stores/user.ts + 调用方
- [ ] step-03: 改 stores/cart.ts + 调用方
...

## Checkpoints
- [ ] all `pnpm typecheck` passes
- [ ] all `pnpm test` passes
- [ ] dev server boots
- [ ] e2e smoke test passes

让 AI 每完成一步就更新这份文件。

阶段 4：执行（AI 主导，1-N 小时）

每个 step 用同一个 prompt 模板：

现在执行 step-{N}：{描述}。

要求：
1. 只改清单内的文件，不要碰其他文件
2. 改完后跑 checkpoint：{checkpoint 命令}
3. 如果 checkpoint 失败，先 debug 失败原因，再决定是修改还是回滚
4. 成功后：
   a. 在 .refactor/STATUS.md 把这一项打勾
   b. git add 改动 + git commit -m "refactor(step-{N}): {描述}"
5. 不要继续下一步，等我确认

关键纪律：

• 每步 commit，不要憋一个大 commit
• 每步等人确认，AI 不要连续跑 5 步——很容易在第 3 步偏轨道但你没发现
• 如果 step 失败 2 次，停下来人工介入

阶段 5：合并验证（人工 + AI，30 min）

所有 step 完成后：

# 1. 跑全套测试
pnpm test
pnpm e2e

# 2. 启动 dev server，手测核心路径
pnpm dev

# 3. 让 AI 做"自我代码审查"

请审视本分支相对 main 的所有改动，找出：
- 不一致：相同模式有没有漏改的地方
- 风险：有没有可能的运行时错误（null deref、type 转换失败）
- 兼容：旧代码调用新代码会不会出问题
- 性能：有没有 N+1 查询、不必要的循环

输出 markdown 报告，每条带文件路径和行号。

人工 review 报告，必要时再开新 step 修补。

阶段 6：发布（人工，时间不定）

• 发 PR，标题写清楚 "Refactor: ..." + 影响面摘要
• PR description 直接贴 .refactor/STATUS.md 内容
• 至少一个 reviewer 看
• 合并后保留 .refactor/ 目录在 git 里作为历史记录——下次类似重构可参考

工具选择

踩坑

1. 不要相信 AI 说"我已完成"

每步都要自己跑 checkpoint 确认，不能信 AI 的口头报告。

2. 别让 AI 改测试

如果跑测试失败，AI 倾向于"修测试让它通过"——这是最危险的反模式。

明确禁止：

"如果测试失败，分析为什么失败。不允许修改测试文件——除非测试本身有 bug 且你能在改之前向我证明。"

3. 不要跨大版本改依赖

step 中遇到"顺便升一下这个库"的诱惑——说不。把依赖升级单独开 PR。

4. 注意 token 成本

跨 50 文件的重构容易烧掉 $10-50 的 token（Claude Sonnet 4.5）。先估预算再开始。

实战案例：本站项目从 src/ 改根级

我们自己用这套工作流把姊妹站 oltools.net 从 src/ 根布局改成 Nuxt 4 标准布局，影响 200+ 文件。

• 调研：30 min
• 拆任务：拆成 14 个 step
• 执行：4 小时（Windsurf Cascade，重度人工 review）
• 合并验证：1 小时
• 零线上事故

完整 commit 历史可看 oltools.net 仓库（即将开放）。

继续阅读：AI 做 PR review 工作流。