用 Codex CLI 给祖传代码大扫除：一个晚上跑通

Q: 可以在 CI 里自动跑吗？

能。codex --print 是非交互模式，适合 CI。但不推荐 auto-merge——CI 跑 review，人决策 merge。CI 用一个独立的 API Key（命名 ci- ），设 RPM 上限和月度预算。

Q: 祖传代码跑完之后怎么防止再次"祖传化"？

两个动作：① 把这次重构后的规范写进项目 README + Codex .codex/policy.md，下次新人接手有标杆；② 在 CI 里加 quality gate（圈复杂度阈值、覆盖率阈值），下次有人想加 600 行函数直接被卡。

用 Codex CLI 给祖传代码做大扫除：一个晚上跑通的实战方法

作者：CodeGateway 团队 · 实测于 2026-05

一句话：每个工程师电脑里都有那么一个项目：3 年没动过、测试覆盖 12%、上一次维护那个人已经离职、注释里残留着 2022 年的"等以后再改"标记。每次想动它都两难——"不动它老板下一个迭代过不去 / 动它一周交不了别的活"。 Codex CLI（OpenAI 的命令行编码助手，配合 GPT-5.3 Codex 模型）让"动它"的成本压到一个晚上。本文不是"AI 万能"的鸡汤——而是把"祖传代码大扫除"这件事拆成 4 个具体阶段：诊断、接入、多代理拆任务、跑崩瞬间复盘。每一步都有可复制的命令与 spec。一个晚上跑完一个典型中型 Python 项目，成本估算 $1-3。

祖传代码的三种典型病症

跑大扫除之前，先把"祖传"具体化。绝大多数你不想动的老项目落在三种典型病症里——每种诊断方式不同，重构的优先级也不同。

病症	典型表现	危害	适合的 Codex 任务
屎山型	函数 800 行、嵌套 6 层、变量名 `tmp1` `tmp2`	改 A 出 B、回归测试盲区	拆函数、重命名、抽公共逻辑
化石型	依赖 5 年没升级、Python 3.6、jQuery 1.x	安全洞、CVE 警告、新手不会用	依赖批量升级 + API 适配
失忆型	没文档、没测试、原作者离职、注释全是"see slack"	没人敢改、知识只存在前同事大脑里	自动生成文档 + 单测覆盖

实际项目通常三种叠加——这就是为什么"看着想重写"的冲动来得那么强。但全推倒重写的项目八成会失败（行业数据：>60% 的"rewrite from scratch" 项目超期或 abandon）。Codex CLI 的玩法是在原结构上做手术，而不是推平重建。

重构前的诊断：先弄清楚要改什么

不要打开 Codex 就一句"重构这个项目"。这句指令的成本会爆掉而且效果差——AI 不知道你的优先级、不知道哪些是历史包袱哪些是必要复杂度。

诊断花 15 分钟，省后面几小时返工。三个动作：

1. 跑一遍可量化的"病症体检"

bash

# 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. 列一份"动什么不动什么"清单

bash

# 创建 refactor-scope.md，回答 4 个问题：
# 1. 哪些模块的圈复杂度 > 15？（必动）
# 2. 哪些函数 > 100 行？（拆）
# 3. 哪些依赖有 CVE 警告？（升）
# 4. 哪些代码 vulture 标了死代码？（删）

第 4 条要谨慎——动态语言里"死代码"经常其实是被反射调用的。打 # vulture: ignore 标记不删的部分。

3. 备份 + 建分支

bash

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 秒）

bash

npm install -g @openai/codex
codex --version

需要 Node.js 18+。Windows 推荐 WSL2。

Step 2：拿一把 CodeGateway API Key（约 2 分钟）

直连 OpenAI 也行。本文走 CodeGateway，原因：

邮箱注册即可，无需国际信用卡
新账号送 $2 起步额度——按 GPT-5.3 Codex 输入 $2/1M tokens × 1.5x 起步倍率折算，约 67 万 tokens，够诊断 + 一轮重构试跑
长任务比直连稳——10 万行级 codebase 全量分析跑过 8-12 分钟，断流过一次（详见后面"跑崩瞬间"那节）

Step 3：配环境变量（约 1 分钟）

bash

