我们如何用Codex辅助重构旧项目

我们如何用Codex辅助重构旧项目

去年年底，我所在的技术团队接手了一个维护了四年多的旧项目。这个项目代码库膨胀到300多个TypeScript文件，依赖了47个npm包，其中11个已经停止维护超过一年。当我第一次在团队会议上提出“让Codex来帮忙重构”时，技术总监看了我一眼，说了句让我记到现在的话：“AI写的代码，到时候出了问题谁负责？”

三个月后，还是他，在复盘会上对所有人说：以后新项目能不能也考虑用AI辅助重构流程。

这个转变不是因为Codex有多完美，恰恰相反，是因为我们终于弄清楚了它到底能干什么、不能干什么。更重要的是，我们弄清楚了“人”在AI重构过程中应该扮演什么角色。

这篇文章不打算给你看那种“输入一行Prompt，AI帮你重写整个项目”的爽文。我要分享的，是真实踩过的坑、做过的取舍，以及一套能让AI真正帮你干活的协作方案。

一、你以为的就是你以为的吗，三个认知先讲清楚

在进入具体方法之前，先对齐三件事。这三件事直接决定了你和一个代码AI合作时的“协作姿势”。

第一，Codex的最大优势不是“能写代码”，而是“能读整个项目”。

很多人用AI写代码的感受是：写个工具函数没问题，但它不知道你这项目里还有另外一个函数已经实现了差不多的逻辑。Codex对比其他工具最根本的区别，在于它会把整个项目当成一个上下文去理解。这不是说它更聪明，而是它“视野”更大。你不需要手动告诉它“这个项目用了Redux”、“我们的异常处理统一走handleError这个工具函数”，它自己能读出来。这能力对重构来说至关重要，因为你改一个文件，往往要同时改十几处调用它的地方。

第二，AI重构的能力上限，不取决于AI本身，取决于你项目的“安全网”厚度。

这一点我几乎在每一场内部培训里都会反复强调。我们在这个旧项目上的第一个大动作，不是打开Codex开始重构，而是用两周时间补齐了单元测试覆盖率。原先覆盖率只有百分之十几，我们硬是补到了接近70%。为什么？因为当AI一次性给你修改了40个文件的时候，如果你没有一个能自动跑通并告诉你“哪里坏了”的测试体系，你相当于把自己的生产环境当成了QA环境。这不是AI的问题，是你的问题。

第三，AI重构的成功率不是99%，在我们这里，AI初稿的“一次通过率”只有60%左右。

这里“一次通过”指的是：AI给出的改动，人Review之后不需要二次修改就能直接合入。在我们这个300多文件的项目里，真正复杂的那部分逻辑，你去问任何一个在这个项目上干过半年的开发者，他们都会告诉你，这部分的改动十次有六次需要返工。这不是失败，这是现实。如果你对AI的预期是“一次搞定”，那你一定会失望。但如果你对它的预期是“帮我搞定60%的脏活累活”，那你赚了。

二、失败案例比成功案例更有价值，那些Codex没能搞定的事

我坚持认为，学一个工具最好的方式是看它怎么失败。因为在失败里，你才能看到它的能力边界。这里有三个让我印象深刻的“翻车”现场。

翻车一：依赖包替换，“它改完了，但一半功能坏了”

我们项目里有一个很经典的遗留问题：前任架构师深度绑定了@electron/remote这个已经废弃的依赖，需要全部迁移到@electron/ipcMain加@electron/ipcRenderer的通信方式。涉及42个文件，调用链分散在渲染进程和主进程之间。

我先尝试把整个任务描述扔给Codex，让它全自动修改。它在不到十分钟内给出了修改方案。但当我跑测试的时候，渲染进程里有七个地方的remote调用被它直接删除了，因为它没理解“这条调用链最终会跨进程触发主进程里的一个文件操作”。它还修改了两处主进程的调用，让它们“看起来符合新的IPC写法”，但入参类型全错了。

最后真正有效的修改，只有大约一半。

这类“牵一发而动全身”的依赖重构，AI最大的问题不是它不想做好，而是它对于跨文件、跨进程、跨模块的深层调用链，没有真实的理解。它看到的是一堆字符串，你用人类思维制定的架构规约，在Token化的过程中已经被打散了。

所以后来我们建立了一条规则：凡是涉及跨三层以上调用链的依赖替换，先让人画出影响面依赖图，再让AI逐个模块去改。人在中间承担的是“架构理解”的角色。

翻车二：风格一致性，它做到了局部优雅，也带来了全局分裂

Codex对现代前端最佳实践的掌握是顶级的。我们有一次让它重写了一个用户列表组件，从Class写法改到Hooks，写得非常漂亮，命名清晰，状态管理逻辑合理。但问题是，这个组件旁边还有一个用户详情组件，也是老的Class写法，两者的文件命名规则、目录组织方式、状态变量的命名风格完全割裂。

这导致的一个隐性后果：新加入团队的开发者开始困惑“这项目到底有没有统一的规范”。AI没有帮你维护“项目一致性”的内在驱动力，这是人的活儿。

