让 Codex 重构代码库
说明如何用 Codex 小步清理工程债，包括 unused code、duplicated logic、stale abstractions 和 legacy patterns。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| 代码库重构 | refactor | 不改行为、改善结构的大范围修改。 |
| 导览先行 | tour first | 先让 Codex 读懂再动手。 |
| 行为保持 | parity | 重构前后行为必须一致。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你把一次代码库重构拆成先导览、小步、可验证的安全计划。
你是 Codex 代码库重构规划顾问，帮我把一次重构拆成先导览、小步推进、每步可验证的安全计划。
【角色】
你熟悉用 Codex 重构代码库的方法：先导览读懂、小步改、保持行为不变、每步验证。
【输入】
- 要重构的范围和目标：___
- 代码库规模和技术栈：___
- 现有的测试覆盖：___
- 风险容忍度：___
【工作流程】
1. 先让 Codex 导览读懂相关模块
2. 把重构拆成小步、每步行为不变
3. 每步设计验证（测试 / 对比）
4. 给从小步到收口的推进顺序
【输出规范】
▌一、导览范围
▌二、重构的小步拆解
▌三、每步的行为保持验证
▌四、推进顺序与收口
【硬约束】
- 重构不改行为，每步验证不退化
- 小步可回滚，不一次大改
- 测试不足先补关键路径再动
- 多人协作守工作树边界
- 不确定影响范围先只读分析
- 给的每条结论都要落到具体可照做的步骤或示例，不停留在「建议」「考虑一下」这类没法直接执行的空泛表述当 codebase 里积累了 unused code、duplicated logic、stale abstractions、large files 或 legacy patterns，每次改动都会变贵。这个用例是让 Codex 在不改变行为的前提下，按小而可 review 的 passes 清理工程债，而不是把 refactor 变成 stack migration。
官方页面：https://developers.openai.com/codex/use-cases/refactor-your-codebase
适合什么任务
| 场景 | Codex 应该做什么 |
|---|---|
| codebase 有 dead code、oversized modules、duplicated logic 或 stale abstractions | 先 map messy area，再按 cleanup theme 小步落地 |
| 团队要 in-place modernization | 不做 framework/stack migration，保持 public behavior stable |
| cleanup 触及 security、auth、dependency changes | 用 $security-best-practices 做额外 review |
| 某种 modernization pattern 反复出现 | 用 $skill-creator 沉淀 reusable team skill |
使用的能力
| 能力 | 用法 | 链接 |
|---|---|---|
$security-best-practices | merge 前 review security-sensitive cleanup、dependency changes、auth flows 和 exposed surfaces | https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices |
$skill-creator | 把 proven modernization pattern、review checklist 或 parity workflow 做成 reusable repo/team skill | https://github.com/openai/skills/tree/main/skills/.system/skill-creator |
相关官方说明：
- Modernizing your Codebase with Codex：https://developers.openai.com/cookbook/examples/codex/code_modernization
- Codex skills：https://developers.openai.com/codex/skills
起始提示词
请 modernize 并 refactor 这个 codebase。
要求：
- 除非我明确要求 functional change，否则保持 behavior 不变。
- 先识别拖慢改动的 dead code、duplicated paths、oversized modules、stale abstractions 和 legacy patterns。
- 对每个 proposed pass，说明 current behavior、structural improvement，以及证明 behavior stable 的 validation check。
- 把工作拆成小而可 review 的 refactor passes，例如删除 dead code、简化 control flow、抽取 helpers，或用 repo 当前 conventions 替换 outdated patterns。
- 除非 refactor 必须改变 public APIs，否则保持 public APIs stable。
- 标出应该拆成独立 migration task 的 framework migration、dependency upgrade、API change 或 architecture move。
- 如果工作范围较宽，先提出 implementation 前应该创建的 docs、specs 和 parity checks。
请先提出计划。这个 prompt 先要求 plan，不直接改代码。宽范围 refactor 必须先把 behavior、structural improvement 和 validation check 绑定起来。
使用方式
- 先让 Codex map area：noisy modules、duplicated logic、unused code、tests、public contracts、old patterns。
- 每次只选一个 cleanup theme：remove unused code、simplify control flow、modernize pattern、split large file。
- patch 前要求 Codex 说明 current behavior、structural improvement、smallest check。
- 每个 pass 后 review，并运行最小有用检查。
- stack changes、dependency migrations、architecture moves 单独拆任务，除非它们是完成 cleanup 的必要条件。
使用 ExecPlans
OpenAI 的 code modernization cookbook 介绍了 ExecPlans：让 Codex 保持 cleanup 全局视图、写清目标状态，并记录每个 pass 的 validation。
当 refactor 跨多个 module 或多 session 时，用 ExecPlans 记录：
- 删除了什么。
- 更新了什么 pattern。
- 哪些 contracts 必须 stable。
- 哪些工作 deferred。
- 每个 pass 的 validation log。
重复模式做成 Skills
当同一 cleanup rules 会跨 repos、services 或 teams 重复，skills 更合适。
适合做成 skill 的模式：
- unused-code removal checklist。
- module extraction rules。
- legacy-pattern modernization。
- security-sensitive cleanup review。
- CI failure triage。
- parity validation workflow。
如果你已经在一个 codebase 成功做过 modernization pass，可以让 Codex 把这套 pattern 做成 reusable skill。