结论先说
- 老代码重构的第一步不是改业务代码,而是补特征测试(Characterization Test)。特征测试不评判旧逻辑「对不对」,而是忠实记录当前代码在各类输入下的真实返回值、抛错类型和副作用,为后续改动拉起安全网。
- 严格区分「补测试提交」与「纯结构重构提交」。先在零业务改动的基线上让特征测试全部通过并提交到 Git,再要求 Codex 在不修改测试断言的前提下分步抽离函数或模块。
- 盘点阶段优先开只读沙箱。用
codex --sandbox read-only让模型先通读调用链、全局变量与隐藏副作用,输出依赖地图后再进入编辑模式(权限边界详见 /guides/codex-permissions-sandbox)。 - 每次只做一种结构变换,小步提交配合
/review。把「提取纯函数」「替换魔法值」「解耦外部接口调用」拆成独立步骤,每步跑通测试再用本地审查确认未混入行为改动。 - 长上下文多轮重构消耗较高额度。若国内缺少外币卡或现有档位配额吃紧,可在本站自助选购 ChatGPT Plus 充值 或配额更高的 ChatGPT Pro 充值,团队多人协作可了解 ChatGPT Business 团队定制。

图:本站根据 OpenAI Codex 官方文档:Codex CLI 及工程实践整理的示意图
本文根据 OpenAI Codex 官方文档《Codex CLI》《Command line options》《Custom instructions with AGENTS.md》及遗留代码重构工程实践整理,资料核对于 2026-11-19。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 OpenAI 官方网站。
适用于谁
- 接手缺少文档与单元测试的祖传模块,既要拆解千行大函数、又担心破坏线上隐性分支的后端与前端开发者;
- 曾让 Codex 一次性重构整个文件,结果出现边缘场景回归、差异过大难以代码审查的工程师;
- 希望建立可复现、可随时回滚的 AI 辅助重构标准流程的研发团队。
一、为什么直接让 Codex 重写老代码容易改坏线上
许多老旧核心文件(如订单结算、权限判定、报表汇总)历经多年热修,表面充满重复判断和过深嵌套,但内部往往埋着兼容历史数据的隐性分支——例如把 null 和空字符串视为不同含义、依赖特定字段的校验顺序、或顺手修改了入参对象本身。
如果直接对 Codex 说「帮我把 orderService.ts 重构得更简洁」,模型通常会出于代码审美做出三类危险操作:一是合并它认为多余的条件判断,悄悄改变了极端输入的返回结果;二是顺手升级接口签名或重命名导出符号,导致未在上下文里的外部调用方报错;三是一次生成数百行差异,代码审查者根本无法逐行核验等价性。
因此,安全使用 Codex 重构老代码的核心思路,是把「探索与锁定现状」和「调整代码结构」彻底拆开。

