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