这次教训之后，我们在项目根目录增加了文档化的架构规约，并且在每次AI生成的代码里，特别检查“你的写法是否与相邻模块保持风格统一”。

翻车三：它太想“优化”你的代码了

有一次，我让它把一段核心业务计算逻辑里的性能瓶颈解掉。它确实优化了，它把一段用for循环实现、每个开发者都能一眼看懂的计算逻辑，重构成了一套高度抽象的函数式组合，用上了柯里化、高阶函数，还自己封装了一个utils。

从技术上看，没毛病，甚至可以说很优雅。但这段逻辑是账务相关的计算，每个月财务团队都要对着它审计。当我拿着AI改过的代码跟财务那边的技术对接人沟通时，他说了一句让我至今记得的话：“这还能看懂吗？”

对于维护期的旧项目来说，“可读性”和“可维护性”永远大于“技术上的优雅”。尤其在业务逻辑层，你的代码需要让一个接手不到三个月的新人能看懂、能改、敢改。AI的“过度优化”实际上是在增加维护负担。

三、人的角色变了，从“写代码的人”变成“做决策的人”

在踩完上述坑之后，我们内部形成了一个共识：用AI重构旧项目，不是在指挥一个超级程序员在帮你干活，更像是在和一个能力极强但经验不足的实习生合作。他能帮你处理大量重复、枯燥的体力劳动，但你必须要承担架构判断、风险评估、代码评审的责任。

所以我们把“人”的角色拆成了三个：

第一，做“风险分级”的决策者。

不是所有旧代码都适合让AI去重构。我们在项目里建立了一个简单的风险评估模型：

这个表格帮我们节省了大量沟通成本。团队里的每个人都知道，什么任务可以放心交给AI，什么任务必须自己上。

第二，做“协作流程”的设计者。

我们磨合出了一套相对标准化的协作流程。不是让AI全自动跑，而是让它在人的决策框架内工作：

1. 人在Issue里把任务拆碎，明确边界和期望结果（例如：“将UserProfile组件从Class写法改为Function组件，保持现有props接口不变，不要修改相邻组件”）。
2. AI基于完整上下文生成修改，并输出一份变更报告（我们要求它在PR description里写清楚“改了什么文件、为什么这么改、哪个地方的判断它不确定”）。
3. 人Review，在代码diff上对每一处有疑问的地方进行批注。批注分两种：“这里OK”和“这里有问题，因为XX原因，请按YY方向调整”。
4. AI根据批注进行二次修改，人最终确认合入。

这本质上是人机协同的“双向反馈”过程。人给出战略方向，AI执行战术动作，人再对战术结果进行校准和纠偏。

第三，建立“AI输出验收清单”。

我们制定了一份针对AI生成代码的检查清单，每个开发者在CR时必须逐项核对。这份清单来源于我们所有翻车经验的总结：

• [ ] 是否引入了新的不必要的依赖？
• [ ] 异常处理分支是否完整？（AI特别容易只考虑Happy Path）
• [ ] 是否有无意义的类型断言？（面对不懂的类型，AI有时会用as any强转，掩盖问题）
• [ ] 性能敏感路径里的循环/递归是否被错误替换？
• [ ] 命名风格是否与相邻模块一致？
• [ ] 是否在核心业务逻辑中引入了难以理解的抽象？
• [ ] 产生的TypeScript、ESLint告警是否全部处理？

这七条看起来简单，但每一条背后都有至少一次线上告警的教训。

四、结论：AI是加速器，不是自动驾驶

回到开头那个问题，技术总监担心AI写的代码出问题谁负责。答案是：永远是人负责。AI不会为任何一个Bug买单，也不会半夜起来修生产环境的紧急问题。

但我想说的是，在搞清楚AI的能力边界之后，你并不会觉得它“没用”。恰恰相反，你会开始找到正确使用它的方式，把它当成一台高效的“理解机器”和“执行机器”，它帮你去处理那些费时间但不费脑子的活，而你，把自己的精力集中在“决策”和“判断”上。

在重构旧项目这件事上，AI能让你从一个“搬砖工”变成“施工队队长”。你依然需要懂架构、懂业务、懂判断，但AI让你的执行效率提升了不止一个量级。

如果你正在考虑在你的旧项目上尝试Codex，我的建议只有三条：

1. 先补测试，后动代码。没有安全网的AI重构是在定时炸弹上跳舞。
2. 不要一口气把你的整个项目扔给它。拆碎了喂，一点一点验收。
3. 做好打60分就接受的心理准备。剩下的40分，靠你的经验和判断去补齐。

最后想问你一个问题：你让AI帮你改过最让你崩溃的一次代码是什么？或者说，你有没有被它“惊喜”到过？欢迎分享你的故事，我特别想听听其他团队踩过的坑。

因为说到底，在这个AI编程工具层出不穷的时代，最有价值的不是某个工具的单点能力，而是我们作为开发者，如何学会和它们真正高效地协作。