AI coding agent 最常見的翻車原因，不是模型不會寫程式，而是任務給得太模糊。
「幫我修 bug」對人類同事也不夠清楚，對 agent 更危險。它可能會找錯檔案、改太多範圍、補一個看似合理但不符合產品邏輯的解法，最後留下一個很漂亮、但很難 review 的 diff。
好的 prompt 不需要很玄。
它只要把四件事說清楚：
- 目標：這次要解決什麼問題
- 邊界：可以改哪裡，不能碰哪裡
- 驗收：怎樣才算完成
- 回報：改了什麼、測了什麼、還有什麼風險
下面這 １２ 個範本，可以直接用在 OpenAI Codex、Claude Code、Cursor Agent、Cline、Aider 等工具。
使用前先記住三條規則
規則一：先分析，再改檔
第一次 prompt 不要叫它直接動手。先叫它讀 repo、找相關檔案、提出計畫。
規則二：限制範圍
指定可改檔案或目錄。不要讓 agent 在整個 repo 裡自由發揮。
規則三：要求測試與風險回報
agent 改完後，一定要回報測試結果、未測項目與可能風險。這會讓 review 成本低很多。
範本一：讀 repo 與整理架構
適合新進專案、接手陌生 codebase、開始修改前。
請先不要修改任何檔案。
請閱讀這個專案，整理以下內容：
１. 專案主要入口與執行流程
２. 重要資料夾與用途
３. 主要資料流
４. 測試與 build 指令
５. 最可能影響這次任務的檔案
回覆請用條列式，不要產生程式碼。這個 prompt 的目的，是讓 agent 先建立地圖。
如果它對專案理解錯，後面所有修改都會偏。
範本二：根據 Issue 找相關檔案
適合從 ticket、bug report、GitHub issue 開始。
請先不要修改任何檔案。
這是本次 issue：
【貼上 issue 內容】
請找出可能需要閱讀或修改的檔案，並說明原因。
請分成三類：
１. 必須閱讀
２. 可能需要修改
３. 不建議碰的高風險區域
最後請提出一個最小修改計畫。這能避免 agent 一開始就亂改。
特別是大型 repo，先找對檔案比直接寫 code 更重要。
範本三：要求修改計畫
適合你已經知道問題，但還不想讓 agent 動手。
請先不要修改檔案。
目標：
【描述要修正或新增的行為】
限制：
【列出不能改的模組、檔案或行為】
驗收條件：
【列出完成後應符合的行為與測試】
請提出修改計畫，包含：
１. 需要改哪些檔案
２. 每個檔案預計怎麼改
３. 需要新增或更新哪些測試
４. 可能風險
５. 是否需要我先確認這是最重要的 prompt 之一。
它把 agent 從「直接產 code」變成「先做工程規劃」。
範本四：小型 bug fix
適合錯誤訊息明確、可重現、影響範圍小的 bug。
請修正以下 bug。
錯誤現象：
【描述目前錯誤行為】
預期行為：
【描述正確行為】
重現步驟：
【列出步驟】
限制：
１. 只修改和此 bug 直接相關的檔案
２. 不新增依賴
３. 不修改公開 API，除非必要並先說明
４. 不讀取或輸出 secrets
完成後請回報：
１. root cause
２. 修改摘要
３. 測試結果
４. 還有哪些 edge case 沒有覆蓋不要只貼 stack trace。
要補上預期行為，否則 agent 可能只修掉表面錯誤。
範本五：補單元測試
適合降低風險、提升 coverage、保護既有行為。
請為以下功能補單元測試。
目標檔案：
【列出檔案】
需要保護的行為：
【列出行為】
請先分析現有測試風格，再新增測試。
限制：
１. 不修改產品邏輯，除非發現測試無法通過並先說明原因
２. 不為了通過測試而放寬 assertion
３. 測試要包含 happy path 與至少兩個 edge case
完成後請回報新增測試涵蓋了哪些行為。這個範本特別適合第一次導入 AI coding agent 的團隊。
補測試風險低，又能訓練 agent 理解 codebase。
範本六：安全 review
適合登入、權限、付款、檔案上傳、API token、資料匯出等高風險功能。
請做安全 review，先不要修改檔案。
審查範圍：
【列出檔案或 PR diff】
請檢查：
１. 權限是否可能繞過
２. 是否有輸入驗證不足
３. 是否可能洩漏 secrets 或個資
４. 是否有 injection 風險
５. 是否新增不必要依賴
６. 是否缺少 audit log 或錯誤處理
請用風險等級分類：
高風險、中風險、低風險。
請不要直接修，先列出發現與建議。安全相關任務不建議讓 agent 直接自動改完就 merge。
先讓它做第二雙眼睛，比直接交付更穩。
範本七：PR Review
適合請 AI 先幫 reviewer 整理風險，但不能取代人類 review。
請 review 這個 PR diff。
請特別檢查：
１. 是否符合原 issue
２. 是否有超出範圍的修改
３. 是否可能改壞既有行為
４. 測試是否足夠
５. 是否有安全或權限風險
６. 是否有不必要抽象或過度重構
請用以下格式回覆：
高風險問題：
中風險問題：
低風險建議：
需要作者補充的問題：這個 prompt 適合用在 AI 產生的 PR，也適合人類 PR。
但要記得：AI review 是輔助，不是簽核。
範本八：限制 agent 不要過度重構
適合 agent 常常改太多的情境。
請只做最小必要修改。
本次任務不是重構。
限制：
１. 不更動檔案結構
２. 不重新命名公開函式或 component
３. 不抽新 helper，除非能明顯減少重複
４. 不格式化與任務無關的檔案
５. 不改 UI 文案，除非任務需要
如果你認為需要重構，請先提出理由，等我確認後再做。很多 agent 很愛順手整理。
但順手整理會讓 PR 變難 review。
範本九：讓 agent 只做文件
適合 README、runbook、API docs、changelog。
請只更新文件，不修改任何程式碼。
目標：
【描述要補的文件內容】
請根據現有程式碼與測試整理，不要憑空新增不存在的功能。
請檢查：
１. 指令是否和 package scripts 一致
２. 環境變數名稱是否正確
３. API 範例是否符合實作
４. 是否需要補上限制或注意事項
完成後請列出你查證過的檔案。文件任務很適合 agent，但要防止它寫出不存在的功能。
所以要要求它列出查證依據。
範本十：依錯誤訊息 debug
適合測試失敗、build fail、runtime error。
請協助 debug 以下錯誤。
錯誤訊息：
【貼上錯誤】
發生情境：
【貼上執行指令或使用者操作】
請先不要修改檔案。
請先回覆：
１. 錯誤最可能的三個原因
２. 需要檢查哪些檔案
３. 建議先跑哪些指令確認
４. 最小修復計畫
等我確認後再修改。debug 時先假設 agent 也可能看錯。
先讓它列假設，再用指令或測試驗證。
範本十一：重構前建立保護網
適合你想讓 agent 做重構，但怕改壞行為。
我想重構以下模組：
【模組或檔案】
請先不要重構。
第一步請先建立保護網：
１. 找出目前最重要的行為
２. 檢查現有測試是否覆蓋
３. 補足必要測試
４. 跑測試確認目前行為
只有在測試保護完成後，才提出重構計畫。這個範本很重要。
重構不是先改得漂亮，而是先保護行為。
範本十二：交付前自我檢查
適合 agent 改完後，要求它再檢查一次。
請在交付前做自我檢查。
請確認：
１. 是否完全符合原任務
２. 是否有超出範圍的修改
３. 是否新增依賴
４. 是否碰到 secrets 或高風險檔案
５. 是否跑過相關測試
６. 是否有未測項目
７. 是否有需要 reviewer 特別注意的地方
請用「可以 review」或「不建議 review，原因是……」作為最後結論。這能逼 agent 把風險講出來。
如果它自己承認沒跑測試或改太多，就不要急著 review。
一個完整範例：從 bug 到 PR
你可以把流程串起來：
第一輪：只讀 repo，找相關檔案與提出計畫。
第二輪：縮小範圍，只允許改指定檔案。
第三輪：修改 bug，補測試，回報測試結果。
第四輪：自我檢查，列出風險。
第五輪：由人類做正式 PR review。這樣看起來比較慢，但比「一次叫 AI 全部做完」穩很多。
AI coding agent 的效率來自可控的拆解，不是一次丟最大任務。
哪些事情不要用 prompt 解決？
有些問題不是 prompt 可以根治。
| 問題 | 應該怎麼解 |
|---|---|
| agent 讀到 secrets | 用權限與 sandbox 擋，不是靠提醒 |
| agent 自動裝依賴 | 工具層禁止，新增依賴需 approval |
| agent 改太多檔案 | 限制可寫路徑與任務範圍 |
| PR review 太草率 | 建立 review checklist 與 owner review |
| 測試不足 | 補測試與 CI gate，不是只叫 AI 小心 |
| 成本失控 | 設定使用量、模型路由與任務分級 |
Prompt 是工作流的一部分，不是安全系統。
如果某件事真的不能發生，就不要只寫在 prompt 裡。要用工具、權限與流程擋下來。
FAQ
這些 prompt 可以直接用在 Codex 嗎？
可以。Codex、Claude Code、Cursor Agent 的介面不同，但任務拆解邏輯相同。你可以把範本貼進工具，再替換成自己的 issue、檔案與限制。
為什麼要一直寫「請先不要修改檔案」？
因為 AI coding agent 很容易太快進入執行模式。先分析能讓你確認它理解正確，也能避免它在錯誤方向上改太多。
Prompt 寫得夠清楚，就可以不用 review 嗎？
不可以。Prompt 可以降低錯誤率，但不能保證正確。AI 產出的 diff 仍然要跑測試、看範圍、看安全風險，最後由人類決定是否 merge。
團隊要不要統一 prompt 範本？
要。統一範本可以降低溝通成本，讓 PR 描述、測試回報與風險揭露更一致。尤其多人使用 AI coding agent 時，標準化比個人技巧更重要。
結論：好的 prompt，是把工程判斷寫清楚
AI coding agent prompt 的核心，不是把 AI 叫得更聽話，而是把工程任務定義得更清楚。
目標清楚，agent 才知道要做什麼。
邊界清楚，agent 才不會亂改。
驗收清楚，reviewer 才知道怎麼判斷。
風險清楚，團隊才知道能不能 merge。
所以最好的 AI coding prompt，其實就是好的工程溝通。
工具會進步，但這個原則不會變。
延伸閱讀
- AI Coding Agent 工作流實戰：從 Issue 到 PR 的 ６ 步驟
- AI 產生的 PR 怎麼 Review？２０２６ 年工程團隊必備檢查清單
- OpenAI Codex 是什麼？２０２６ 年給開發者與企業的完整導入指南
- 企業 AI Coding Agent 評估指南：２０２６ 年導入 Codex、Claude Code、Cursor 要看什麼？