官方教程中文版实战场景
让 Codex 执行代码迁移
说明如何用 Codex 做代码迁移：先盘点 legacy system，再按 checkpoint 验证 parity。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| 代码迁移 | code migration | 把代码迁到新框架 / 语言 / 结构。 |
| 等价验证 | parity check | 迁移前后行为要一致。 |
| 分批迁移 | phased | 小批迁、每批验证。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你把一次代码迁移拆成分批、可验证、行为等价的安全计划。
你是 Codex 代码迁移规划顾问，帮我把一次迁移拆成分批、每批可验证、行为保持等价的安全计划。
【角色】
你熟悉用 Codex 执行代码迁移，知道先盘点、分批迁、保持行为等价、每批回归验证。
【输入】
- 迁移的源和目标（框架 / 语言 / 结构）：___
- 涉及的代码范围和规模：___
- 现有测试覆盖：___
- 时间和风险约束：___
【工作流程】
1. 盘点受影响范围，找出迁移难点
2. 把迁移拆成小批，定每批边界
3. 每批迁完做等价 / 回归验证
4. 给从首批到收口的顺序
【输出规范】
▌一、范围盘点与难点
▌二、分批迁移方案
▌三、每批的等价验证
▌四、推进顺序与收口
【硬约束】
- 小批迁移、每批验证，不一次全迁
- 迁移保持行为等价，不顺手改逻辑
- 测试不足先补关键路径
- 不可逆操作人工确认、改动可回滚
- 不确定的目标特性标注需查官方文档
- 给的步骤具体可执行，不空泛代码迁移不要做成一次性大重写。Codex 适合先盘点 legacy system，再把旧概念映射到新栈，按 checkpoint 落地，每个 milestone 后都验证 parity。
官方页面：https://developers.openai.com/codex/use-cases/code-migrations
适合什么任务
| 场景 | Codex 应该做什么 |
|---|---|
| legacy stack 迁到 modern stack | 盘点旧系统假设，提出分阶段迁移计划 |
| framework、runtime、build system 或平台约定要变 | 映射旧概念到新概念，标出没有直接对应物的部分 |
| 产品迁移过程中仍要保持可用 | 使用 compatibility layer、module-by-module port、branch-by-abstraction 或 strangler-style replacement |
| 团队需要明确回滚路径 | checkpoint 之间保留 rollback 或 fallback options |
使用的能力
| 能力 | 用法 | 链接 |
|---|---|---|
$security-best-practices | 在 merge 前检查高风险迁移、依赖变更和暴露面 | https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices |
$gh-fix-ci | 每个 migration milestone 后处理失败 CI，不把清理拖到最后 | https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci |
$aspnet-core | 当迁移涉及 ASP.NET Core app models、Program.cs、middleware、testing、performance 或 version upgrades 时使用框架指导 | https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core |
相关官方说明：
- Modernizing your Codebase with Codex：https://developers.openai.com/cookbook/examples/codex/code_modernization
- Worktrees in the Codex app：https://developers.openai.com/codex/app/worktrees
起始提示词
请把这个 codebase 从 [legacy stack or system] 迁移到 [target stack or system]。
要求：
- 先盘点 legacy assumptions：routing、data models、auth、configuration、build tooling、tests、deployment 和 external contracts。
- 把旧栈概念映射到新栈，并标出没有直接对应物的部分。
- 提出渐进式迁移计划，使用 compatibility layers 或 checkpoints，不要一次性大重写。
- 除非迁移明确需要 user-visible change，否则保持行为不变。
- 按 milestones 工作；每个 milestone 后运行 lint、type-check 和 focused tests。
- 在迁移完成前，保持 rollback 或 fallback options 清晰可见。
- 如果 validation 失败，先修复再继续。
- 第一步先 mapping migration surface，并提出 checkpoint plan。这个 prompt 把 Codex 的第一步限制在 mapping 和 checkpoint plan。复杂迁移先画清楚边界，再动代码。
推荐迁移顺序
- 盘点 migration surface：legacy packages、framework conventions、routing、data access、auth、configuration、build tooling、tests、deployment assumptions，以及必须保留的 external contracts。
- 让 Codex 把 legacy concepts 映射到 target stack，并标出没有直接对应物的部分。
- 选择 incremental strategy：compatibility layer、module-by-module port、branch-by-abstraction，或围绕单一边界做 strangler-style replacement。
- 默认保持 behavior stable。迁移必须带来的 user-visible change 要单独命名。
- 每个 milestone 后跑最小但有效的验证：lint、type-check、focused tests、contract tests、smoke tests，或 legacy path 与 new path 的 side-by-side check。
- 每个 checkpoint 后 review diff 和剩余 transition risk，不要等到完整重写结束才看。
使用 ExecPlans
OpenAI 的 code modernization cookbook 介绍了 ExecPlans：一种让 Codex 保持全局视图、写清目标状态、记录每轮验证结果的文档。
复杂迁移建议每个系统部分都创建一个 ExecPlan，记录：
- 当前 legacy behavior。
- 目标 stack 的设计。
- checkpoint 顺序。
- 每个 checkpoint 的验证命令。
- 已知风险和回滚方案。
- 每轮 Codex 修改后的 validation log。
这样后续 review 的不是“Codex 改了很多文件”，而是一条可以追踪的迁移链路。
验收重点
- 行为未变，除非迁移计划明确要求。
- checkpoint 能独立 review。
- CI 或本地验证失败时先修复，再继续下一步。
- dependency 和 exposed surface 经过安全检查。
- fallback options 在 transition 完成前一直可见。
- external contracts 没有被无意破坏。