用 Codex CLI 批量重构项目的方法
本文说明用 Codex CLI 的子代理并行能力批量重构旧项目的任务拆解方式和注意事项。
重构目标怎么界定范围
批量重构最容易失控的地方是范围不清楚，一上来就想"把整个项目都优化一遍"。比较可行的做法是先明确一个具体的重构目标（比如统一错误处理方式、把某个过时的依赖库替换掉、给缺测试的模块补上基础测试），再确定这个目标涉及哪些文件，把范围锁定清楚之后再动手。
批量任务的拆解方式
Codex CLI 支持子代理并行执行任务，OpenAI 官方文档[1]说明可以通过直接指令（比如"用多个子代理并行分析这些文件"）触发这套机制，默认最多同时开启若干个并发线程处理独立任务。拆解任务时的核心原则是：把改动范围不重叠的文件分给不同的子代理并行处理，涉及同一个文件的改动不要并行执行，避免出现合并冲突。
执行过程中的关注点
并行执行期间建议逐个检查每个子代理的输出，而不是等全部跑完再一次性审查，这样能更早发现某个子代理理解偏差的情况并及时纠正。涉及公共接口或者被多个模块依赖的核心文件，建议放在最后单独处理，避免和其他并行任务产生冲突。
效果核验
批量改动完成后，跑一遍完整的测试套件是必要的一步，不能只看代码"看起来对"就直接合并。如果项目本身测试覆盖不足，批量重构前先补一批基础测试用例，能大幅降低重构引入隐藏 bug 的风险。
常见问题
批量重构一定比逐个文件手动处理快吗？
在文件之间改动相互独立的场景下确实更快，但如果文件之间耦合度很高，并行处理反而容易出现冲突，需要更多时间做后续整合。
子代理数量是不是开得越多越好？
不是，子代理数量增加会带来更高的 token 消耗和更复杂的结果整合成本，一般建议按实际独立任务数量设置，不需要盲目追求并发数量。
重构涉及数据库结构变更能不能也批量处理？
不建议，涉及数据库结构这类高风险变更，建议单独、谨慎地处理，并配合完整的回滚方案，不适合放进批量并行任务里。