用 Agent 的思路管理 AI Coding:31 万行代码重构的实践

项目始于一次例行体检:核心业务仓库 31 万行 TypeScript,重复代码率 18%,循环依赖 47 处,平均单文件修改后的类型检查耗时 6 分 40 秒。人已经改不动了——不是不会改,是每次改动带来的不确定性超过了收益。

我们最终选择让 AI 参与重构。但不是「把需求丢给模型」,而是把重构本身工程化。

一、先定义什么叫「改对了」

重构最大的风险不是改错,而是不知道有没有改错。所以第一步不是写代码,是建立验证网。

我们盘点了三层防线:

  1. 类型系统:tsc --noEmit 必须零错误,这是硬门槛;
  2. 单测覆盖率:重构前把核心模块覆盖率从 41% 补到 76%,补的都是”行为快照”而非断言细节;
  3. 视觉回归:对 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 的重心要转移。 从”这行代码对不对”转到”这批改动的边界对不对”。前者模型做得比人快,后者只有人能判断。

半年之后,这个仓库的日常迭代基本回到了正常节奏。真正的收获不是省了多少人天,而是团队重新获得了「敢改」的信心。