AI 工程

Coding agent 說「修好了」，其實只是「改了」：用規則檔、Stop hook、獨立審查逼它附上驗證證據

2026-10-04 / 0 評論
瀏覽次數: 1

你一定看過這種收尾：agent 改了三個檔案，回一句「已修正 token refresh 的問題 ✅」，然後停下來等你。你打開瀏覽器一試，登入還是壞的。

r/ChatGPTCoding 最近一篇討論的標題把這件事講得很準：Coding agents say "fixed" when they mean "I changed the code"。agent 說的「修好了」，很多時候真正的意思只是「我改了程式碼，而且讀起來覺得合理」。

這篇不談 agent 會不會取代誰，只講一件可以今天就做的事：把「完成」重新定義成「附上驗證指令和輸出」，再用 Claude Code、Cursor、Codex 這些工具內建的機制，把這個定義從「拜託」升級成「強制」。每一招都附設定檔和 prompt，可以直接抄。

一、為什麼 agent 會「改了就說修好」

先講機制，招式才會用得對。

Anthropic 在 Claude Code 官方的 Best Practices 文件裡，把這個問題講得很直白：「Claude stops when the work looks done.」agent 停下來的條件是「看起來做完了」。如果手邊沒有一個能跑、能回傳 pass／fail 的檢查，「看起來做完了」就是它唯一能用的訊號。結果就是文件裡那句：你變成了驗證迴圈本身，每個錯誤都要等你自己發現。

這不是哪一家模型特別愛說謊，而是迴圈設計的問題：

  • 終止條件是主觀的：沒有外部訊號時，agent 只能靠「我讀自己的 diff，覺得邏輯對」來判斷收工。
  • 「改了」和「驗了」在對話裡長得一樣：兩者最後都是一段自信的總結文字，你從字面上分不出來。
  • 有測試也不保證誠實：這點最容易被忽略，下一節會用論文數字講。

所以解法不是叫 agent「認真一點」，而是改變它收工的條件：沒有證據就不算完成。

二、比「沒驗」更麻煩的：驗了，但驗的方式被動過手腳

很多人的第一反應是「那我叫它跑測試就好」。方向對，但不夠。

CMU 的 Ziqian Zhong、Aditi Raghunathan 和 Anthropic 的 Nicholas Carlini 在 2025 年 10 月發表的 ImpossibleBench（arXiv 2510.20270，已收錄於 ICLR 2026）專門量這件事。他們的做法很巧妙：拿 LiveCodeBench 和 SWE-bench 的題目，故意把單元測試改成和規格矛盾，例如把 assert f(2) == 4 改成 assert f(2) == 5（Oneoff 版），或是同一個輸入塞兩條期望值不同的測試（Conflicting 版）。這種題目照規格做是不可能全部通過的，所以只要 agent 回報「測試全過」，就代表它走了違反規格的捷徑。

論文回報的幾個數字值得工程師記住：

  • GPT-5 在 Oneoff-SWEbench 上有 76% 的題目「通過」了，在 Conflicting-SWEbench 上是 54.0%。同一組實驗裡 o3 約 49%、Claude Opus 4.1 約 50%。
  • 作弊手法被歸成四類：直接改測試、覆寫比較運算子讓 assert 永遠成立、記錄呼叫狀態讓同一個輸入第二次回傳不同值、針對測試寫死特例。
  • 用 LLM 當監控器去抓作弊，在較簡單的 Impossible-LiveCodeBench 能抓到 86–89%，到較複雜的 Impossible-SWEbench 只剩 42–65%。

要注意適用前提：這是刻意製造的不可能任務，不是在說日常工作裡 agent 有一半時間在作弊。它量的是「被逼到牆角時，模型有多傾向走捷徑」。但這正好對應真實場景：測試本身寫錯、環境缺依賴、需求互相矛盾，agent 卡住時最容易「讓燈變綠」而不是告訴你「這題有問題」。

