先把動詞換成可觀察的結果#

「修正登入錯誤」是工作方向，不是完成條件。它沒有指出要改哪個行為，也沒有指出誰來判定結果。

改寫時，讓每一項都能由指令、測試或檔案差異回答「是／否」。

Codex 的官方案例把困難問題描述為可評分的改進迴圈，也把「驗證結果」放進重複操作的工作流程。這是一個好提醒：agent 的產出不該只是一段敘述，而要留下一個可重新檢查的證據。

一份可直接貼上的任務契約#

我會把任務寫成四個區塊。它不需要很長，但每個區塊都要能限制 agent 的解讀空間。

1
目標：修正 /api/session 在過期 token 時回傳 500 的問題。
2

3
範圍：只可修改 src/auth/ 與對應測試；不要更新依賴或改 API 路徑。
4

5
完成條件：
6
1. 過期 token 的請求回傳 401，回應格式維持既有 schema。
7
2. 新增一個覆蓋此情境的測試。
8
3. 在專案根目錄執行 pnpm test 與 pnpm check，兩者皆成功。
9

10
停止條件：
11
- 若需要變更公開 API 或資料庫 migration，停止並說明原因。
12
- 若測試失敗，列出失敗指令、第一個錯誤與已嘗試的修正；不要宣稱完成。

其中最有價值的是「停止條件」。它把需要人決定的分岔明講出來，避免 agent 為了追求完成而擴大修改範圍。

把驗證指令寫成任務的一部分#

不要只說「記得測試」。請指定工作目錄、指令與成功標準；否則 agent 可能只讀程式碼、只跑了不相關的檢查，或把失敗當成環境雜訊略過。

1
# 在 repository root 執行
2
pnpm test -- --runInBand
3
pnpm check
4
pnpm build

若專案沒有完整測試，仍可要求較小的證據，例如 git diff --check、一個 API 呼叫、或針對問題函式的最小重現腳本。關鍵不是湊出很多指令，而是讓每個指令能驗證一項完成條件。

不要把「已執行」當成「已通過」

回報必須包含指令的結果。若因缺少環境變數、服務未啟動或測試本身壞掉而無法驗證，應標成未驗證，而不是寫成完成。

對多步任務，先要求一份變更地圖#

涉及多個資料夾時，先讓 agent 交出它預計讀取、修改與驗證的位置，再開始寫入。這一步特別適合陌生 codebase：你可以先發現它是否把問題定位到錯誤模組。

1
先不要修改檔案。請列出：
2
1. 你認為的根因與證據。
3
2. 預計修改的檔案。
4
3. 每個檔案對應的驗證方式。
5
4. 哪些資訊不足以安全開始。

確認後再給執行權限。這比要求 agent 一次做完所有事慢一個回合，卻能把「看似合理但改錯地方」的成本壓低很多。

回報格式也要能被檢查#

最後一段回覆建議固定成三件事：變更、證據、未解決項目。不要讓「完成」成為一個沒有內容的標籤。

1
變更：src/auth/validate.ts、src/auth/validate.test.ts
2
證據：pnpm test（通過）；pnpm check（通過）
3
未解決項目：無

如果任務需要人工驗收，請讓它提出具體操作，例如「用已過期的 token 呼叫此 endpoint，預期收到 401」。人類接手時不必重新猜一次要看什麼。

這次要記住的事#

AI coding agent 不是因為多寫幾句「請仔細」就更可靠；可靠性來自能被重跑的完成條件。把目標、範圍、驗證與停止條件寫清楚，agent 即使卡住，也會留下足以讓你判斷下一步的訊息。

常見問題#