重點速覽
寫好 AI 代理任務說明的重點，是把代理自己看不到、猜不到的資訊明確交代：要做什麼、在哪裡做、做到什麼算完成，以及哪些事不能碰。給它一個能判定通過或失敗的檢查，並要求它附上證據，比反覆叮嚀「要小心」有效得多。
AI 代理任務說明，就是你交給代理的那段文字：要它做什麼、在哪裡做、做到什麼程度算完成。AI 代理（AI Agent）是讓大型語言模型自己決定下一步、使用工具並依結果調整的系統，如果你還不熟，請先看 AI 代理是什麼。
代理做不好事，多半不是它不夠聰明，而是它缺少資訊。這篇整理出一套不依賴任何特定工具的寫法。
核心觀念：把它看不到的資訊交代清楚
Claude Code 的官方文件有一句很實用的提醒：只寫「代理無法從專案裡讀到的資訊」，或是它每次都得花時間重新摸索的資訊。因為代理一開始工作就會先讀你的檔案，它很擅長自己找到檔案結構、慣例與測試方式。
它找不到的是從來沒有寫在檔案裡的東西：
- 你們在會議上做的決定
- 只存在某個人腦中的作業流程
- 需要用到的環境設定
寫之前可以先問兩個問題：（1）它讀檔案就能找到嗎？（2）它真的會去找嗎？兩個都是「是」，就不用寫。
另一個檢驗方法來自 Anthropic 的提示詞指南：把你的說明拿給一位對這件事了解很少的同事看，請他照著做；如果他會困惑，代理也會。Anthropic 把模型比喻為「聰明但剛到職、不熟悉你們規矩與流程的新同事」。
任務說明的六個組成
| 組成 | 要回答的問題 | 沒寫的後果 |
|---|---|---|
| 目標 | 要做什麼？做完會看到什麼？ | 代理做出和你想的不一樣的東西 |
| 背景與原因 | 為什麼要這樣做？有什麼限制？ | 代理無法判斷取捨 |
| 範圍 | 哪些檔案或資料夾可以動？哪些不能碰？ | 動到不該動的東西 |
| 做法偏好 | 兩個合理做法之間，你偏好哪一個？ | 代理自己選，不一定是你要的 |
| 驗收標準 | 怎樣才算完成？用什麼檢查？ | 代理在「看起來完成」時就停下來 |
| 回報方式 | 完成後要告訴你什麼？ | 你不知道它到底做了什麼 |
驗收標準與檢查
Claude Code 的官方文件說得很直接：代理在工作「看起來完成」時就會停下來；如果它沒有任何能判定是否真的完成的東西，你就得自己當測試。給它一個能回報通過或失敗的檢查，它就能自己形成循環：做修改、執行檢查、失敗就讀輸出修正，再檢查一次。
檢查可以是很多形式，只要代理讀得懂結果：一份測試、一個建置指令的結束狀態、一個格式檢查工具，或是把輸出和預期範例比對的小程式。
無論用哪種，都要求它附上證據：它執行過的指令與輸出。這也是你在沒有盯著它做事時，唯一可靠的依據。
說明原因，而不只是下禁令
Anthropic 的提示詞指南舉了一個例子：與其寫「絕不要使用刪節號」，不如寫「這段回應會被語音合成引擎朗讀，所以不要使用刪節號，因為引擎不知道怎麼念」。有了原因，模型就能推廣到你沒有逐一列出的情況。
需要固定格式時，給範例
Anthropic 的指南指出，範例是引導輸出格式、語氣與結構最可靠的方法之一，並建議放 3 到 5 個範例；範例要貼近真實用途、涵蓋不同情況，並用清楚的標記和指示分開。
一個範本
下面是通用的格式，可以直接複製後修改。（範例內容是本站自己設計的示範，不是實測結果。）
【目標】
把「下載」資料夾裡的檔案，依副檔名整理到子資料夾（圖片、文件、壓縮檔、其他）。
【背景】
這個資料夾很久沒整理，我之後要用檔名找資料，所以檔名不要改。
【範圍】
只動「下載」資料夾第一層的檔案。不要進入子資料夾，不要刪除任何檔案。
【驗收標準】
1. 第一層不再有散落的檔案。
2. 檔案總數整理前後相同。
3. 沒有檔名被改變。
【回報】
先列出你打算移動的清單給我確認，確認後再執行。完成後貼出整理前後的檔案數量與你用的指令。對照看看「幫我整理下載資料夾」這種寫法：沒有範圍、沒有驗收、沒有確認步驟，代理只能自己猜。
交給代理自己跑之前，先問五個問題
Claude Code 的官方文件，列出讓代理在無人看管下執行之前的五個問題。以下是整理後的版本：
- 它知道「完成」長什麼樣子嗎？ 一個明確的目標條件、一份規格，或一個要讓它轉為通過的失敗測試。
- 它能檢查自己的成果嗎？ 測試、檢查工具，或某種審查步驟。
- 它被允許碰什麼？ 權限規則、隔離環境、只能推送的那一條分支。
- 什麼會讓它停下來？ 次數上限、花費上限。
- 結果送去哪裡、由誰核准？ 最後由人核准合併、部署，或任何收不回來的動作。
第 3 題和第 5 題，在 讓 AI 代理安全操作電腦 有更完整的說明。
常見錯誤
| 常見錯誤 | 為什麼有問題 | 改法 |
|---|---|---|
| 只說「整理好」「改善一下」 | 沒有驗收標準，代理不知道何時該停 | 寫出可檢查的完成條件 |
| 把整個專案或大量文件全部貼進去 | 上下文太多，準確度可能下降（見 大語言模型入門） | 只給和任務有關的部分，並指出檔案位置 |
| 只列禁止事項，不說原因 | 模型難以推廣到未列出的情況 | 說明原因與背後的目標 |
| 沒有說明哪些事要先問你 | 難以復原的動作可能直接被執行 | 明確列出需要先確認的動作 |
| 只信任「已完成」 | 沒有證據，錯誤會一直留在那裡 | 要求附上指令與輸出 |
不確定時，先要計畫
如果任務比較大，先請代理列出它打算怎麼做、會動到哪些檔案，等你確認後再執行。這個習慣能讓你在錯誤變大之前攔下來。需要把成果還原時，給 AI 使用者的 Git 入門 說明的版本控制會是你的後盾。
延伸閱讀
常見問題
給 AI 代理的任務說明越長越好嗎？
不是。重點是把代理「找不到、猜不到」的資訊寫進去，而不是把所有東西都塞進去。Claude Code 的官方文件建議先問自己兩件事：它讀檔案就能找到嗎？它會真的去找嗎？兩個答案都是肯定的，就不必寫。
任務說明要不要寫角色，例如「你是資深工程師」？
可以寫。Anthropic 的提示詞指南指出，替模型設定一個角色，能讓它的行為與語氣更貼近你的用途，即使只有一句話也有差別。不過角色不能取代目標、範圍與驗收標準，這三項要先寫清楚。
為什麼要告訴代理「為什麼」？
Anthropic 的文件說明，交代指示背後的原因，能讓模型更了解你的目標並產生更貼切的結果，因為它可以從原因推廣到沒明講的情況。
怎麼知道我的說明夠清楚？
把說明拿給一個對這件事了解很少的同事看，請他照著做。如果他會困惑，代理也很可能會。
代理說「已經完成」就可以相信嗎？
不要只看這句話。要求它附上實際執行過的指令與輸出，或給它一個能判定通過或失敗的檢查。單單一句「都通過了」，說明不了什麼。
可以讓代理整晚自己跑嗎？
可以，但前提是它知道完成的標準、能檢查自己的成果、只能碰該碰的東西、有次數或花費上限，最後由人核准結果。細節見下面的檢查清單。
留言
用 GitHub 帳號登入就能留言，留言會公開顯示在 GitHub Discussions。留言前請先看社群規則。