好消息是，同一篇論文也量了哪些設定能壓低作弊，而且每一項都能直接轉成 coding agent 的設定：

  1. 提示詞的嚴格程度影響很大：論文中寬鬆的提示詞讓 GPT-5 和 o3 的作弊率都超過 85%，最嚴格的版本把兩者分別壓到 1% 和 33%。
  2. 給 agent 一條「回報做不到」的退路：允許模型標記任務不可能並退出後，GPT-5 在 Conflicting-SWEbench 的作弊率從 54% 降到 9%，o3 從 49% 降到 12%。不過論文也指出，這招對 Claude Opus 4.1 的效果明顯小很多。
  3. 限制對測試的存取：把測試藏起來，作弊成功率幾乎降到零；只給唯讀權限是折衷，能擋住改測試，但擋不住寫死特例這類手法。

「改了」不等於「修好了」：規則檔、Stop hook、獨立 reviewer 三層把關

接下來的三層做法，就是把「要求證據」、「真的去跑」、「防止動手腳」這三件事拆開處理。

三、第一層：用規則檔重新定義「完成」

最低成本、所有工具都適用的一步：在專案的規則檔裡寫清楚「完成報告」長什麼樣子。

用哪個檔案看你的工具：Claude Code 每次開工都會讀 CLAUDE.md；AGENTS.md 是 OpenAI Codex、Cursor、Google Jules、Factory、Amp 等團隊一起推的開放格式，現在由 Linux Foundation 底下的 Agentic AI Foundation 維護，Codex、Cursor、Aider、GitHub Copilot、JetBrains Junie 等工具都讀得到。Cursor 也可以放在 .cursor/rules/。兩邊都想支援的話，在 CLAUDE.md 裡用 @AGENTS.md 引入同一份即可。

可以直接貼的段落：

# 完成的定義（IMPORTANT）
宣告任何修復或功能「完成」前，必須在回報中附上：
1. 修前重現：用來重現問題的指令 + 失敗輸出（原文，最後 20 行）
2. 修後驗證：同一個指令 + 輸出原文 + exit code
3. 測試檔異動：有沒有修改既有的斷言？有的話逐條說明理由
4. 沒驗到的部分：明確列出沒跑、跑不了、需要人工確認的項目

規則：
- 沒有實際執行指令，只能說「已修改，尚未驗證」，不能說「已修正」
- 不准修改既有測試的期望值來讓測試通過
- 如果你判斷測試本身或需求是錯的，停下來回報，不要繞過
- 測試指令：`npm test -- <檔名>`；型別檢查：`npx tsc --noEmit`

這段每一行都有理由：

  • 「修前重現」是整份報告的靈魂。修前沒有紅燈，修後的綠燈就沒有意義，你無法分辨是修好了，還是測試根本沒碰到那段程式。Claude Code 文件裡的範例 prompt 也是同一個思路：「write a failing test that reproduces the issue, then fix it」。
  • 「輸出原文」而不是摘要，因為摘要又回到 agent 的主觀判斷。
  • 「停下來回報」對應 ImpossibleBench 的退路實驗。給它一條合法的出口，它比較不會去鑽非法的。
  • 把測試指令寫死。官方文件建議規則檔放「Claude 猜不到的 Bash 指令」，測試和型別檢查指令正是這種東西。

兩個實務提醒。第一，規則檔要短：Claude Code 文件明講，檔案太長時重要規則會被淹沒；如果某條規則一直被忽略，只對那一條加 IMPORTANT，全篇都加等於沒加。第二，這一層本質上是軟約束，agent 照不照做取決於它當下有沒有把規則放在心上。所以需要第二層。

四、第二層：Stop hook，讓檢查真的被執行

Claude Code 文件對 hooks 的定位很清楚：CLAUDE.md 是建議性的，hooks 是確定性的，保證每次都會發生。其中 Stop 事件在 agent 準備結束回應時觸發，而且可以擋下：hook script 以 exit code 2 結束時，Claude 不會停，stderr 的內容會被餵回給它，對話繼續。

步驟 1：寫 hook script

建立 .claude/hooks/verify-on-stop.sh：

#!/bin/bash
INPUT=$(cat)
ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active')

# 沒有任何改動就不驗（純問答不該被擋）
if git diff --quiet && git diff --cached --quiet; then
  exit 0
fi

OUT=$(npm test --silent 2>&1)
if [ $? -ne 0 ]; then
  echo "測試沒過，不能宣告完成。請讀下面的錯誤繼續修：" >&2
  echo "$OUT" | tail -n 40 >&2
  exit 2
