Coding Agent 為什麼容易失控？
從指令、權限、驗證到人工檢查，讓 AI 改程式時有範圍、證據與停止條件。
Coding Agent 會讀檔、改程式與執行指令。這篇用一個網站修改案例，教你從指令、權限、驗證與人工檢查四層降低失控風險。
文章目錄 11 節
我實際用 Coding Agent 做網站時，最麻煩的情況是它沒有報錯，還看起來一直在工作。
它會讀專案、修改檔案、執行指令、修正錯誤，最後回報任務完成。等我真的打開網站，才發現原本正常的版面被改掉、手機版跑版，或它為了修一個小問題，順手動了其他元件。
Coding Agent 可以讀檔、改程式和執行指令。模糊的需求因此會直接變成實際變更，影響範圍也比一般聊天回答大。
我現在會用四層方式控制 Coding Agent：
| 控制層 | 要回答的問題 | 常用方法 |
|---|---|---|
| 指令 | 這次要做什麼，範圍到哪裡？ | 任務目標、修改範圍、禁止事項、停止條件 |
| 權限 | 它實際可以執行哪些操作？ | Allow、Ask、Deny、沙盒、網路限制 |
| 驗證 | 有什麼證據能證明完成？ | 測試、程式碼規則檢查、型別檢查、建置、畫面檢查 |
| 人工檢查 | 哪些決定需要人來承擔？ | 計畫確認、變更差異檢查、合併與部署確認 |
這篇會用一個網站修改案例，把四層控制方法拆成可以直接套用的流程。
Coding Agent 的「失控」是什麼？
Coding Agent 失控不一定代表它執行了危險指令。更常見的情況是範圍逐漸擴大，而且每一步看起來都有理由。
例如你只要求修改一個按鈕，它可能同時重構共用元件、更換 CSS 寫法、安裝新套件，最後改了十幾個檔案。第一次修正失敗後，它也可能繼續換方法，讓後面的變更全建立在錯誤假設上。
另一種情況是把「指令成功」當成「需求完成」。建置通過只能證明專案成功產出，無法證明手機版、操作流程、錯誤狀態與原有功能都正確。
所以我判斷 Coding Agent 是否受控，不會只看它有沒有報錯。我會看三件事：
- 修改有沒有超出這次任務
- 結果有沒有經過適合的驗證
- 高風險操作有沒有停下來等人確認
先用一個網站修改案例看問題
假設文章卡片在 390px 寬度下超出畫面。
如果我只說：
幫我修好文章卡片的手機版。Agent 必須自己猜測修改範圍和完成標準。它可能調整卡片，也可能改共用版面配置、全站內容容器或圖片規則。只要頁面不再溢出，它就可能判斷任務完成。
但我真正要的是：
- 只處理文章卡片與直接相關的 CSS
- 桌機版維持原來的欄數和比例
- 圖片不能變形
- 390px、768px 與 1440px 都要檢查
- 同一個方向連續兩次失敗時先停下來
這些條件沒有寫出來，Agent 就無法穩定判斷邊界。
第一步：把任務邊界寫進指令
一份能執行的 Coding Agent 指令，至少要交代五件事：
- 任務目標
- 允許修改的範圍
- 明確禁止的變更
- 驗收標準
- 失敗與停止條件
可直接修改的任務模板
任務目標：
修正文章卡片在 390px 寬度下超出畫面的問題。
修改範圍：
先檢查文章卡片元件與文章列表頁的 CSS。
只有確認共用版面配置是根本原因時，才能提出修改版面配置的方案。
禁止事項：
不要更換 CSS 架構。
不要安裝新套件。
不要重新命名現有 CSS 類別名稱。
不要改變桌機版的欄數與卡片尺寸。
驗收標準：
1. 390px、768px 與 1440px 都沒有水平捲動。
2. 圖片不變形。
3. 標題與摘要不超出卡片。
4. npm run build 成功。
5. 回報修改檔案、原因與驗證結果。
停止條件：
同一個方向連續兩次修改後仍未解決時，停止繼續嘗試。
整理目前判斷、嘗試過的方法，以及需要我決定的地方。
Prompt 不需要刻意寫長。這份模板的作用，是讓範圍和完成條件可以被檢查。
長期規則放進專案文件
單次任務的目標放在當次指令。每次都適用的工作方式，才放進 CLAUDE.md、AGENTS.md 或其他專案規則，例如：
- 修改前先讀相關檔案
- 保留不屬於本次任務的既有變更
- 不要順手重構
- 不要自行安裝依賴
- 無法驗證時要明確回報
- 提交、推送與部署前先詢問
這些規則會影響 Agent 的工作方式。機密檔案、危險指令與正式環境存取仍要交給權限系統限制。
第二步：依風險設定權限
Coding Agent 的操作可以分成 Allow、Ask 與 Deny。
| 權限 | 適合的操作 | 例子 |
|---|---|---|
| Allow | 低風險、可重複、容易驗證 | 讀檔、搜尋、查看 Git 狀態、執行既有測試 |
| Ask | 會改變專案或外部狀態 | 寫檔、安裝依賴、修改設定、提交變更、存取網路 |
| Deny | 後果高或不應自行執行 | 讀取機密、正式部署、刪除資料、強制推送 |
判斷時可以問：
這個動作做錯之後，能不能輕易復原？
影響小、能用 Git 還原、結果容易檢查的操作，可以考慮自動允許。會碰到機密、正式環境、外部服務或不可逆變更的操作，適合保留詢問或直接禁止。
Claude Code 權限文件目前將規則分成 allow、ask 與 deny，並以 deny、ask、allow 的順序比對。OpenAI 也將 Codex 的沙盒與批准視為兩種不同控制：沙盒決定技術邊界，批准政策決定跨越邊界時何時要停下來詢問。可參考 Running Codex safely at OpenAI。
複雜任務先用唯讀方式探索
當任務涉及多個檔案，或我還不確定問題在哪裡，我會先要求 Agent：
- 讀取相關檔案
- 說明目前架構
- 找出可能原因
- 列出預計修改的檔案
- 等我確認後再寫入
Claude Code 的 Plan Mode就是把探索與實作分開。這能減少 Agent 很有效率地解決錯誤問題的情況。
第三步：把驗證寫成完成證據
我以前會讓 Agent 做完整個功能，最後才執行一次建置。當它已經改了十幾個檔案，測試失敗時很難看出問題從哪一步開始。
現在我會讓驗證跟著修改走：
- 先找到能重現問題的方式
- 修改最小範圍
- 執行和這次變更最相關的檢查
- 再跑完整測試與建置
- 檢查 Git 變更差異
- 完成畫面或操作流程驗收
不同任務需要不同證據：
| 任務類型 | 自動驗證 | 人工驗證 |
|---|---|---|
| 資料處理 | 單元測試、固定測試資料比對 | 邊界案例與輸出內容 |
| API 修改 | 整合測試、型別檢查 | 權限、錯誤訊息與相容性 |
| 前端版面 | 建置、瀏覽器主控台、截圖 | 響應式版面、視覺層級與操作感受 |
| 套件更新 | 建置、測試、漏洞掃描 | 破壞性變更、授權與維護狀態 |
| 資料庫變更 | 資料遷移測試、資料庫結構差異 | 備份、還原與正式執行 |
測試通過是一項證據。測試本身也需要檢查，因為 Agent 可能調整測試來配合目前的實作。
Anthropic 的 Claude Code 最佳實踐建議提供測試、建置、程式碼規則檢查工具或畫面比較等可驗證訊號。無法取得這些訊號時，Agent 很難知道自己是否真的完成。
不能省略的檢查可以交給 hooks
如果某項檢查每次都要執行，可以用 hooks 固定觸發。例如修改後執行程式碼格式化工具、操作前攔截危險指令，或結束前確認測試結果。
Hook 腳本本身也要有輸入檢查與停止條件。Claude Code hooks 文件提供 PreToolUse、PostToolUse 與 Stop 等事件，Stop hook 也會提供「stop_hook_active」，讓腳本辨識目前是否已經由停止 hook 要求繼續，避免無限重複。
第四步：把高風險決定留給人
每一行 AI 產生的程式都逐字檢查，成本很高。我會把人工判斷集中在後果大、難以復原或涉及產品責任的地方。
我通常會保留人工確認的操作包括：
- 正式部署、資料庫遷移
- 刪除或覆寫資料
- 權限、登入、驗證、金流與訂閱
- API 金鑰、Token 與環境變數
- 安裝或更換核心依賴
- 修改 GitHub Actions 或 CI/CD
- 公開 API 變更與大範圍重構
- 合併請求
- 品牌核心版面與對外內容
人工檢查可以放在三個位置：
實作前
確認 Agent 理解的問題、預計修改的檔案、新增依賴與驗收方式。
高風險操作前
遇到安裝依賴、修改設定、存取外部服務、提交、推送或部署時先停下來。
合併或部署前
查看「git diff --stat」、完整變更差異、測試輸出、預覽畫面與還原方法。
GitHub 對 Copilot cloud agent 也保留人類審查邊界。依照 GitHub 官方風險與緩解措施，Agent 建立的草稿合併請求需要人類審查與合併，GitHub Actions 預設也要由具寫入權限的人批准後才會執行。
套用到 Level UP 官網，我會怎麼跑一個任務？
以 Level UP 的 Astro 官網為例，我會使用這個順序：
- 先讓 Agent 讀取相關頁面、元件、資料與設計文件。
- 要求它說明問題、最小解法與預計修改的檔案。
- 確認範圍後再允許寫入。
- 每次只處理一個頁面或一個問題。
- 先跑局部檢查，再執行「git diff --check」與「npm run build」。
- 實際檢查桌機、平板、手機與瀏覽器主控台。
- 看完變更差異後，才決定是否提交、推送或部署。
例如改首頁 Hero 時，我不會同時要求重做文章卡片、Footer 與 SEO。每一輪都要能從變更差異看出修改目的，也要有獨立的驗收方式。
網站成功建置只代表程式可以產生。內容層級、品牌感覺和操作流程仍要打開頁面確認。
常見的五個控制錯誤
1. 把所有規則都寫進 CLAUDE.md 或 AGENTS.md
專案文件適合描述工作方式。機密存取、危險指令與部署權限要由 settings、沙盒或 hooks 執行。
2. 為了方便直接允許所有工具
可以先放行低風險操作，再依實際需求增加權限。一次打開所有權限，錯誤也會更快被執行。
3. 一次修改太多，最後才驗證
變更越大，失敗時越難找到原因。小範圍修改、局部驗證，再跑完整檢查，會更容易復原。
4. 只讓同一個 Agent 檢查自己的工作
重要任務可以開一個新對話、交給另一個 Agent，或由人重新閱讀原始需求和變更差異。
5. 把測試通過直接等同可以上線
測試只涵蓋已經寫進測試的行為。正式上線還要確認資料、權限、視覺、相容性與回滾方式。
合併或發布前的檢查表
- 任務目標和修改範圍清楚
- 沒有未說明的額外檔案
- 沒有新增不必要的依賴套件
- 機密、正式環境和外部服務受到限制
- 相關測試、程式碼規則檢查、型別檢查或建置已執行
- Git 變更差異已完整檢查
- 前端變更已看過桌機與手機畫面
- 高風險操作已由人確認
- 有需要時準備還原方式
總結
如果只記得一件事：先用指令限定任務，用權限限制行動，再以驗證提供完成證據，最後把高風險決定留給人。
剛開始不必一次建立完整的 Agent 治理系統。先挑下一個真實任務，補上修改範圍、驗收標準與停止條件，再把提交、推送、部署和機密存取設為人工確認。
這樣已經能避免很多「Agent 看起來做完了，實際卻留下更多問題」的情況。
參考資料與查核範圍
本文產品功能與安全機制查核日期為 2026 年 7 月 27 日，主要參考：
- Claude Code：Configure permissions
- Claude Code：Hooks reference
- Claude Code：Best practices
- OpenAI：Running Codex safely at OpenAI
- GitHub：Risks and mitigations for GitHub Copilot cloud agent
FAQ
Coding Agent 失控通常是什麼原因？
常見原因包括任務範圍模糊、工具權限超過需求、缺少能驗證結果的檢查，以及高風險操作沒有保留人工確認。
寫好 CLAUDE.md 或 AGENTS.md 就能避免 Coding Agent 亂改嗎？
這些文件可以固定工作規則，但仍要搭配權限限制、測試、差異檢查與人工審查。行為指示無法取代系統真正執行的存取控制。
哪些 Coding Agent 操作應該保留人工確認？
正式部署、資料刪除、資料庫遷移、權限與驗證邏輯、金流、機密資料、核心依賴、CI 工作流程、提交與推送，都適合先停下來確認。
