把 Codex 用到極致 ！OpenAI 官方最佳實踐完整解讀
整理版優先睇
將Codex當成可配置嘅隊友，透過AGENTS.md、Skills同Automations建立持久記憶，先係用盡佢嘅關鍵。
呢篇文章係對OpenAI官方Codex最佳實踐文檔嘅完整解讀。作者將文檔內容逐條拆解，補充咗具體操作案例。整體結論係：要將Codex由一個單純嘅代碼生成工具，變成一個可以幫你完成整個開發循環嘅系統，核心係畀佢建立對你倉庫、規範同工作習慣嘅持久記憶。
文章圍繞六個支柱展開：從正確任務上下文出發、用AGENTS.md寫入持久指引、通過配置文件統一行為、用MCP連接外部系統、把重複工作封裝成Skills、把穩定流程變成Automations。所有最佳實踐都圍繞呢幾點。官方推薦嘅prompt四要素框架（Goal、Context、Constraints、Done when）同三種規劃方式（Plan mode、讓Codex問你、PLANS.md模板）係提升效率嘅關鍵。
AGENTS.md係持久指引嘅核心，要短而準確，並隨時間根據錯誤更新。Skills同Automations嘅分工係：Skills定義方法，Automations定義節奏。Session管理要每個任務一個線程，避免上下文膨脹。最後總結八個常見錯誤同一個完整工作流。官方一句話點題：Codex唔止生成代碼，仲可以幫你測試、檢查同review。
- 核心思路：將Codex由生成代碼嘅工具轉變成完成成個開發循環嘅系統，關鍵係透過AGENTS.md、Skills同Automations建立持久記憶。
- Prompt四要素：Goal、Context、Constraints、Done when，呢個框架可以令Codex保持喺範圍內工作，減少假設，方便review。
- 複雜任務先用Plan mode或者叫Codex問你問題，確認方向先動手，避免大規模返工；官方推薦三步驟：先理解、再規劃、後實現。
- AGENTS.md係持久指引嘅核心，要短而準確，並透過重複錯誤嘅覆盤持續更新；離當前目錄越近嘅AGENTS.md優先級越高。
- 穩定嘅工作流先封裝成Skill，再設置Automations自動執行；但一定要先手動驗證可靠，避免將不穩定行為規模化。
核心思路：將Codex當作可配置嘅隊友
呢篇文章係對OpenAI官方Codex最佳實踐文檔嘅完整解讀，作者將文檔逐條拆解，補充具體案例。整體結論係：要將Codex由生成代碼嘅工具變成完成成個開發循環嘅系統。
- 從正確嘅任務上下文出發：prompt要包含Goal、Context、Constraints、Done when。
- 用AGENTS.md寫入持久指引：呢度係你哋團隊嘅工程協議。
- 通過配置文件統一行為：config.toml分個人、倉庫同命令行三層。
- 用MCP連接外部系統：例如數據庫、API，擴展Codex能力。
- 把重複工作封裝成Skills：每個Skill聚焦一件事。
- 把穩定流程變成Automations：定義節奏，自動執行。
Prompt四要素同規劃方式
官方推薦嘅prompt四要素框架係令Codex保持範圍嘅關鍵：Goal（你想改咩）、Context（相關文件同資訊）、Constraints（規範同約束）、Done when</highlight-inline>（完成條件）。呢個框架可以減少Codex嘅假設，令你嘅review更輕鬆。
複雜任務一定要先規劃再動手。官方提供三種規劃方式，好多人淨係識第一種。
- 1 Plan mode：最常用，用 `/plan` 或者 Shift + Tab 切換，等Codex先收集上下文、問清問題、建立計劃，然後先寫代碼。
- 2 讓Codex問你：如果你方向模糊，可以直接同Codex講「先問我幾個問題」，等佢幫你釐清需求，好似產品討論夥伴。
- 3 PLANS.md模板：喺倉庫維護一個執行計劃模板，等Codex處理長期任務時跟住做，適合跨模塊重構。
AGENTS.md同配置文件：建立持久指引
AGENTS.md係agent嘅README，會自動載入到上下文，係編碼你同團隊想Codex點樣工作嘅最佳位置。官方提醒：短而準確嘅AGENTS.md比長而模糊更有用。
AGENTS.md有三個層級：全局（~/.codex/）、倉庫根目錄、子目錄。離當前工作目錄越近嘅文件優先級越高。你可以用 `/init` 快速生成初始版本，但一定要根據實際情況修改。
配置文件方面，官方推薦分層模式：~/.codex/config.toml（個人默認）、.codex/config.toml</highlight-inline>（倉庫專屬）、命令行參數（一次性調整）。呢度可以定義MCP服務器、profiles、multi-agent設置等。
Skills同Automations：封裝可複用方法
一旦工作流變得可重複，就用Skill封裝，唔好再依賴長prompt。官方建議：每個Skill聚焦一件事，從2-3個使用案例出發，定義清晰輸入輸出。
Skills嘅存儲位置：個人Skills放 `$HOME/.agents/skills`，團隊共享Skills放倉庫嘅 `.agents/skills` 目錄（可以提交git）。典型候選包括：日誌分類分析、發版說明生成、PR review checklist、標準調試流程等。
官方特別提醒：唔好將唔穩定嘅工作流自動化，否則自動化會將不穩定行為規模化，反而更難處理。一定要先手動驗證可靠。
八個常見錯誤同完整工作流
- 錯誤一：將持久規則堆喺prompt，正確做法係寫入AGENTS.md。
- 錯誤二：唔話畀Codex點運行同測試，令佢喺黑盒工作。
- 錯誤三：複雜任務跳過規劃，直接開工。
- 錯誤四：一開始就畀Codex完整電腦權限，應該從收緊開始。
- 錯誤五：唔用worktree，多個線程同時改同一批文件導致衝突。
- 錯誤六：未手動驗證可靠就將工作流自動化。
- 錯誤七：好似盯住初級員工咁盯實Codex，唔敢放手。
- 錯誤八：每個項目得一個線程，導致上下文膨脹。
一個完整嘅工作流：初始化階段用 `/init` 生成AGENTS.md、修改佢、配置config.toml、接入MCP；日常每個任務開一個線程，用四要素寫prompt，複雜任務先用Plan mode，啟動後去做其他嘢；持續改進就係更新AGENTS.md、封裝Skill、設置Automations。
OpenAI 嘅開發者文檔發佈咗一篇 Best Practices 嘅文章。
呢篇文檔描寫嘅 Codex 用法，同大多數人實際用緊嘅方式，差距相當大，呢篇文章將官方文檔嘅所有內容逐條拆解，補充具體操作案例。
六大支柱
其實成篇最佳實踐嘅核心思路就係要將 Codex 當成可配置嘅隊友，畀佢建立對你嘅倉庫、你嘅規範、你嘅工作習慣嘅持久記憶。
官方畀出嘅六個支柱：
- • 從正確嘅任務上下文出發
- • 用
AGENTS.md寫入持久指引 - • 通過配置文件統一行為
- • 用 MCP 連接外部系統
- • 將重複工作封裝成 Skills
- • 將穩定流程變成 Automations
後面嘅所有最佳實踐都圍繞呢幾點嚟展開。
Prompt 要包含四個要素
「Codex is already strong enough to be useful even when your prompt isn't perfect.」
喺大型倉庫或者高風險任務裏面工作，清晰嘅 prompt 可以令結果更穩定、更加容易 review。
官方推薦嘅 prompt 四要素框架：
- • Goal：你想改啲乜、想做啲乜
- • Context：邊啲文件、目錄、文檔、報錯信息同呢個任務相關（可以直接 @ 文件）
- • Constraints：Codex 需要遵守邊啲規範、架構約定、安全要求
- • Done when：要滿足咩條件先算完成（測試通過、行為符合預期、bug 唔再復現）
呢四個要素幫助 Codex 保持喺範圍內工作，減少假設，令你嘅 review 更輕鬆。
差嘅寫法同好嘅寫法對比
差：
「幫我優化一下 checkout 流程」
好：
Goal：減少
src/checkout/裏面重複嘅支付校驗邏輯Context：相關文件喺
src/checkout/和src/orders/validation.ts，後者有現成嘅 helper 可以參考Constraints：唔改變公開 API 嘅響應格式，唔引入新嘅依賴
Done when：跑完
pnpm test --filter checkout全部通過，diff 只涉及src/checkout/目錄，最終回覆列出改動文件同剩餘風險
關於推理級別嘅選擇
官方文檔明確咁講，唔同任務適合唔同嘅推理強度：
- • Low：快速、範圍明確嘅任務
- • Medium / High：複雜改動或者調試問題
- • Extra High：長時間運行嘅 agentic 任務、需要深度推理嘅場景
唔係所有任務都需要最高推理級別，會明顯影響速度和成本，我個人推薦使用 Medium，兼具速度和性價比：點樣拯救你，我嘅 Codex 額度！
一個冷門技巧
喺 Codex App 裏面可以用語音輸入代替打字嚟描述任務。呢個喺需要描述複雜上下文嘅時候比打字快好多。
複雜任務，先規劃再動手
呢個係官方文檔裏面我認為最值得深挖嘅部分之一，官方提供咗三種規劃方式，好多人淨係知道第一種。
方式一：Plan mode（最常用）
Plan mode 係最簡單、最有效嘅選項。佢令 Codex 先收集上下文、問清楚問題、建立更完整嘅計劃，然後先開始寫代碼。
切換方式：CLI 裏面用 /plan，或者按 Shift + Tab。
方式二：等 Codex 嚟問你
如果你個腦入面有個大概方向，但係唔肯定點樣清晰咁描述，可以直接對 Codex 講：
「我想做 X，但仲未諗清楚。先問我幾個問題，挑戰一下我嘅假設，幫我將呢個模糊嘅想法變成可以寫代碼嘅具體需求，然後再動手。」
呢種方式喺需求探索階段特別有用。相當於將 Codex 臨時變成一個產品討論夥伴，而唔係直接執行者。
方式三：PLANS.md 模板
更高級嘅工作流，喺倉庫裏面維護一個 PLANS.md 或者執行計劃模板，設定 Codex 喺處理長期任務或者多步驟工作嘅時候按照呢個模板執行。
一個典型案例：跨模塊重構
錯誤方式：直接同 Codex 講「重構一下用戶權限系統」，結果佢改咗一堆文件，你發現方向完全唔啱，全部回退。
正確方式：
第一條 prompt：
「先讀一下
src/auth/和src/permissions/嘅結構，唔好改任何文件。解釋一下當前嘅權限檢查流程係點樣行嘅，列出如果我將角色檢查統一到 middleware 層，需要改動邊啲文件，然後畀一個最小化嘅實現方案。」
等佢回覆，你 review 方案，確認方向，再發第二條：
「按照上面確認嘅方案實現。保持現有 API 接口唔變。改完之後跑權限相關嘅測試，將冇覆蓋到嘅測試盲區都列出來。」
兩步行比一步行多用兩分鐘，但係慳返可能幾個鐘嘅返工。
AGENTS.md，持久指引嘅核心
一旦某個 prompt 模式有效咗，下一步就係唔好每次都重複佢，將佢寫入 AGENTS.md。
AGENTS.md 係 agent 嘅 README。佢會自動加載到上下文裏面，係編碼你同團隊想要 Codex 點樣喺倉庫裏面工作嘅最佳位置。
一個好嘅 AGENTS.md 覆蓋嘅內容
官方列出咗幾個核心類別：
- • 倉庫結構同重要目錄
- • 點樣運行呢個項目
- • 構建、測試、lint 命令
- • 工程規範同 PR 要求
- • 約束同「唔可以做」嘅邊界
- • 驗收標準同驗證方式
三個層級，優先級由高到低
- •
~/.codex/裏面嘅全局AGENTS.md：個人默認值 - • 倉庫根目錄嘅
AGENTS.md：團隊共享標準 - • 子目錄裏面嘅
AGENTS.md：局部規則，優先級最高
離當前工作目錄越近嘅文件，優先級越高，你可以俾前端目錄同後端目錄各自寫一套唔同嘅規範。
快速起點
喺 CLI 裏面跑 /init，會自動喺當前目錄生成一個 AGENTS.md 嘅初始版本。但官方提醒：呢個只係起點，要根據你團隊實際嘅構建、測試、review、發佈方式嚟修改佢。
點樣令 AGENTS.md 保持實用
官方畀咗一條非常好嘅原則：短而準確嘅 AGENTS.md，比起長而模糊嘅更加有用。先寫基礎部分，只有當你發現重複錯誤之後先增加新規則。
如果文件開始變得太長，主文件保持精簡，將具體任務嘅指導（例如 code review 規範、架構說明）抽成獨立嘅 markdown 文件，喺 AGENTS.md 裏面引用。
令 AGENTS.md 隨時間進化嘅方法
當 Codex 對同一個問題犯咗兩次錯，叫佢做一個覆盤，然後將糾正嘅規則更新入 AGENTS.md。
例如 Codex 兩次喺 TypeScript 文件裏面引入咗 any 類型：
修復：不要使用 `any` 類型，用 `unknown` 加類型守衞替代將呢條加落 AGENTS.md，呢個問題就唔會再出現。AGENTS.md 係你同 Codex 之間不斷積累嘅「工程協議」。
配置文件，令行為跨會話保持一致
配置係令 Codex 行為喺唔同會話同唔同入口之間保持一致嘅核心手段。
可以配置嘅內容包括：模型選擇、推理強度、沙箱模式、審批策略、profiles、MCP 設置等。
配置分層
官方推薦嘅模式：
- •
~/.codex/config.toml：個人默認值（從 Codex App 嘅 Settings → Configuration 打開） - •
.codex/config.toml：倉庫專屬配置 - • 命令行參數：淨係用於一次性嘅臨時調整（如果係用 CLI 嘅話）
config.toml 係定義持久偏好嘅地方：MCP 服務器、profiles、multi-agent 設置、實驗性功能等。可以手動編輯，亦可以直接等 Codex 幫你更新。
測試同 Review，唔好淨係睇最終回覆
唔好滿足於等 Codex 做出改動，要等佢喺必要時寫測試、運行相關檢查、確認結果、喺你接受之前 review 工作。
但 Codex 只有知道「好」係點樣嘅，先可以自己做呢個循環。呢個信息要嚟自 prompt，要嚟自 AGENTS.md。
等 Codex 完成完整循環嘅內容
- • 為改動編寫或更新測試
- • 運行對應嘅測試套件
- • 檢查 lint、格式、類型
- • 確認最終行為符合請求
- • Review diff，揾 bug、迴歸、有風險嘅 pattern
Codex App 嘅 diff 面板
Codex App 有專門嘅 diff 面板，可以直接喺本地 review 改動。㩒嚇 diff 裏面嘅某一行，可以直接畀出反饋，呢個反饋會作為上下文傳畀 Codex 嘅下一輪。呢個係一個比起喺聊天框裏面打字反饋更加高效嘅方式。
/review 命令
/review slash command，呢個比好多人知道嘅要全面：
- • 同 base branch 對比，做 PR 風格嘅 review
- • Review 未提交嘅改動
- • Review 某個特定 commit
- • 使用自定義嘅 review 指令
如果你同團隊維護咗一個 code_review.md 文件，喺 AGENTS.md 裏面引用佢，Codex 喺 review 嘅時候就會遵循呢套規範。
Skills，將可複用嘅方法封裝起來
一旦某個工作流變得可重複，就唔好再依賴長 prompt 或者反覆來回，用 Skill 嚟封裝指令。
Skill 嘅核心係一個 SKILL.md 文件，加上上下文同支援 Codex 穩定執行嘅輔助邏輯。Skills 喺 CLI、IDE 插件同 Codex App 裏面都可以用。
點樣設計一個好嘅 Skill
官方嘅建議：
- • 每個 Skill 聚焦一件事
- • 從 2-3 個具體嘅使用案例出發
- • 定義清晰嘅輸入同輸出
- • Description 要講清楚呢個 Skill 做啲乜、幾時用，包括用戶會講嘅觸發詞
- • 唔好一開始就覆蓋所有邊界情況
一個實用嘅經驗法則：如果你反覆咁用同一個 prompt，或者反覆咁糾正同一個工作流，咁佢就應該變成一個 Skill。
典型嘅 Skill 候選
- • 日誌分類分析
- • 發版說明自動生成
- • 按 checklist 做 PR review
- • 遷移方案規劃
- • 遙測數據或故障摘要整理
- • 標準調試流程
點樣創建 Skill
推薦用 $skill-creator Skill 嚟生成第一版框架，用 $skill-installer Skill 嚟安裝到本地。
Skills 嘅存儲位置
- • 個人 Skills：
$HOME/.agents/skills - • 團隊共享 Skills：倉庫裏面嘅
.agents/skills目錄（可以提交入 git）
團隊共享 Skills 對新成員 onboarding 好有幫助，clone 倉庫就可以用團隊積累嘅所有 Skills。
Automations，令穩定嘅工作流自動跑
一旦工作流變得穩定，就可以等 Codex 喺後台自動幫你跑佢。
喺 Codex App 嘅 Automations 標籤裏面，
可以設定揀邊個項目、用咩 prompt（可以調用 Skills）、跑嘅頻率、喺專用 git worktree 定係本地環境裏面運行。
適合自動化嘅任務
- • 總結最近嘅 commit
- • 掃描可能嘅 bug
- • 起草發版說明
- • 檢查 CI 失敗
- • 生成每日站會摘要
- • 按計劃跑重複性分析
Automations 唔止係用嚟執行嘅，亦可以用嚟反思同維護。等 Codex 定期 review 最近嘅 session、總結重複出現嘅摩擦點、更新 prompt 或者工作流配置。
Skills 同 Automations 嘅分工
Skills 定義方法，Automations 定義節奏。如果一個工作流仲需要大量人工幹預，先將佢做成穩定嘅 Skill，穩定之後再自動化。
Session 管理，唔好等一個線程做曬所有嘢
呢部分係官方文檔裏面好多人冇留意到嘅內容，但對日常使用影響好大。
Codex 嘅 session 唔止係聊天記錄，而係包含咗上下文、決策過程同操作歷史嘅工作線程。點樣管理佢，直接影響輸出質量。
Codex App 裏面嘅管理方式
App 裏面可以置頂線程，亦可以創建 worktree。
CLI 裏面嘅關鍵 slash 命令
官方文檔列出咗呢啲：
- •
/experimental：開關實驗性功能，同時寫入config.toml - •
/resume：恢復一個保存過嘅會話 - •
/fork：基於當前線程創建新線程，同時保留原始記錄 - •
/compact：當線程變得好長嘅時候，生成一個摘要版本嘅上下文（Codex 亦會自動 compact） - •
/agent：喺並行運行多個 agent 嘅時候，切換當前活躍嘅 agent 線程 - •
/theme：選擇語法高亮主題 - •
/apps：直接喺 Codex 裏面使用 ChatGPT apps - •
/status：查看當前會話狀態
關於 /fork 嘅使用時機
如果工作仲屬於同一個問題，留喺同一個線程裏面通常比新開一個好，因為佢保留咗推理上下文。只有當工作真正分叉成兩個方向嘅時候，先用 /fork。
Worktree 同並行工作
Codex 嘅 multi-agent 工作流可以令你將一啲有邊界嘅工作從主線程裏面分離出去。
主 agent 專注核心問題，子 agent 負責探索、寫測試、分類問題等。
並行工作有效嘅前提係：寫入範圍唔衝突。
好嘅並行拆分：
- • 後端改動 + 文檔更新
- • 一個 agent 寫測試，另一個查根本原因
- • 多個 agent 分別提出備選方案
- • 一個 agent 實現，另一個淨係做 review
唔好嘅並行拆分：
- • 多個 agent 重構同一批文件
- • 需求仲未確認就跑多個實現
- • schema 同調用方同時改動但冇協調
每個任務一個線程，而唔係每個項目一個線程。 將一個項目嘅所有工作都放喺一個線程裏面，會導致上下文膨脹，輸出質量隨時間下降。
八個官方明確點名嘅錯誤用法
官方文檔喺最後總結咗一組常見錯誤。
錯誤一：將持久規則堆喺 prompt 裏面
每次 prompt 都將項目規範、代碼風格、約束條件重新描述一次，而唔係將佢哋寫入 AGENTS.md 或者 Skill。
結果：上下文浪費，而且一旦唔記得寫就失效。
正確做法：持久規則放入 AGENTS.md，一次寫入，永久生效。
錯誤二：唔話畀 Codex 知點樣運行同測試代碼
畀 Codex 一個任務，但冇話畀佢知構建同測試命令係咩，等於等佢喺黑盒裏面工作。
結果：Codex 估唔出驗證方式，淨係靠「寫完覺得冇問題」嚟判斷完成。
正確做法：AGENTS.md 裏面寫清楚驗證命令，每個任務嘅 Done when 裏面都要有具體嘅檢查步驟。
錯誤三：複雜任務 skip 咗規劃
直接等 Codex 開工，冇先等佢理解系統、提出方案。
結果：佢套用咗一個「睇落合理」嘅方案，但唔適應你實際嘅代碼結構。
正確做法：複雜任務先用 Plan mode 或者要求 Codex 先解釋再實現。
錯誤四：未搞清楚工作流就畀咗完整權限
一開始就畀 Codex 對電腦嘅完整訪問權限，覺得權限越大越好用。
結果：可能出現意外嘅全局改動，或者影響到唔應該影響嘅文件。
正確做法：從默認嘅收緊權限開始，理解咗工作流之後再針對咁放寬。
錯誤五：唔用 worktree 喺同一批文件上同時跑多個線程
多個 Codex 會話同時修改同一批文件，冇隔離。
結果：改動衝突，搞唔清楚邊個版本係啱嘅。
正確做法：用 git worktree 隔離並行工作，每個線程喺獨立嘅 worktree 裏面操作。
錯誤六：未手動驗證可靠就將工作流自動化
急住將一個唔穩定嘅工作流變成 Automation。
結果：自動化將唔穩定嘅行為規模化咗，反而比手動更難處理。
正確做法：先將工作流做成穩定嘅 Skill，跑幾次驗證佢係可靠嘅，再設定自動化。
錯誤七：好似睇住初級員工咁睇住 Codex
每一步都喺旁邊睇住，唔敢等佢跑完先檢查結果。
結果：Codex 嘅異步同並行優勢完全發揮唔到，效率同直接自己寫差唔多。
正確做法：啟動任務之後去做自己嘅工作，返嚟 review 結果。將 Codex 當成後台任務，唔係實時對話。
錯誤八：每個項目一個線程
喺一個線程裏面積累整個項目嘅所有工作記錄。
結果：上下文越來越膨脹，Codex 越來越難從噪音裏面揾到相關信息，輸出質量隨時間劣化。
正確做法：每個任務或者每個獨立工作單元開一個新線程。用 /fork 喺保留上下文嘅情況下創建分支線程。
一個完整嘅工作流
將官方文檔嘅所有建議串埋一齊，一個成熟嘅 Codex 工作流大概係咁樣：
初始化階段（一次性）
- 1. 喺倉庫裏面跑
/init生成 AGENTS.md 初始版本 - 2. 修改 AGENTS.md 寫入實際嘅構建命令、驗證命令、約束同 pattern
- 3. 喺
~/.codex/config.toml裏面配置個人默認值 - 4. 接入高價值嘅 MCP 服務器（一兩個就夠）
日常任務流程
- 1. 每個任務開一個獨立線程
- 2. 按四要素框架寫 prompt（Goal + Context + Constraints + Done when）
- 3. 複雜任務先用 Plan mode 或者等 Codex 先問你
- 4. 啟動之後去做自己嘅其他工作
- 5. 返嚟檢查結果，用 diff 面板 review
- 6. 發現穩定嘅 pattern 就封裝成 Skill
持續改進
- 1. Codex 犯咗同一個錯誤兩次，更新 AGENTS.md
- 2. Skill 穩定咗，設定 Automation
- 3. 定期等 Codex 回顧最近嘅 session，更新配置同 AGENTS.md
最後講一句
官方文檔裏面有一句話我覺得好準：
「Codex shouldn't just generate code. With the right instructions, it can also help test it, check it, and review it.」
將呢個理解食透，Codex 就從一個寫代碼嘅工具變成咗一個完成整個開發循環嘅系統。
OpenAI 的開發者文檔發佈一篇 Best Practices 的文章。
這篇文檔描述的 Codex 用法，和大多數人實際在用的方式，差距相當大，本文把官方文檔的所有內容逐條拆解，補充具體操作案例。
六個支柱
其實整篇最佳實踐的核心思路就是要把Codex當可配置的隊友，給它建立對你的倉庫、你的規範、你的工作習慣的持久記憶。
官方給出的六個支柱：
- • 從正確的任務上下文出發
- • 用
AGENTS.md寫入持久指引 - • 通過配置文件統一行為
- • 用 MCP 連接外部系統
- • 把重複工作封裝成 Skills
- • 把穩定流程變成 Automations
後面的所有最佳實踐都圍繞這幾點來展開。
Prompt 要包含四個要素
"Codex is already strong enough to be useful even when your prompt isn't perfect."
在大型倉庫或者高風險任務裏工作，清晰的 prompt 能讓結果更穩定、更容易 review。
官方推薦的 prompt 四要素框架：
- • Goal：你想改什麼、想做什麼
- • Context：哪些文件、目錄、文檔、報錯信息和這個任務相關（可以直接 @ 文件）
- • Constraints：Codex 需要遵守哪些規範、架構約定、安全要求
- • Done when：什麼條件滿足了才算完成（測試通過、行為符合預期、bug 不再復現）
這四個要素幫助 Codex 保持在範圍內工作，減少假設，讓你的 review 更輕鬆。
差的寫法和好的寫法對比
差：
"幫我優化一下 checkout 流程"
好：
Goal：減少
src/checkout/裏重複的支付校驗邏輯Context：相關文件在
src/checkout/和src/orders/validation.ts，後者有現成的 helper 可以參考Constraints：不改變公開 API 的響應格式，不引入新的依賴
Done when：跑完
pnpm test --filter checkout全部通過，diff 只涉及src/checkout/目錄，最終回覆列出改動文件和剩餘風險
關於推理級別的選擇
官方文檔明確說，不同任務適合不同的推理強度：
- • Low：快速、範圍明確的任務
- • Medium / High：複雜改動或者調試問題
- • Extra High：長時間運行的 agentic 任務、需要深度推理的場景
不是所有任務都需要最高推理級別，會明顯影響速度和成本，我個人推薦使用Medium，兼具速度和性價比：拿什麼拯救你，我的 Codex 額度！
一個冷門技巧
在 Codex App 裏可以用語音輸入代替打字來描述任務。這在需要描述複雜上下文的時候比打字快很多。
複雜任務，先規劃再動手
這是官方文檔裏我認為最值得深挖的部分之一，官方提供了三種規劃方式，很多人只知道第一種。
方式一：Plan mode（最常用）
Plan mode 是最簡單、最有效的選項。它讓 Codex 先收集上下文、問清楚問題、建立更完整的計劃，然後再開始寫代碼。
切換方式：CLI 裏用 /plan，或者按 Shift + Tab。
方式二：讓 Codex 來問你
如果你腦子裏有個大概的方向，但不確定怎麼清晰地描述，可以直接對 Codex 說：
"我想做 X，但還沒想清楚。先問我幾個問題，挑戰一下我的假設，幫我把這個模糊的想法變成可以寫代碼的具體需求，然後再動手。"
這種方式在需求探索階段特別有用。相當於把 Codex 臨時變成一個產品討論夥伴，而不是直接執行者。
方式三：PLANS.md 模板
更高級的工作流，在倉庫裏維護一個 PLANS.md 或者執行計劃模板，配置 Codex 在處理長期任務或多步驟工作時按照這個模板執行。
一個典型案例：跨模塊重構
錯誤方式：直接告訴 Codex "重構一下用戶權限系統"，結果它改了一堆文件，你發現方向完全不對，全部回退。
正確方式：
第一條 prompt：
"先讀一下
src/auth/和src/permissions/的結構，不要改任何文件。解釋一下當前的權限檢查流程是怎麼走的，列出如果我要把角色檢查統一到 middleware 層，需要改動哪些文件，然後給一個最小化的實現方案。"
等它回覆，你 review 方案，確認方向，再發第二條：
"按照上面確認的方案實現。保持現有 API 接口不變。改完之後跑權限相關的測試，把沒有覆蓋到的測試盲區也列出來。"
兩步走比一步走多花兩分鐘，但省掉了可能幾小時的返工。
AGENTS.md，持久指引的核心
一旦某個 prompt 模式有效了，下一步就是不要每次重複它，把它寫進 AGENTS.md。
AGENTS.md 是 agent 的 README。它會自動加載到上下文裏，是編碼你和團隊想要 Codex 如何在倉庫裏工作的最佳位置。
一個好的 AGENTS.md 覆蓋的內容
官方列出了幾個核心類別：
- • 倉庫結構和重要目錄
- • 如何運行這個項目
- • 構建、測試、lint 命令
- • 工程規範和 PR 要求
- • 約束和"不能做"的邊界
- • 驗收標準和驗證方式
三個層級，優先級從高到低
- •
~/.codex/裏的全局AGENTS.md：個人默認值 - • 倉庫根目錄的
AGENTS.md：團隊共享標準 - • 子目錄裏的
AGENTS.md：局部規則，優先級最高
離當前工作目錄越近的文件，優先級越高，你可以給前端目錄和後端目錄各寫一套不同的規範。
快速起點
在 CLI 裏跑 /init，會自動在當前目錄生成一個 AGENTS.md 的初始版本。但官方提醒：這只是起點，要根據你團隊實際的構建、測試、review、發佈方式來修改它。
怎麼讓 AGENTS.md 保持實用
官方給了一條非常好的原則：短而準確的 AGENTS.md，比長而模糊的更有用。先寫基礎部分，只有在你發現重複錯誤之後再增加新規則。
如果文件開始變得太長，主文件保持精簡，把具體任務的指導（比如 code review 規範、架構說明）抽成獨立的 markdown 文件，在 AGENTS.md 裏引用。
讓 AGENTS.md 隨時間進化的方法
當 Codex 對同一個問題犯了兩次錯，讓它做一個覆盤，然後把糾正的規則更新進 AGENTS.md。
比如 Codex 兩次在 TypeScript 文件裏引入了 any 類型：
修復：不要使用 `any` 類型，用 `unknown` 加類型守衞替代把這條加進 AGENTS.md，這個問題就不會再出現了。AGENTS.md 是你和 Codex 之間不斷積累的"工程協議"。
配置文件，讓行為跨會話保持一致
配置是讓 Codex 行為在不同會話和不同入口之間保持一致的核心手段。
可以配置的內容包括：模型選擇、推理強度、沙箱模式、審批策略、profiles、MCP 設置等。
配置分層
官方推薦的模式：
- •
~/.codex/config.toml：個人默認值（從 Codex App 的 Settings → Configuration 打開） - •
.codex/config.toml：倉庫專屬配置 - • 命令行參數：只用於一次性的臨時調整（如果用 CLI 的話）
config.toml 是定義持久偏好的地方：MCP 服務器、profiles、multi-agent 設置、實驗性功能等。可以手動編輯，也可以直接讓 Codex 幫你更新。
測試和 Review，不要只看最終回覆
不要滿足於讓 Codex 做出改動，要讓它在必要時寫測試、運行相關檢查、確認結果、在你接受之前 review 工作。
但 Codex 只有知道"好"是什麼樣的，才能自己做這個循環。這個信息要麼來自 prompt，要麼來自 AGENTS.md。
讓 Codex 完成完整循環的內容
- • 為改動編寫或更新測試
- • 運行對應的測試套件
- • 檢查 lint、格式、類型
- • 確認最終行為符合請求
- • Review diff，找 bug、迴歸、有風險的 pattern
Codex App 的 diff 面板
Codex App 有專門的 diff 面板，可以直接在本地 review 改動。點擊 diff 裏的某一行，可以直接給出反饋，這個反饋會作為上下文傳給 Codex 的下一輪。這是一個比在聊天框裏打字反饋更高效的方式。
/review 命令
/review slash command，這個比很多人知道的要全：
- • 和 base branch 對比，做 PR 風格的 review
- • Review 未提交的改動
- • Review 某個特定 commit
- • 使用自定義的 review 指令
如果你和團隊維護了一個 code_review.md 文件，在 AGENTS.md 裏引用它，Codex 在 review 的時候就會遵循這套規範。
Skills，把可複用的方法封裝起來
一旦某個工作流變得可重複，就不要再依賴長 prompt 或者反覆來回了，用 Skill 來封裝指令。
Skill 的核心是一個 SKILL.md 文件，加上上下文和支持 Codex 穩定執行的輔助邏輯。Skills 在 CLI、IDE 插件和 Codex App 裏都可以用。
怎麼設計一個好的 Skill
官方的建議：
- • 每個 Skill 聚焦一件事
- • 從 2-3 個具體的使用案例出發
- • 定義清晰的輸入和輸出
- • Description 要說清楚這個 Skill 做什麼、什麼時候用，包括用戶會說的觸發詞
- • 不要一開始就覆蓋所有邊界情況
一個實用的經驗法則：如果你反覆在用同一個 prompt，或者反覆在糾正同一個工作流，那它就應該變成一個 Skill。
典型的 Skill 候選
- • 日誌分類分析
- • 發版說明自動生成
- • 按 checklist 做 PR review
- • 遷移方案規劃
- • 遙測數據或故障摘要整理
- • 標準調試流程
如何創建 Skill
推薦用 $skill-creator Skill 來生成第一版框架，用 $skill-installer Skill 來安裝到本地。
Skills 的存儲位置
- • 個人 Skills：
$HOME/.agents/skills - • 團隊共享 Skills：倉庫裏的
.agents/skills目錄（可以提交進 git）
團隊共享 Skills 對新成員 onboarding 很有幫助，clone 倉庫就可以用團隊積累的所有 Skills。
Automations，讓穩定的工作流自動跑
一旦工作流變得穩定，就可以讓 Codex 在後台自動幫你跑它。
在 Codex App 的 Automations 標籤裏，
可以配置選擇哪個項目、用什麼 prompt（可以調用 Skills）、跑的頻率、在專用 git worktree 還是本地環境裏運行。
適合自動化的任務
- • 總結最近的 commit
- • 掃描可能的 bug
- • 起草發版說明
- • 檢查 CI 失敗
- • 生成每日站會摘要
- • 按計劃跑重複性分析
Automations 不只是用來執行的，也可以用來反思和維護。讓 Codex 定期 review 最近的 session、總結重複出現的摩擦點、更新 prompt 或者工作流配置。
Skills 和 Automations 的分工
Skills 定義方法，Automations 定義節奏。如果一個工作流還需要大量人工干預，先把它做成穩定的 Skill，穩定之後再自動化。
Session 管理，別讓一個線程幹所有事
這部分是官方文檔裏很多人沒注意到的內容，但對日常使用影響很大。
Codex 的 session 不只是聊天記錄，而是包含了上下文、決策過程和操作歷史的工作線程。怎麼管理它，直接影響輸出質量。
Codex App 裏的管理方式
App 裏可以置頂線程，也可以創建 worktree。
CLI 裏的關鍵 slash 命令
官方文檔列出了這些：
- •
/experimental：開關實驗性功能，同時寫入config.toml - •
/resume：恢復一個保存過的會話 - •
/fork：基於當前線程創建新線程，同時保留原始記錄 - •
/compact：當線程變得很長時，生成一個摘要版本的上下文（Codex 也會自動 compact） - •
/agent：在並行運行多個 agent 時，切換當前活躍的 agent 線程 - •
/theme：選擇語法高亮主題 - •
/apps：直接在 Codex 裏使用 ChatGPT apps - •
/status：查看當前會話狀態
關於 /fork 的使用時機
如果工作還屬於同一個問題，留在同一個線程裏通常比新開一個好，因為它保留了推理上下文。只有當工作真正分叉成兩個方向的時候，再用 /fork。
Worktree 和並行工作
Codex 的 multi-agent 工作流可以讓你把一些有邊界的工作從主線程裏分離出去。
主 agent 專注核心問題，子 agent 負責探索、寫測試、分類問題等。
並行工作有效的前提是：寫入範圍不衝突。
好的並行拆分：
- • 後端改動 + 文檔更新
- • 一個 agent 寫測試，另一個查根本原因
- • 多個 agent 分別提出備選方案
- • 一個 agent 實現，另一個只做 review
不好的並行拆分：
- • 多個 agent 重構同一批文件
- • 需求還沒確認就跑多個實現
- • schema 和調用方同時改動但沒有協調
每個任務一個線程，而不是每個項目一個線程。 把一個項目的所有工作都放在一個線程裏，會導致上下文膨脹，輸出質量隨時間下降。
八個官方明確點名的錯誤用法
官方文檔在最後總結了一組常見錯誤。
錯誤一：把持久規則堆在 prompt 裏
每次 prompt 都把項目規範、代碼風格、約束條件重新描述一遍，而不是把它們寫進 AGENTS.md 或者 Skill。
結果：上下文浪費，而且一旦忘了寫就失效。
正確做法：持久規則進 AGENTS.md，一次寫入，永久生效。
錯誤二：不告訴 Codex 怎麼運行和測試代碼
給 Codex 一個任務，但沒有告訴它構建和測試命令是什麼，等於讓它在黑盒裏工作。
結果：Codex 猜不出驗證方式，只能靠"寫完了感覺對了"來判斷完成。
正確做法：AGENTS.md 裏寫清楚驗證命令，每個任務的 Done when 裏也要有具體的檢查步驟。
錯誤三：複雜任務跳過規劃
直接讓 Codex 開工，沒有先讓它理解系統、提出方案。
結果：它套用了一個"看起來合理"的方案，但不適配你實際的代碼結構。
正確做法：複雜任務先用 Plan mode 或者要求 Codex 先解釋再實現。
錯誤四：沒弄清楚工作流就給了完整權限
一開始就給 Codex 對電腦的完整訪問權限，覺得權限越大越好用。
結果：可能出現意外的全局改動，或者影響到不該影響的文件。
正確做法：從默認的收緊權限開始，理解了工作流之後再針對性地放寬。
錯誤五：不用 worktree 在同一批文件上同時跑多個線程
多個 Codex 會話同時修改同一批文件，沒有隔離。
結果：改動衝突，搞不清楚哪個版本是對的。
正確做法：用 git worktree 隔離並行工作，每個線程在獨立的 worktree 裏操作。
錯誤六：還沒手動驗證可靠就把工作流自動化
急着把一個不穩定的工作流變成 Automation。
結果：自動化把不穩定的行為規模化了，反而比手動更難處理。
正確做法：先把工作流做成穩定的 Skill，跑幾次驗證它是可靠的，再設置自動化。
錯誤七：像盯着初級員工一樣盯着 Codex
每一步都在旁邊看着，不敢讓它跑完再檢查結果。
結果：Codex 的異步和並行優勢完全發揮不出來，效率和直接自己寫差不多。
正確做法：啓動任務之後去做自己的工作，回來 review 結果。把 Codex 當後台任務，不是實時對話。
錯誤八：每個項目一個線程
在一個線程裏積累整個項目的所有工作記錄。
結果：上下文越來越膨脹，Codex 越來越難從噪音裏找到相關信息，輸出質量隨時間劣化。
正確做法：每個任務或者每個獨立工作單元開一個新線程。用 /fork 在保留上下文的情況下創建分支線程。
一個完整的工作流
把官方文檔的所有建議串起來，一個成熟的 Codex 工作流大概是這樣的：
初始化階段（一次性）
- 1. 在倉庫裏跑
/init生成 AGENTS.md 初始版本 - 2. 修改 AGENTS.md 寫入實際的構建命令、驗證命令、約束和 pattern
- 3. 在
~/.codex/config.toml裏配置個人默認值 - 4. 接入高價值的 MCP 服務器（一兩個就夠）
日常任務流程
- 1. 每個任務開一個獨立線程
- 2. 按四要素框架寫 prompt（Goal + Context + Constraints + Done when）
- 3. 複雜任務先用 Plan mode 或者讓 Codex 先問你
- 4. 啓動之後去做自己的其他工作
- 5. 回來檢查結果，用 diff 面板 review
- 6. 發現穩定的 pattern 就封裝成 Skill
持續改進
- 1. Codex 犯了同一個錯誤兩次，更新 AGENTS.md
- 2. Skill 穩定了，設置 Automation
- 3. 定期讓 Codex 回顧最近的 session，更新配置和 AGENTS.md
最後說一句
官方文檔裏有一句話我覺得很準：
"Codex shouldn't just generate code. With the right instructions, it can also help test it, check it, and review it."
把這個理解吃透，Codex 就從一個寫代碼的工具變成了一個完成整個開發循環的系統。