图:本站结合工程维护经验整理的对比示意图
二、阶段一:只读盘点依赖并补齐特征测试
在动任何一行生产代码之前,先保证 Git 工作区干净,并新建独立分支。如果不熟悉整个仓库结构,可先参考 /guides/codex-onboard-unfamiliar-project-agents-md 完成项目规则摸底。
1. 用只读模式绘制行为与副作用清单
在项目根目录启动只读会话(避免模型顺手改动文件):
bash
codex --sandbox read-only
在会话中发送第一段提示词,锁定被重构模块的外部边界:
text
请只读取 src/billing/calcDiscount.ts 及其直接调用方,不要修改任何文件。
请整理一份行为与副作用清单,包含:
1. 所有外部调用入口和参数类型(含可空、缺省与异常入参);
2. 函数内部的全部条件分支、边界阈值与抛错条件;
3. 是否读写全局变量、环境变量、系统时间、数据库或修改入参对象本身。
2. 让 Codex 生成特征测试并锁定当前行为
拿到清单后,回到常规工作区模式(建议保留审批确认),按「只新增测试文件、不碰生产源码」的原则补齐特征测试。更多测试生成细节也可参考 /guides/codex-write-tests-and-run。
text
请为 src/billing/calcDiscount.ts 编写特征测试(tests/billing/calcDiscount.char.test.ts)。
硬性要求:
1. 禁止修改 src/ 下的任何生产代码,即使发现疑似历史缺陷也先按当前真实输出断言,并在注释中标注「疑似历史行为待确认」;
2. 覆盖正常路径、空值与零值边界、叠加折扣优先级、异常抛错类型及入参是否被原地修改;
3. 如果依赖系统时间或外部客户端,仅对外部 I/O 边界做最小隔离;
4. 编写完成后运行测试命令,确认所有用例在未改动源码时 100% 通过。
核对要点:人工逐条检查测试断言,确认用例真正触发了源码中的复杂分支,而不是简单模拟返回值。确认全部绿灯后,立即执行一次独立提交,例如 test(billing): add characterization tests for calcDiscount。
订阅与账号准备提示:对千行老代码做依赖分析、补测与多轮重构会持续读取多文件上下文,容易触发额度上限(计算规则见 /guides/codex-usage-limits)。重度开发建议升级 ChatGPT Pro 5x iOS 可覆盖档 或 ChatGPT Pro 5x 信用卡不可覆盖档;新注册账号若在手机号环节遇到阻碍,可参考 Codex 注册手机验证服务。
三、阶段二:单步结构抽离与检查点验证
特征测试提交入库后,每一轮重构都遵循「单目标 → 跑测试 → 看差异 → 小步提交」的固定闭环。本站建议单次重构提交的有效业务变更控制在 150 行以内,方便逐行核对。
推荐的拆解顺序(由安全到复杂)
- 隔离外部依赖(引入接缝):先把时间获取、配置读取、日志写入等隐式依赖改成可选参数注入,保持旧签名兼容。
- 提取无副作用纯函数:把深层嵌套的折扣计算、金额舍入、状态映射抽成独立纯函数,主流程只留清晰编排。
- 收敛重复判断与魔法数字:替换为语义化常量和卫语句(Early Return),降低圈复杂度。
- 验证并清理:确认所有特征测试及原有集成测试绿灯后,再单独开一次任务讨论是否修复之前标注的「疑似历史缺陷」。
单步重构提示词模板
text
基于已通过的特征测试 tests/billing/calcDiscount.char.test.ts,对 src/billing/calcDiscount.ts 执行第一步重构:
目标仅限:将「会员等级折算」和「满减阶梯计算」提取为同文件内的两个纯函数。
严格约束:
1. 禁止修改任何已有测试文件与测试断言;
2. 禁止改变导出函数签名、返回字段名与异常类型;
3. 不要顺手重构文件其余部分或修改无关文件;
4. 修改完成后自动运行全部相关测试并展示 git diff --stat。
每次测试通过后,在 Codex CLI 中运行 /review 做一次自动代码复核(用法详见 /guides/codex-code-review),确认没有夹带逻辑语义变化再执行 git commit。若某一步把测试改红且定位困难,直接 git checkout -- . 回到上一个干净提交,比在改乱的现场继续让 AI 补救省时得多。
常见问题
问:老代码本身确实有 Bug,特征测试阶段要不要顺手一起修了?
答:不建议在结构重构中夹带 Bug 修复。特征测试阶段应忠实锁定线上现行行为,把可疑点记录成注释或工单;等结构拆清、所有测试稳定通过后,再另开独立提交专门修 Bug 并更新对应预期断言,这样上线后若出现问题能立刻区分是重构引入还是业务改动导致。
问:如果老代码强依赖全局单例或静态数据库连接,特征测试跑不起来怎么办?
答:先做最小「接缝改造」(如在文件末尾增加可选依赖注入参数,默认仍指向原有单例),保证老调用方零修改即可编译运行,再用测试传入轻量内存替身跑通特征测试,之后再逐步抽离核心逻辑。
问:国内没有外币信用卡,或者公司研发团队需要开票报销,怎么开通高配额 ChatGPT / Codex 订阅?
答:可通过本站 AI 会员充值总览 按需选择 ChatGPT Plus、ChatGPT Plus 自助卡密 或更高额度的 ChatGPT Pro,支持支付宝、微信支付与 AlipayHK,采用卡密自助兑换(无需提供账号密码)或客服协助,支持开具增值税发票;多人团队可直接在站内咨询 Business 团队定制方案。实时价格以页面显示为准,售后遵循掉订阅按剩余天数折退、封号不在质保范围的规则。
相关教程
- 用 Codex 写测试并跑通:指定函数、覆盖正常和边界并报告结果
- 用 Codex 接手陌生项目:先解释代码再用 /init 起草 AGENTS.md
- Codex 代码审查(codex review)怎么用
- Codex 权限与沙箱设置:审批模式怎么选与安全边界
参考资料
- OpenAI Codex 官方文档:Codex CLI — https://learn.chatgpt.com/docs/codex/cli
- OpenAI Codex 官方文档:Command line options — https://learn.chatgpt.com/docs/developer-commands
- OpenAI Codex 官方文档:Custom instructions with AGENTS.md — https://learn.chatgpt.com/docs/agent-configuration/agents-md
- OpenAI Codex 官方文档:Non-interactive mode — https://learn.chatgpt.com/docs/non-interactive-mode
0 条评论
还没有评论,来抢沙发~