用 Codex 高效完成上万行代码重构

最近，我对 Fread 项目进行了一次大规模重构，借助 Codex（一款 AI 编程助手）完成了超过一万行代码的修改。放在过去，人工处理这样的任务至少需要一个多月，而现在仅用几天就顺利收工。本文将详细分享整个过程中的心得体会与实用技巧，希望能为正在经历重构挑战的开发者提供一些启发。

本次重构主要聚焦于两个方向：一是将依赖注入框架从 kotlin-inject 迁移至 koin，二是用 navigation3 替换原有的导航框架 Voyager。

选择 Koin 的主要原因在于，其 DSL 风格的管理方式更符合个人编码偏好，代码表述清晰直白，理解成本较低。说实话，依赖注入涉及的类实在太多，使用注解不仅会带来较强的侵入性，还会生成大量无法窥见内部逻辑的辅助类，导致整个注入流程如同黑盒，调试起来相当棘手。

至于导航框架，Voyager 已超过一年未更新，基本处于被维护方弃置的状态。而 Nav3 的设计更为优雅，对预测性返回和 Shared Element 的支持表现优秀，没有理由不选择它。

可想而知，这是一场硬仗——几乎每个页面都需要调整，依赖注入也需全线翻新。不过，有赖于 Codex，据不完全统计，大约 70% 的代码由它生成。本文就来聊聊具体是如何操作的。

（附上本次改动的 PR 链接：github.com/0xZhangKe/F…）

充分利用 AI 的模仿能力

使用下来最大的感受是：AI Coding 最擅长的并非创造，而是模仿。对于给定的模式，Codex 可以模仿得相当出色，即便偶尔出现一些小意外，它也能顺势解决。

因此，在这次重构中，我作为人类的角色，核心任务其实是找出所有不同类型的变更，再将其分类处理。举个例子，kotlin-inject 在项目中的用法就那么几种固定模式，针对每种情况分别用 koin 编写一份对应的重构代码。这样一来，每种场景下的转换关系就变成了有限的、一一对应的模式。随后，我直接让 AI 参照这几份样板代码进行模仿，逐一改造剩下的部分。

这种方法能大幅降低 Codex 面临的问题复杂度——它只需按部就班地模仿，逐个击破即可。越是复杂的问题，Codex 越容易出错。刚开始我尝试让它一次性重构整个依赖注入，结果它跑了 1.5 小时，不仅耗光了多轮上下文，还烧掉了整整五小时的用量，最终问题仍未解决。原因在于依赖关系过于复杂，连它自己也绕得晕头转向。

此外，这种做法的好处还在于可控性。毕竟我对整个软件架构的理解远胜于 AI，清楚正确的演进方向。因此分工变得清晰：我发挥自身专长，先将复杂问题拆解干净，剩下的海量重复性劳动交给它来完成——各司其职，效率才能最大化。

现在，当使用 Codex 处理大型任务时，我通常会先提供一个最佳实践的代码样例，让它照此执行。

特殊情况特殊处理

Fread 是一个跨平台的 KMP 项目，依赖注入不仅存在于通用代码层，还涉及多个平台实现层。这些情况叠加在一起，复杂度显著上升。

很多时候，这类特殊情况若由我们人类处理，可能只需几行代码、几分钟就能搞定。但 AI 需要思考很长一段时间，而且对其而言，复杂度是成倍增加的。一方面，Codex 对 KMP 项目的了解有限；另一方面，对于如何正确处理平台实现层，它也很难给出理想的方案。

针对这类问题，我的解决策略是：逐步推进，交替上阵。先人工编写一部分代码，然后交给 Codex 解决剩余部分；再人工写一部分，再交给 Codex……如此循环往复。

具体如何操作呢？在每个存在依赖注入的模块中，我都会声明一个 expect 函数，并在当前的 Koin 模块中注册它：

expect fun Module.createPlatformModule()
val commonModule = module {
    createPlatformModule()
}

然后在 Android/iOS 平台上分别创建具体的实现：

actual fun Module.createPlatformModule() {
}

我先完成这一步，随后让 Codex 在所有模块中添加相同的改动。

接下来，需要将这些平台实现中的依赖注入模块注册原有的 kotlin-inject 类。这样一来，事情就简化了：我只需指导 Codex 将 kotlin-inject 模块中的声明同步到 Koin 的平台级模块中。这种任务 Codex 可以完成得非常出色。

然后重复以上步骤，直到所有模块的重构工作全部完成。

任务拆分至关重要

Codex 的上下文有限，处理复杂任务时很容易“走着走着就忘了初衷”，甚至会自作主张对代码做一些奇怪的改动。

拆分的逻辑是：复杂任务、架构相关的工作仍然由人完成。这部分搞定之后，就能拆分出独立且简单的子任务，交给 Codex 去处理。这样一来，即便 Codex 犯错，影响范围也很有限，回滚代码时也能节省更多的 token。

有一点个人习惯：AI 生成的代码，我一定会全部 review 之后才 accept。若不进行任务拆分，review 的工作量太大，恐怕连我自己的大脑也招架不住。

复杂问题使用 SKILL

用 Nav3 替换 Voyager 这个任务，需要改动的代码非常多，其中包含了大量重复性工作。就算让 AI 完全按照写好的最佳实践来模仿，但由于代码量巨大、任务复杂，Codex 仍然可能出错。这时就可以通过创建 SKILL 来解决。

（此处为原文中较长的 SKILL 定义代码，包含任务背景、任务内容、工作流程和绝对禁止规则等核心内容，此处按其原文样式保留）

在这个 SKILL 里，我写了一些“绝对禁止”的行为，本质上就是在规避特殊情况——也就是上面提到过的“特殊情况特殊处理”。这样能极大降低任务复杂度。

如果能定义好具体的 workflow，并且要求 Codex 必须严格遵守，那么它出错的可能性就会小很多。

单元测试验证

另一个可行的思路是：先让 AI 针对任务编写足够多的单元测试，确保重构前的代码全部能通过。然后进行大规模重构后，再次运行这些单元测试，以此确保软件稳定性。不过 Fread 这次重构涉及大量 UI 代码，编写单元测试比较麻烦，因此这个环节就跳过了。

提交并 Review

按照上述步骤，每次完成一个小任务后，都可以创建一个提交，然后新建一个对话来 review 这次提交。新建对话的目的是丢弃之前的上下文，作为一个全新的任务交给 AI，否则它很可能会为自己的问题自圆其说，反而影响 review 的质量。