寫好 Codex 提示詞

你透過 prompts 和 Codex 互動。Prompt 描述你希望它做什麼，Codex 隨後進入迴圈：呼叫模型、讀取檔案、編輯檔案、執行命令和呼叫工具，直到任務完成或被取消。

好的 Codex prompt 不只是“請幫我做”。它要寫清目標、上下文、範圍、禁止事項、驗證方式和交付格式。

Prompting

官方 Codex prompting 基礎。

From theory to practice

把模糊需求改寫成可執行任務。

How a task completes

理解 Codex 從 prompt 到驗證的迴圈。

兩個簡單例子

解釋程式碼：

请解释 transform module 是如何工作的，以及其他模块如何使用它。

新增功能：

请添加一个新的命令行选项 `--json`，用于输出 JSON。

這兩個 prompt 能跑，但真實專案裡還不夠。要穩定交付，需要補上下文、範圍和驗證。

好 prompt 的結構

flowchart LR
    Goal["目標"] --> Context["上下文"]
    Context --> Scope["範圍"]
    Scope --> Boundaries["禁止事項"]
    Boundaries --> Verify["驗證"]
    Verify --> Deliver["交付"]

建議包含：

目標：使用者層面的結果是什麼。
上下文：相關檔案、錯誤日誌、截圖、連結、業務規則。
範圍：只允許動哪些檔案或目錄。
禁止事項：不新增依賴、不改資料庫、不動無關檔案等。
驗證：跑什麼測試、lint、build、截圖或人工檢查。
交付：最後彙報改動檔案、驗證結果、未驗證項和風險。

Outcome-first 寫法

GPT-5.5 的官方提示詞指導強調 outcome-first：先定義結果、成功標準、約束和可用上下文，讓模型選擇具體路徑。對 Codex 來說，這比寫一長串“先做 A、再做 B、再做 C”更穩，除非每一步都是業務硬約束。

可以用這個模板：

目标：
修复用户在移动端打开设置页时按钮错位的问题。

上下文：
- 复现路径：打开 /settings，宽度 390px，点击 Profile tab。
- 相关文件优先看 src/app/settings 和 src/components/tabs。

范围：
- 只改布局和样式相关文件。
- 不改接口、不改数据结构、不新增依赖。

验证：
- 跑现有 lint/build。
- 用浏览器检查 390px、768px、1440px 三个宽度。
- 最后说明改动文件、验证结果和残余风险。

這個 prompt 沒規定 Codex 必須先讀哪個檔案、後改哪個元件，但把目標和驗收寫清楚了。Codex 可以按實際程式碼結構選擇路徑。

停止條件和缺證據行為

長任務尤其要寫 stopping conditions。否則 Codex 可能一直擴大搜尋範圍或改到無關檔案。

建議直接寫：

如果沒有復現到問題，先停下並報告已檢查路徑，不要猜改。
如果需要新增依賴，先說明原因和替代方案。
如果測試失敗且與本次改動無關，記錄失敗命令和證據，不要順手大改。
如果超過約定範圍，先輸出計劃，等確認後再繼續。

缺證據時也要明確：

如果官方文档、源码和现象不一致，以本仓库当前源码和可复现行为为准；无法确认时标注为推断，不要写成确定结论。

複雜任務先拆

Codex 處理複雜工作時，拆成更小、更聚焦的步驟更穩。小任務更容易測試，也更容易 review。

如果不知道怎麼拆，先讓 Codex 只做計劃：

请先不要改文件。基于当前问题提出最小实现计划，列出需要读取的文件、可能风险和验证方式。

確認計劃後，再讓它執行第一步。

Prompt 裡應該少寫什麼

很多舊 prompt 會堆滿絕對規則，例如 ALWAYS、NEVER、must、only。官方提示詞指導建議把這些詞留給真正的不變數，例如安全邊界、必填欄位、絕對禁止的動作。

判斷類任務更適合寫 decision rules：

不推薦	推薦
“永遠不要聯網。”	“只有當本地資料不足或需要最新事即時聯網，並引用來源。”
“必須先讀所有檔案。”	“先讀入口檔案和呼叫鏈，發現範圍不足再擴充套件。”
“一定要完整重構。”	“優先最小改動；只有現有結構無法滿足目標時再提出重構計劃。”

對 Codex 來說，過多絕對規則會讓它在衝突指令裡浪費推理，甚至錯過更簡單的驗證路徑。