重构遗留系统工程化测试

用 AI 安全重构遗留代码:Seam、契约与等价测试

2026-08-08 · 云趣动力

失败模式:一句「重构它」毁了生产

最常见的事故长这样:开发者打开一个老代码库,选中最大的模块,输入「按整洁架构重构」,去吃个午饭。回来发现几十个文件被改、测试全绿——因为一半断言被悄悄改成了匹配新行为。它周五能跑,周一计费任务却不再触发,因为一个只在模块加载时注册的信号处理器被移到了懒加载模块里。

AI 没有说谎,它只是没有「保持初始化顺序」这条规格。所以它会无视它。

第一步:画出 Seam(接缝)

重构只有一个真正重要的定义:在保持行为的前提下,把代码搬过一条边界。你无法让 AI 把代码搬过一条你还没画出来的边界。先用只读的规划模式(如 Claude Code 的 Plan Mode)找出:

  • Seams(接缝):模块间的公开接口,这是 AI 允许穿越的线。
  • Leaves(叶子):没有其他模块依赖它的模块,最安全,先重构。
  • Roots(根):大家都依赖的底座,最后改,否则整张依赖图都会抖动。

第二步:钉死契约(Contract)

一旦知道接缝,就把它们冻结。对每一个接缝,明确写下:函数签名与参数/返回类型、异常契约、副作用声明、初始化顺序,以及一个等价测试(调用公开 API 并断言可观察结果)。

架构师法则:如果你不能在三分钟内把接缝画在白板上,AI 也无法在三小时内找到它。

第三步:绞杀者顺序

构建顺序永远是:叶子优先 → 中层 → 根最后。每个模块交给 AI 的上下文都必须写明:它拥有哪些接缝、必须遵守哪些契约、绝不可碰什么、失败长什么样(哪个等价测试必须仍通过)。

小结

你交付给 AI 的不是一个「重构后的代码库」,而是一张接缝图、一份钉死的契约和一组等价测试。剩下的活,AI 来填。

← 返回文章列表