讓 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。