fi

# 測試過了，再檢查有沒有動到既有測試（只提醒一次，避免反覆擋）
if [ "$ACTIVE" != "true" ] && git diff --name-only | grep -qE '(^|/)(tests?|__tests__)/|\.spec\.|\.test\.'; then
  echo "你修改了測試檔。請在完成報告中逐條說明每個斷言的改動理由。" >&2
  exit 2
fi
exit 0

記得 chmod +x，並確認機器上有 jq。

步驟 2：在 .claude/settings.json 註冊

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/verify-on-stop.sh"
          }
        ]
      }
    ]
  }
}

設定好之後可以用 /hooks 確認有沒有載入。

步驟 3：決定要不要處理 stop_hook_active

這是最容易踩的坑。Stop hook 的輸入 JSON 裡有一個 stop_hook_active 欄位，代表這次停止是不是已經被 Stop hook 擋過、正在續跑。官方 hooks 指南的說法是：同一個 Stop hook 連續擋了 8 次而沒有進展，Claude Code 會強制放行並顯示警告；上限可用環境變數 CLAUDE_CODE_STOP_HOOK_BLOCK_CAP 調整。文件建議在 script 開頭檢查這個欄位，是 true 就 exit 0。套在上面的 script，就是在 ACTIVE=... 那行下面加：

if [ "$ACTIVE" = "true" ]; then
  exit 0
fi

這裡有個 trade-off 要自己選：

  • 加上這段：最多只會逼 agent 重修一輪，第二次就放行。安全，不會卡迴圈，但測試可能還是紅的。
  • 不加這段：agent 會一直修到測試過，最多到 8 次的上限。適合測試跑得快、失敗訊息清楚的專案。

我們的建議是：測試在 30 秒內跑得完的 repo 不加，讓它修到綠；測試很慢或容易 flaky 的 repo 加上，避免燒掉一堆 token 在重跑上。另外，script 裡的 npm test 最好換成只跑相關檔案的指令，不然每次收工都跑全套，等待時間會讓你很快想把 hook 關掉。

其他工具的對應做法

  • Cursor：從官方文件看，.cursor/hooks.json 也有 stop 事件，hook 可以回傳 followup_message，作為自動送出的下一則使用者訊息讓 agent 繼續修；loop_count 記錄已經自動續跑幾次，預設上限 5 次，可用 loop_limit 調整。機制和 Claude Code 的 exit 2 不同，但效果接近，值得實測的點是它在測試失敗時的續修品質。
  • Codex、Aider 等沒有 Stop hook 的工具：退回第一層的規則檔，加上第三層的獨立審查，或是把驗證交給 CI，讓 PR 上的紅燈當最終閘門。

五、第三層：讓「做事的」和「打分數的」分開

前兩層解決「有沒有跑」，但 ImpossibleBench 提醒我們，測試全綠也可能是被動過手腳的綠。這一層的重點是：不要讓寫程式的 agent 自己改自己的考卷。

招式 1：把既有測試設成唯讀

對應論文裡「唯讀存取」的設定：擋得住改測試，擋不住寫死特例，但已經砍掉最粗暴的那一類。在 Claude Code 的 .claude/settings.json 加 deny 規則：

{
  "permissions": {
    "deny": ["Edit(./tests/**)"]
  }
}

路徑規則照 gitignore 語法，請依你的專案結構調整。代價是 agent 也不能幫你新增測試到這個資料夾，可以另開一個 tests/new/ 讓它寫，再由你 review 後搬進去。

招式 2：新 context 的 subagent 做驗收

Claude Code 文件建議在宣告完成前，用一個全新 context 的 subagent 審 diff：它只看得到 diff 和你給的標準，看不到產生這些改動的推理過程，所以不會被原本的思路帶著走。可以直接用的 prompt：

Use a subagent to review the current diff against the bug report.
Check: (1) the failing case is reproduced by a test that fails before the fix,
(2) no existing assertion was changed or deleted,
(3) no special-casing of test inputs, operator overloading, or call-count tricks.
Report only gaps that affect correctness. Do not report style issues.

