官方教學中文版實戰場景
讓 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 沒有被無意破壞。