# ~/.zshrc 或 ~/.bashrc
export OPENAI_BASE_URL="https://api.codegateway.dev/v1"
export OPENAI_API_KEY="sk-cg-xxxxxxxxxxxxxxxxxxxxxx"

source 一下生效。

Step 4：验证连通（约 30 秒）

bash

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 秒）

bash

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 之后 → 串行）。

bash

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.5x）展开。

9 个任务的 token 消耗估算

任务	输入 token（千）	输出 token（千）	估算成本
ARCHITECTURE	80	8	$0.32
DEAD-CODE	60	4	$0.20
RENAME	120	30	$0.65
SPLIT	180	60	$1.10
TYPES	100	25	$0.55
DEPS	40	5	$0.16
TESTS	200	80	$1.30
DOCS	90	35	$0.50
REVIEW	70	12	$0.30

单晚总账估算

Token 总量:   940K 输入 + 259K 输出 ≈ 1.2M tokens
Anthropic 直连价:   ~$3.50（按 GPT-5.3 Codex 公开价折算）
1.5x 起步倍率（CodeGateway 新账号）:  ~$5.30
1.2x 老账号倍率（90 天累计 > $500）:  ~$4.20

新账号 $2 起步额度能跑通前 4-5 个任务，足够 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 也改了——导致测试基础设施破坏，后面所有测试报错。

修法：开任务前明确"防火墙"。

bash

codex "重构 src/, 但尽量不要修改以下文件：tests/conftest.py、scripts/deploy*.sh、.github/**。如果发现需要改这些，停下来报告我决定。"

写进任务模板，每次任务都加一遍。多跑几次会习惯。

3. RENAME 任务把字符串字面量也改了

把变量 user_id 改成 accountId 时，把日志里的 "user_id" 字符串字面量也一起改了——结果 grep 日志的脚本全失效。

修法：明确 scope。

bash

codex "重命名 user_id 为 accountId，但仅限于变量名 / 函数参数 / 类属性。
字符串字面量（包括日志、SQL、错误消息）不动。
JSON / YAML / 配置文件里的 'user_id' 不动。"

4. TESTS 任务给假阳性测试

Codex 给一个有 bug 的函数补了"通过的"测试——它读懂了函数当前行为，把当前行为（包括 bug）变成了断言。下次有人修 bug，测试反而挂了。

修法：明确告诉 Codex"测试基于规范，不基于现有实现"。

bash

codex "为 src/billing/calculate.py 补单元测试。规范见 docs/billing-spec.md。
不要从函数当前实现反推测试——那会把 bug 固化成断言。
如果规范不清楚，写 `# clarify-with-pm:` 注释标记，不要自己脑补。"

如果连 spec 都没有，测试任务的优先级应该排到写完 spec 之后。

FAQ

Q：直连 OpenAI 也能跑 Codex CLI，为什么走 CodeGateway？

A：直连完全可以。CodeGateway 解决三个具体问题：① 国内 / 海外网络不稳定时长任务断流（Cloudflare 边缘保活）；② 没有国际信用卡（邮箱注册 + 微信/支付宝充值）；③ 同一个 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 两边都能用，按任务切。详细对比即将上线（W4 周五发布）。

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 给祖传代码做大扫除：一个晚上跑通的实战方法

用 Codex CLI 给祖传代码做大扫除：一个晚上跑通的实战方法

目录

祖传代码的三种典型病症

重构前的诊断：先弄清楚要改什么

1. 跑一遍可量化的"病症体检"

2. 列一份"动什么不动什么"清单

3. 备份 + 建分支

Codex CLI 5 步接入

Step 1：装 CLI（约 30 秒）

Step 2：拿一把 CodeGateway API Key（约 2 分钟）

Step 3：配环境变量（约 1 分钟）

Step 4：验证连通（约 30 秒）

Step 5：第一句指令（约 30 秒）

多代理拆任务：把"重构"切成 9 件可调度的事

任务分解模板

用 sub-agent 并发跑

子代理选模型的省钱策略

一个晚上的成本估算（典型场景）

9 个任务的 token 消耗估算

单晚总账估算

时间维度

成本压缩的 3 个杠杆

4 个让重构跑崩的瞬间

1. 中间盒断流

2. 子代理"自作主张"动了不该动的文件

3. RENAME 任务把字符串字面量也改了

4. TESTS 任务给假阳性测试

FAQ

相关资料