用 Codex CLI 给祖传代码做大扫除：一个晚上跑通的实战方法
一句话：每个工程师电脑里都有那么一个项目：3 年没动过、测试覆盖 12%、上一次维护那个人已经离职、注释里残留着 2022 年的"等以后再改"标记。每次想动它都两难——"不动它老板下一个迭代过不去 / 动它一周交不了别的活"。 Codex CLI（OpenAI 的命令行编码助手，配合 GPT-5.3 Codex 模型）让"动它"的成本压到一个晚上。本文不是"AI 万能"的鸡汤——而是把"祖传代码大扫除"这件事拆成 4 个具体阶段：诊断、接入、多代理拆任务、跑崩瞬间复盘。每一步都有可复制的命令与 spec。一个晚上跑完一个典型中型 Python 项目，成本估算 $1-3。
目录
祖传代码的三种典型病症
跑大扫除之前，先把"祖传"具体化。绝大多数你不想动的老项目落在三种典型病症里——每种诊断方式不同，重构的优先级也不同。
病症 | 典型表现 | 危害 | 适合的 Codex 任务 |
|---|---|---|---|
屎山型 | 函数 800 行、嵌套 6 层、变量名 | 改 A 出 B、回归测试盲区 | 拆函数、重命名、抽公共逻辑 |
化石型 | 依赖 5 年没升级、Python 3.6、jQuery 1.x | 安全洞、CVE 警告、新手不会用 | 依赖批量升级 + API 适配 |
失忆型 | 没文档、没测试、原作者离职、注释全是"see slack" | 没人敢改、知识只存在前同事大脑里 | 自动生成文档 + 单测覆盖 |
实际项目通常三种叠加——这就是为什么"看着想重写"的冲动来得那么强。但全推倒重写的项目八成会失败（行业数据：>60% 的"rewrite from scratch" 项目超期或 abandon）。Codex CLI 的玩法是在原结构上做手术，而不是推平重建。
重构前的诊断：先弄清楚要改什么
不要打开 Codex 就一句"重构这个项目"。这句指令的成本会爆掉而且效果差——AI 不知道你的优先级、不知道哪些是历史包袱哪些是必要复杂度。
诊断花 15 分钟，省后面几小时返工。三个动作：
1. 跑一遍可量化的"病症体检"
# Python 项目：
pip install radon vulture pylint
radon cc -a -s . # 圈复杂度
radon mi -s . # 可维护性指数
vulture . # 死代码扫描
pylint --output-format=json . # 综合报告
# JS/TS 项目：
npx complexity-report-html ./src # 复杂度
npx ts-prune # 死代码
npx depcheck # 没用的依赖把输出存成 legacy-audit.txt。这是后面 Codex 决策的输入材料。
2. 列一份"动什么不动什么"清单
# 创建 refactor-scope.md，回答 4 个问题：
# 1. 哪些模块的圈复杂度 > 15？（必动）
# 2. 哪些函数 > 100 行？（拆）
# 3. 哪些依赖有 CVE 警告？（升）
# 4. 哪些代码 vulture 标了死代码？（删）第 4 条要谨慎——动态语言里"死代码"经常其实是被反射调用的。打 # vulture: ignore 标记不删的部分。
3. 备份 + 建分支
git checkout -b refactor/legacy-cleanup-2026q2
git commit -am "checkpoint: pre-refactor baseline"Codex CLI 的执行是 destructive 的——不挂分支直接动 main，撤回成本翻倍。
Codex CLI 5 步接入
Step 1：装 CLI（约 30 秒）
npm install -g @openai/codex
codex --version需要 Node.js 18+。Windows 推荐 WSL2。
Step 2：拿一把 CodeGateway API Key（约 2 分钟）
直连 OpenAI 也行。本文走 CodeGateway，原因：
- Stripe 多种支付方式（Alipay / Apple Pay 等），邮箱注册即开始
- 新账号绑定支付方式后可获得起步额度——折算购买力随所选模型价格变动，以 /models 定价页折算为准，够诊断 + 一轮重构试跑
- 长任务比直连稳——10 万行级 codebase 全量分析跑过 8-12 分钟，断流过一次（详见后面"跑崩瞬间"那节）
注册 https://www.codegateway.dev → Dashboard → API Keys → Create Key，命名建议 codex-laptop。
Step 3：配环境变量（约 1 分钟）
# ~/.zshrc 或 ~/.bashrc
export OPENAI_BASE_URL="https://api.codegateway.dev/v1"
export OPENAI_API_KEY="sk-cg-xxxxxxxxxxxxxxxxxxxxxx"source 一下生效。
Step 4：验证连通（约 30 秒）
curl https://api.codegateway.dev/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" | grep gpt-5.3-codex返回里能看到 gpt-5.3-codex 这一条就 OK。
Step 5：第一句指令（约 30 秒）
cd legacy-project/
codex "总结这个项目的整体架构，并列出 5 个最值得重构的点。"Codex 会自己 grep / 读文件 / 跑指令，最终给你架构概览 + 优先级清单。这条命令本身的成本一般在 $0.05-0.15——把它当作"和项目首次握手"。
多代理拆任务：把"重构"切成 9 件可调度的事
直接让 Codex 跑"重构整个项目"会出两个问题：上下文窗口塞爆、代价巨大且难以验证。正确做法是把任务拆成 9 件粒度可控的事，按依赖顺序跑。
任务分解模板
把下面的 9 个任务保存成 refactor-tasks.md：
1. ARCHITECTURE: 输出当前架构图（Mermaid），定位重构入口
2. DEAD-CODE: 删除 vulture 标记的死代码（保留 # vulture: ignore 注释的部分）
3. RENAME: 把所有 tmp1/tmp2/foo/bar 这类变量名替换成语义化命名
4. SPLIT: 拆 100+ 行的函数为单一职责的小函数
5. TYPES: 给所有公共 API 加类型注解（Python: typing；TS: 显式接口）
6. DEPS: 升级有 CVE 警告的依赖到次新版本，跑一次完整测试
7. TESTS: 为圈复杂度 > 15 的核心模块补单元测试
8. DOCS: 给 public API 加 docstring，生成 README 的 "API Reference" 段
9. REVIEW: 跑全量测试 + lint，输出 diff 摘要 + 风险点用 sub-agent 并发跑
Codex CLI 支持 /agents 调度子代理。任务 1（架构图）必须最先跑，任务 9（review）必须最后跑。中间 7 个任务有些可并行（DEAD-CODE 和 RENAME 互不影响 → 并行；TESTS 必须在 SPLIT 之后 → 串行）。
codex << 'EOF'
请按以下顺序跑：
1. 先跑 ARCHITECTURE，把结果写到 docs/architecture.md
2. 然后并发跑 DEAD-CODE、RENAME、TYPES 三个子代理
3. 这三个完成后，串行跑 SPLIT → TESTS
4. 与 SPLIT 并行跑 DEPS（不冲突）
5. 然后跑 DOCS
6. 最后跑 REVIEW
每个任务完成后写一个 commit，subject 写 "refactor: <task-name>"。
EOF主代理负责调度，子代理负责执行。Codex 会自己拆 git commit，跑完一个任务一个 commit，方便你逐步审查 + 出问题回滚。
子代理选模型的省钱策略
ARCHITECTURE / REVIEW：架构推理 + 综合判断 → gpt-5.3-codex（默认主力）
RENAME / DEAD-CODE / DOCS：机械性强，规则明确 → 切到 gpt-5-mini 或更便宜的模型，单代理成本可压到 1/3
TESTS / SPLIT / TYPES：需要理解上下文但又重复性高 → gpt-5.3-codex 主力
把这套规则写到 .codex/policy.md，Codex CLI 启动时自动加载，子代理调度按规则选模型，不用每条命令手动指定。
一个晚上的成本估算（典型场景）
数据声明：以下是基于一个典型中型项目（约 30K LOC Python、~150 文件、~12K test LOC）的估算成本结构，不是单一项目的真实账单。Codex CLI 实际定价和 token 消耗会因项目大小、代码密度、迭代轮次显著浮动。本文按 GPT-5.3 Codex 价格 + CodeGateway 统一的 1.07× 倍率展开。
9 个任务的 token 消耗估算
任务 | 输入 token（千） | 输出 token（千） | 估算成本 |
|---|---|---|---|
ARCHITECTURE | 80 | 8 | $0.27 |
DEAD-CODE | 60 | 4 | $0.17 |
RENAME | 120 | 30 | $0.54 |
SPLIT | 180 | 60 | $0.92 |
TYPES | 100 | 25 | $0.46 |
DEPS | 40 | 5 | $0.13 |
TESTS | 200 | 80 | $1.08 |
DOCS | 90 | 35 | $0.42 |
REVIEW | 70 | 12 | $0.25 |
单晚总账估算
Token 总量: 940K 输入 + 259K 输出 ≈ 1.2M tokens
Anthropic 直连价: ~$3.50（按 GPT-5.3 Codex 公开价折算）
1.07x 统一倍率: ~$3.78绑定支付方式后新账号的起步额度通常够跑通前几个任务，足够 validate 流程是不是适合你的项目。剩下 5 个任务充值 $5-10 跑完整体。
时间维度
API 调用累计约 30-50 分钟（串行）；并发跑能压到 12-20 分钟。加上你 review 每个 commit 的人工时间，完整闭环 60-90 分钟。
成本压缩的 3 个杠杆
- prompt cache：把 architecture.md 当作长 system prompt 重复 reference，命中后输入计费降到 ~10%。一晚跑下来能省 30-40%
- mini model：机械任务切 mini，前述 RENAME / DEAD-CODE / DOCS 大约能砍掉 $0.7-1.0
- 任务拆得更细：单任务的失败 retry 成本是整个任务重跑，拆到"改一个文件"粒度时，单次失败损失小
4 个让重构跑崩的瞬间
实战中容易崩的不是模型本身——是工作流细节。
1. 中间盒断流
跑了 6 分钟、Codex 改完 12 个文件，第 13 个时报 ECONNRESET。家用宽带或公司代理的 NAT 表项把长连接 idle timeout 设在 30-60 秒，AI 推理一卡就断。
修法：走 CodeGateway 网关——Cloudflare 边缘做长连接保活，10 万行级全量分析单次连接撑过 12 分钟无感。详见Claude Code 连接超时排查（思路对 Codex CLI 完全适用）。
2. 子代理"自作主张"动了不该动的文件
让 Codex 改 src/，结果它顺手把 tests/conftest.py 也改了——导致测试基础设施破坏，后面所有测试报错。
修法：开任务前明确"防火墙"。
codex "重构 src/, 但尽量不要修改以下文件：tests/conftest.py、scripts/deploy*.sh、.github/**。如果发现需要改这些，停下来报告我决定。"写进任务模板，每次任务都加一遍。多跑几次会习惯。
3. RENAME 任务把字符串字面量也改了
把变量 user_id 改成 accountId 时，把日志里的 "user_id" 字符串字面量也一起改了——结果 grep 日志的脚本全失效。
修法：明确 scope。
codex "重命名 user_id 为 accountId，但仅限于变量名 / 函数参数 / 类属性。
字符串字面量（包括日志、SQL、错误消息）不动。
JSON / YAML / 配置文件里的 'user_id' 不动。"4. TESTS 任务给假阳性测试
Codex 给一个有 bug 的函数补了"通过的"测试——它读懂了函数当前行为，把当前行为（包括 bug）变成了断言。下次有人修 bug，测试反而挂了。
修法：明确告诉 Codex"测试基于规范，不基于现有实现"。
codex "为 src/billing/calculate.py 补单元测试。规范见 docs/billing-spec.md。
不要从函数当前实现反推测试——那会把 bug 固化成断言。
如果规范不清楚，写 `# clarify-with-pm:` 注释标记，不要自己脑补。"如果连 spec 都没有，测试任务的优先级应该排到写完 spec 之后。
FAQ
Q：直连 OpenAI 也能跑 Codex CLI，为什么走 CodeGateway？
A：直连完全可以。CodeGateway 解决三个具体问题：① 长任务连接稳定性（Cloudflare 边缘保活，避免长推理过程中断流）；② 灵活付款方式（Stripe 支持 Alipay / Apple Pay 等多种支付）；③ 同一个 Key 同时调 Claude / OpenAI / Google 模型，重构和写测试可能想用不同上游。
Q：成本能不能再压？$1-3 单晚还是太多。 A：能。三条路：① prompt cache 命中（系统 prompt 重复用 → 输入降到 ~10%）；② 机械任务切 gpt-5-mini（成本降一半以上）；③ 用 spec 把任务拆细，失败 retry 不重跑整个任务。
Q：Codex 改的代码能直接 merge 吗？
A：不能。一直要 review。Codex 会写 commit，但每个 commit 都需要你看 diff。两个具体危险信号：① 改了 test 让 test 通过（而不是改 source 让 test 通过）；② 引入了魔法数字 / 硬编码而不抽象。Pre-merge checklist 写到 Skill 里配置指南有详细写法。
Q：可以在 CI 里自动跑吗？
A：能。codex --print 是非交互模式，适合 CI。但不推荐 auto-merge——CI 跑 review，人决策 merge。CI 用一个独立的 API Key（命名 ci-<repo>），设 RPM 上限和月度预算。
Q：Codex CLI 和 Claude Code 怎么选？
A：不互斥。Codex 在"按 OpenAI Responses API 协议跑"的场景（mainstream Python / TS、企业 OpenAI 已有授信）更顺手；Claude Code 在"长上下文 + 多代理编排 + skill 系统"场景更强。同一个 CodeGateway Key 两边都能用，按任务切。详细对比见已上线文章 /blog/codex-cli-vs-claude-code。
Q：祖传项目如果有商业敏感代码怎么办？
A：Codex CLI 把代码 prompt 发给上游模型——所以涉及商业秘密的部分要先脱敏 / 用 placeholder。CodeGateway 网关本身不持久化对话内容（只记 metadata），但上游 OpenAI 的数据保留策略由 OpenAI 自己定，需要看 OpenAI 的 Enterprise / Zero-Retention 服务条款。
Q：什么样的项目不建议用 Codex 跑大扫除？
A：三种：① 没有任何 git 历史的项目（撤回不了）；② 没有任何测试的关键业务代码（无法验证改动正确性）；③ 涉及合规审计、医疗、金融核心交易的代码（需要人工审查每行）。先补测试 → 再上 Codex。
Q：祖传代码跑完之后怎么防止再次"祖传化"？
A：两个动作：① 把这次重构后的规范写进项目 README + Codex .codex/policy.md，下次新人接手有标杆；② 在 CI 里加 quality gate（圈复杂度阈值、覆盖率阈值），下次有人想加 600 行函数直接被卡。
相关资料
- Codex CLI 接入教程 —— 5 步快速配置（CodeGateway 官方）
- Claude Code 连接超时排查指南 —— 长任务断流的根因与修复（思路对 Codex 通用）
- Claude Code 完整配置指南 —— Skills / Hooks / 多 Key 治理（与 Codex 工作流互补）
- 博客内容工厂 1 小时 16 张配图账本 —— 同样"金矿+铲子"思路的 dogfood 复盘
- 充值费用指南 —— 统一倍率、起步额度、Stripe / 支付宝
- 统一倍率说明 —— 统一 1.07× 倍率、不随用量变化
- OpenAI 官方文档：Codex CLI
- OpenAI 官方文档：Responses API
- 本文用到的任务拆解模板：开源在 Whitedit/code-gateway-cookbook（image-gen 配套，codex 任务模板即将加入）
祖传代码不是一晚上变成那样的，但有可能一晚上动起来。先诊断、再小步、commit 颗粒度细到能回滚——把工具流程跑顺，剩下的精力就回到"哪些是真正该改的事"上。