把任務講成規格:一個好的 Codex 指令長什麼樣

入門兩課你大概感覺到了：同樣交給 Codex，有時一次到位，有時改出一個能跑但不是你要的東西。

九成的差別不在它，在你那句話。寫好給 agent 的任務，就是 prompt engineering;但對工程師，有個更熟的講法：把任務當成一份規格來寫。

一份好規格的四塊

1. 目標——要它達成什麼，講行為不講實作。 「讓匯出 CSV 支援自訂欄位順序。」

2. 相關檔案——它該看哪裡、參考什麼 pattern。 「匯出在 export/csv.ts，設定在 export/config.ts，照 export/pdf.ts 處理欄位順序的方式做。」

3. 預期結果與驗收標準——怎樣算做完。工程師最該給、也最容易漏的一塊。 「使用者能拖拉欄位順序，匯出照新順序。補測試涵蓋自訂與預設順序，npm test 要綠。」

4. 界線——什麼不要碰、什麼要先問。 「不要改既有的欄位篩選。不要動 schema。要跑 migration 先停下來問我。」

結果不如預期時，十之八九是缺了一塊——工程師最常缺第三塊：沒給驗收標準，於是它自我感覺良好地交了一個沒測到邊界的版本。

給驗收標準，讓它自己知道做完了沒

這是 coding agent 特別有用的一招：把「怎樣算對」變成它能自己跑的東西。

• 給能跑的測試：「補這幾個測試並讓它們通過」比「確保正確」具體一萬倍。
• 給明確的預期行為：輸入什麼、該輸出什麼、邊界怎麼處理。
• 給可執行的檢查：「跑 lint 和測試，都綠才算完成。」

當驗收是它能自己跑的東西，它會反覆改到通過，你收到的版本品質高很多。

用範例，別用形容詞

「寫乾淨一點」會被各種解讀，「照 users.ts 的寫法」不會。指一個現成的檔當範本——命名、錯誤處理、測試風格，它會照著抄。你的 codebase 本來就是最好的 style guide。

大任務：先計畫，再動手

「重構整個通知系統」這種任務，一次叫它改，它只能邊做邊猜，你也難審。先讓它出計畫、別寫 code:

「先不要改任何檔。給我一個重構通知系統的計畫：要動哪些檔、分幾步、每步的風險、怎麼驗。等我確認再開始。」

你看過計畫、確認方向，再放它動手。在它寫了 500 行你才發現方向錯之前，先用一段計畫對齊。 這在 Codex 上尤其值得——大任務可能跑很久(下一階段會講可恢復的長流程)，先把方向釘對，省下的是整段重跑。

練習：把你上一個失敗的指令改成規格

回想入門階段有沒有哪次它改出不是你要的東西？對照四塊檢查：目標清楚嗎？指了相關檔嗎？給了驗收標準嗎？設了界線嗎？補上缺的，再交一次。

下一課：它會跑指令、改你的檔，還能讓你用手機核准——在你放手讓它跑更多之前，先學會用 approval 與權限設好哪些自動、哪些一定要你放行。