讓 Codex 重構程式碼庫
說明如何用 Codex 小步清理工程債，包括 unused code、duplicated logic、stale abstractions 和 legacy patterns。
當 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。