用 Agent 的思路管理 AI Coding:31 万行代码重构的实践
项目始于一次例行体检:核心业务仓库 31 万行 TypeScript,重复代码率 18%,循环依赖 47 处,平均单文件修改后的类型检查耗时 6 分 40 秒。人已经改不动了——不是不会改,是每次改动带来的不确定性超过了收益。
我们最终选择让 AI 参与重构。但不是「把需求丢给模型」,而是把重构本身工程化。
一、先定义什么叫「改对了」
重构最大的风险不是改错,而是不知道有没有改错。所以第一步不是写代码,是建立验证网。
我们盘点了三层防线:
- 类型系统:
tsc --noEmit必须零错误,这是硬门槛; - 单测覆盖率:重构前把核心模块覆盖率从 41% 补到 76%,补的都是”行为快照”而非断言细节;
- 视觉回归:对 120 个关键页面截图做像素比对,容忍度 0.1%。
有了这三层,每一次批量改写都能在 10 分钟内得到”是否可以继续”的答案。这是整个项目能推进的前提。
二、把重构拆成任务单元
31 万行不可能一次性交给模型。我们按「可独立验证」的原则切成四类任务:
| 任务类型 | 示例 | 单批规模 | 验证方式 |
|---|---|---|---|
| 机械替换 | 旧 API → 新 API | 150–200 文件 | 类型检查 |
| 结构迁移 | Class 组件 → Hooks | 30–50 文件 | 单测 + 截图 |
| 去重合并 | 12 个相似 Table → 1 个 | 1 个模块 | 人工 review + 快照 |
| 依赖治理 | 拆循环依赖 | 1 条链路 | 构建产物对比 |
单批控制在 200 文件以内是有原因的:批次越大,出问题后的定位成本呈平方增长,而模型在长上下文里的改写质量会明显衰减。
三、流水线:让模型只做它擅长的事
我们的流水线长这样:
扫描 → 生成改写规则 → 模型批量改写 → AST 校验 → 类型检查 → 单测 → 分批合并
关键设计是尽量不放权给模型。凡是能用 codemod 表达的,就不让模型逐文件生成。
// 规则先由模型归纳,再由人确认为可执行 codemod
const rule = {
match: (node) => node.type === 'CallExpression'
&& node.callee.name === 'fetchUserInfo',
replace: (node) => t.callExpression(
t.memberExpression(t.identifier('userApi'), t.identifier('get')),
node.arguments
),
};
模型负责归纳规则和处理规则覆盖不到的边角,codemod 负责高频、确定的 80%。这样一来,同批次输出的一致性从 63% 提到了 97%,review 成本下降了一个数量级。
对于必须逐文件生成的场景(比如组件重写),我们给模型的输入固定为四段:
【契约】必须保持的对外行为(props、事件、DOM 结构)
【上下文】该文件被谁引用、引用了谁
【约束】禁止引入的新依赖、代码风格
【样例】同批次已验收的一个改写结果
第四段是最容易被忽略、收益却最大的一段——给一个”已验收样例”比写十条规则更有效。
四、批次管理与回滚
每个批次是一个独立分支,命名 refactor/<类型>-<序号>,必须满足:
- 类型检查零错误;
- 单测全绿;
- 截图差异人工确认为预期内;
- 变更行数不超过 3000 行。
不满足就整批回滚,不做局部修补。局部修补会让批次失去”可回滚”这个最重要的属性。
六个月下来,共执行 214 个批次,其中 31 个被整批丢弃。这个丢弃率(14%)是健康的——它说明验证网真的在拦东西。
五、结果
| 指标 | 重构前 | 重构后 |
|---|---|---|
| 重复代码率 | 18% | 6.4% |
| 循环依赖 | 47 | 3 |
| 单文件改动的类型检查耗时 | 6m40s | 1m50s |
| 新同学上手第一个 PR 的耗时 | 4.2 天 | 1.6 天 |
| 线上事故(重构引入) | — | 2 起,均为 P3 |
两起事故都发生在”去重合并”类任务里,原因是两个相似组件的行为差异没有写在契约里。后续我们把这类任务的契约改为差异清单:不写相同点,只列不同点,逐条确认。
六、几条经验
AI 擅长的是”有明确验收标准的重复劳动”。 判断一个任务该不该交给它,看验收标准能不能写成脚本。
不要指望它理解业务。 它能理解的是你给它的契约。契约写得含糊,输出就一定含糊,而且错得很自信。
人工 review 的重心要转移。 从”这行代码对不对”转到”这批改动的边界对不对”。前者模型做得比人快,后者只有人能判断。
半年之后,这个仓库的日常迭代基本回到了正常节奏。真正的收获不是省了多少人天,而是团队重新获得了「敢改」的信心。