為代理程式撰寫任務說明

描述審查者能評估的變更

「新增客戶匯出功能」留下好幾項未決事項。誰能匯出紀錄？包含哪些紀錄與欄位？請求失敗時怎麼處理？代理程式可以用看似合理的選擇填補空白，但這些選擇仍可能不符合業務需要。

先說明使用者和問題，再描述必要行為，並納入能判斷結果是否可接受的證據。

任務說明應減少不確定性，不必鎖定所有內部設計選擇。指定必要資料邊界；除非有理由變更，否則讓實作沿用儲存庫既有模式。

使用具體範例

以下任務說明適用於虛構客服應用程式。它是教學範例，不是完整的正式環境規格。

結果：客服主管可以下載客戶清單。
操作者：目前組織中的主管。
資料：只包含該組織的活躍客戶。
欄位：客戶 ID、公司名稱和帳戶狀態。
格式：UTF-8 CSV，包含標題列。
遭拒請求：回傳既有的授權錯誤。
空白結果：回傳只有標題列的有效 CSV。
範圍：使用既有匯出路由和稽核模式。
排除：不新增角色、相依項目，也不部署。
證據：測試允許、拒絕、空白和跨組織請求。

這份說明指出有用行為與限制，也暴露更多問題。系統應限制匯出大小嗎？欄位能包含試算表公式嗎？誰能存取稽核紀錄？實作前，先解決後果重大的問題，不要把範例當作通用檢查清單。

區分需求與假設

需求描述變更必須滿足的行為；假設則是尚未驗證的事實。兩者應分開記錄。

例如，「使用既有稽核模式」假設已存在合適模式。請代理程式找出它。如果儲存庫中沒有，就應先回報缺少的相依條件，而不是自行發明新稽核系統。

限制也可能與結果衝突。既有路由可能原本就設計成回傳所有組織。代理程式應指出衝突，提出範圍有限的修正，不應默默移除資料邊界，或把任務擴大成架構重寫。

完成條件要包含證據

要求交付摘要說明最終行為、變動範圍和已執行檢查。必要時提供確切命令與結果，並區分檢查通過和檢查無法執行。

Pull request 應保留變更理由。後續維護者可能只看到程式碼，看不到最初對話。應提供足夠上下文，解釋匯出為何排除特定欄位，以及如何落實存取限制。

Google 的變更描述指引，是這類紀錄的有用參考。描述應解釋變更及其目的。審查造成修改後，也要讓紀錄與最終實作一致。

讓說明的詳細程度符合任務

小幅文字修正，可以用簡短說明。資料匯出失敗可能暴露資訊，因此需要更多細節。新的付款工作流程，則需要更多分析與審查。

不要用長度衡量任務說明品質。應問：合格審查者能否區分正確與錯誤結果？如果兩種合理實作會對後果重大的行為作出不同選擇，就先釐清該行為。