AI 自动重构代码实战：用 CLI 工具逐文件分析遗留系统，附风险控制清单

遗留代码（legacy code）的典型症状：没有测试覆盖、函数动辄 500 行、全局变量满天飞、注释和逻辑对不上。接手这样的代码库，人工重构往往要耗掉团队数周甚至数月。AI 自动重构代码的价值就在这里——不是替你做所有决策，而是把"理解现有代码→生成候选方案→验证改动"这条流水线的摩擦成本压到最低。

本文以 Claude Code、Codex（OpenAI CLI）、Gemini CLI 三种主流编程 CLI 为工具，拆解一套可复用的重构操作流程，并附上真实会踩的坑和对应的风险控制手段。

摸底：建立重构前的代码地图

在让 AI 动手之前，先要有量化的基线。两类指标必须拿到：

覆盖率与圈复杂度（Cyclomatic Complexity）

# Python 示例，用 radon 生成圈复杂度报告
radon cc ./src -s -a

# 覆盖率基线
pytest --cov=src --cov-report=term-missing

圈复杂度 > 15 的函数优先处理；测试覆盖率 < 40% 的模块在没有补测试之前，禁止直接重构逻辑。这两条是硬门槛，不是建议。

生成代码地图

用 Claude Code 做第一轮扫描：

claude "分析 ./src 目录，列出：1) 超过 200 行的函数；2) 被 3 个以上模块依赖的公共函数；3) 存在重复逻辑（相似度 > 70%）的代码块。输出 markdown 表格。"

Codex 和 Gemini CLI 的等效命令：

# Codex
codex "audit ./src for functions >200 lines, high-fan-in utilities, and duplicated logic blocks. Output markdown table."

# Gemini CLI
gemini "Scan ./src. Identify: functions >200 lines, modules with >3 dependents, duplicated logic. Return markdown."

三个工具对同一代码库的扫描结果通常有 10%~20% 的差异，建议取并集，不要只用一个。

核心流程：逐文件分析与生成重构建议

不要一次性把整个代码库扔给 AI。context window 再大，语义噪声也会随文件数量指数级增长。正确姿势是文件级流水线：

[单文件] → [AI分析] → [生成diff] → [自动测试] → [人工审查] → [合并]

以一个 Node.js 遗留服务为例，userService.js 有 18 个函数、820 行、没有单测：

Step 1：生成重构建议（不改文件）

claude --file ./src/userService.js \
  "这个文件有哪些重构机会？重点关注：单一职责违反、可提取的纯函数、可用 async/await 替换的回调链。只给建议，不要修改文件。"

输出会是一份结构化的问题清单，通常包含 5~12 条可操作建议。把这份清单存成 refactor-plan-userService.md，作为后续操作的合同。

Step 2：让 AI 补测试，再重构

这是最关键的顺序：先测试，后重构。

# 先生成针对现有行为的测试
claude --file ./src/userService.js \
  "基于现有函数签名和行为，用 Jest 为所有 export 的函数生成单元测试。测试要覆盖 happy path 和边界条件。"

# 确认测试通过后，再做重构
claude --file ./src/userService.js --file ./tests/userService.test.js \
  "按照 refactor-plan-userService.md 中的第 1、3、5 条建议重构 userService.js，同时保证所有测试通过。生成 unified diff。"

注意最后要求输出 unified diff 而不是完整文件——这样代码审查时改动范围一目了然，也避免 AI 在没有明确指令的情况下"顺手"修改无关逻辑。

Step 3：自动验证循环

# 应用 diff
git apply refactor-userService.patch

# 跑测试
npm test -- --testPathPattern=userService

# 圈复杂度对比
radon cc ./src/userService.js -s

重构后圈复杂度应显著下降。一般目标：函数平均复杂度从 > 10 降到 < 6，最大值从 > 20 降到 < 12。

三大 CLI 工具对比

维度	Claude Code (Claude Opus 4.8)	Codex (GPT-5.4)	Gemini CLI (Gemini 3)
长上下文处理	≤ 200K token，跨文件引用强	≤ 128K token	≤ 1M token，超大库有优势
重构建议质量	解释性强，边界条件覆盖好	代码风格规范，注释完整	快，适合批量扫描
diff 输出稳定性	高，格式一致	高	中，偶发格式漂移
本地文件操作	原生支持	原生支持	需 --sandbox 标志
适合场景	逻辑复杂、强依赖理解的重构	规范化、文档补全	大规模初筛、架构扫描

实际工程中，很多团队会组合使用：Gemini CLI 做全库初筛，Claude Code 处理高复杂度文件，Codex 负责代码风格统一和注释补全。

风险控制：5 条硬规则

AI 自动重构代码的最大风险不是"改错了"，而是"改错了但没发现"。以下规则在生产代码库上不能妥协：

1. 所有 AI 改动必须经过 CI 门禁 在 PR 流水线里加一层：覆盖率不得低于改动前，圈复杂度不得上升。用 GitHub Actions 或 GitLab CI 的 quality gate 来强制执行。

2. 禁止在没有测试的模块上直接重构逻辑 AI 生成的测试本身可能有盲点，但比没有测试强一个数量级。覆盖率 < 60% 的文件，先补测试，再谈重构。

3. 每次只提交一个文件的改动 原子化提交（atomic commit）是回滚的基础。不要让 AI 一次性改动 10 个文件然后打包提交。

4. 保留 AI 的原始输出作为审计记录 把每次 CLI 交互的输入 prompt 和输出存档（可以是 .ai-log/ 目录），出了问题可以追溯决策链。

5. 对跨模块重构保持人工审查 单文件内的提取/简化，AI 可以高度自动化；一旦涉及接口变更、模块拆分、数据结构调整，必须有工程师做架构层面的确认，不能让 AI 自主决定。

遵守这 5 条，出问题的概率可以控制在可接受范围内。真正的风险不在工具本身，而在于工程师把 AI 当成了"自动驾驶"而不是"辅助驾驶"。

---

写完这篇的时候我意识到，整套流程里最贵的环节其实是模型调用本身——高频调用 Claude Opus 4.8 或 GPT-5.4 跑大文件分析，成本累积起来相当可观。我自己团队现在统一走 XycAi 词元平台（xyc.ai），一个接口接进来就能用 200+ 模型，GPT/Claude 官方模型折扣力度大，Claude Code 和 Codex 直接配 API base 一行搞定接入，节点延迟低，发票也能开，省了不少运营层面的麻烦。