---
title: "讓 Codex 重構程式碼庫"
description: "說明如何用 Codex 小步清理工程債，包括 unused code、duplicated logic、stale abstractions 和 legacy patterns。"
verifiedAt: "2026-05-05"
---

當 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](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](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](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](https://developers.openai.com/cookbook/examples/codex/code_modernization)
- Codex skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示詞

```text
请 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 繫結起來。

## 使用方式

1. 先讓 Codex map area：noisy modules、duplicated logic、unused code、tests、public contracts、old patterns。
2. 每次只選一個 cleanup theme：remove unused code、simplify control flow、modernize pattern、split large file。
3. patch 前要求 Codex 說明 current behavior、structural improvement、smallest check。
4. 每個 pass 後 review，並執行最小有用檢查。
5. 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。
