让 Codex 重构代码库
当 codebase 里积累了 unused code、duplicated logic、stale abstractions、large files 或 le
当 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。