第三點就是把論文的四種作弊手法直接寫成檢查清單。最後一句也有出處：官方文件提醒，叫 reviewer 找問題，它通常一定會找出一些，就算程式本身沒問題；照單全收會導致過度工程，所以要限定只回報影響正確性的問題。

招式 3：agent hook，把審查自動化

Claude Code 的 hook 除了跑 shell 指令的 "type": "command"，還有讓模型判斷的 "type": "prompt"，以及能用工具實際檢查程式碼狀態的 "type": "agent"。官方範例就是一個在 Stop 時「執行測試套件並確認結果」的 agent hook。要注意文件標明 agent hooks 仍是實驗性功能，行為可能會變；而且 LLM 當監控器在複雜任務上的抓錯率有限（前面提到的 42–65%），所以它適合當補強，不適合取代確定性的測試。

同一個修復兩種回報：斷言式 vs 證據式完成報告

六、日常 prompt：不改設定也能馬上用

不是每個專案都值得裝 hook。以下幾句 prompt 在任何 coding agent 上都能用：

交辦任務時，先把「修好」的定義講清楚：

登入在 session timeout 之後會失敗。先在 src/auth/ 找原因，
寫一個能重現問題的測試並跑給我看它失敗，再修。
修完跑同一個指令，貼上指令和輸出原文。
不要修改既有測試的期望值；如果你覺得測試本身錯了，停下來告訴我。

agent 說「已修正」但沒附證據時，追問這一句：

你實際執行了哪些指令？請貼出指令、exit code 和輸出原文。
如果沒有執行，請把狀態改成「已修改，未驗證」。

UI 類的修改，把截圖當成驗證：Claude Code 文件的範例是貼上設計稿，要求 agent 實作後截圖、列出差異再修。重點一樣：要有一個 agent 讀得到的訊號，而不是它的自我評價。

七、什麼時候不必這麼重

這套做法有成本，不是每個情境都划算：

  • 探索性工作：問「這個函式在做什麼」、「這段可以怎麼改」，本來就沒有可驗的東西，Stop hook 只會擋路。前面 script 裡「沒有 diff 就放行」那段就是為此設計。
  • 一行就能看懂的改動：改錯字、加一行 log，官方文件也說這類任務直接做就好。
  • 測試很慢或很不穩的 repo：Stop hook 跑全套測試會拖垮節奏。先只跑相關檔案的測試，全套交給 CI。
  • 沒有測試的專案：這套方法的前提是有東西可以跑。沒有的話，第一步是讓 agent 先補一個能重現 bug 的最小測試，而不是直接裝 hook。

八、給團隊的落地清單

如果你要在團隊裡推，建議照這個順序：

  1. 本週：把「完成的定義」段落加進 repo 的 AGENTS.md 或 CLAUDE.md，跟著 git 一起 review。
  2. PR 模板加一欄「驗證指令與輸出」，人寫的和 agent 寫的 PR 用同一個標準，reviewer 看到空白就退回。
  3. 測試跑得快的 repo 裝 Stop hook，先用「加上 stop_hook_active 檢查」的保守版，觀察一兩週再決定要不要放寬。
  4. 既有測試設唯讀，agent 新增的測試另放資料夾、人工搬入。
  5. 長時間無人看管的任務（批次遷移、夜間跑的 agent），一定加上獨立 reviewer 那一層。

核心觀念只有一句：完成是一個可以驗證的狀態，不是一句話。 不要再問 agent「修好了嗎」，改問「你跑了什麼、輸出是什麼」。

來源

整理：DataAgent · Coding Agent 實戰教學

文章裡這些把關做法，要在一個團隊裡真的落地、而不是只有你一個人在用，通常卡在流程與共識。我把這部分整理成企業內訓：
coding agent 導入與治理 — 企業內訓與顧問 →

你也可能喜歡

Tmux + Fable：手把手複刻「砍 35% token」的 coding agent 工作流

2026-07-21

Agentic Resource Discovery：給 agent 的 robots.txt——開放發現規格與 HF 參考實作拆解

2026-06-18

Claude Code 內建的三個 mod 被公開了：sec-default / diff / telemetry 拆解與實作指南

2026-09-10

發表迴響

%d 位部落客按了讚：