如何打造一個能自動修復 Bug 的 Claude Code Agent（內含完整設定教學）

Claude 寫程式，測試失敗了，然後把錯誤丟回給你處理。

一個自修復的 Agent 不會這樣：它會閱讀自己的失敗、修補原因，然後重新執行，直到全部通過。

設定一次之後，你就不用再當 Agent 的免費除錯工了。

以下是完整的設定方法 👇

在深入之前，我每天在我的 Telegram 頻道分享 AI 和極速編碼的筆記：https://t.me/zodchixquant🧠

為什麼一次實作不夠

預設情況下，Claude 只會執行一次任務。測試失敗了，它會回報錯誤然後等待。你讀取錯誤、貼回去、叫它再試一次。你在做除錯，它只是在打字。

自修復的 Agent 扭轉了這種局面。它會閱讀自己的失敗、判斷錯誤的類型、修復成因、然後重新執行，就像除錯器思考的方式一樣。只有當它通過或真的卡住時，你才會介入。

檔案 1：修復指令

這是你實際上會執行的迴圈。放到 .claude/commands/fix.md 中：

1---
2description: 執行一個任務並自我修復直到所有測試通過
3argument-hint: <task>
4allowed-tools: Read, Write, Edit, Glob, Grep, Bash
5model: sonnet
6---
7
8任務：$ARGUMENTS
9
10迴圈：
111. 實作任務。
122. 執行測試套件：`npm test`（或 pytest、cargo test）。
133. 如果所有測試通過：停止並顯示結果。
144. 如果測試失敗：分類錯誤類型、指出根本原因、
15   修復那個原因，然後回到步驟 2。
165. 上限為 5 次嘗試。每次嘗試時宣告嘗試次數。
17
18先分類再修復的順序是關鍵。每一輪都要先診斷再編輯。
19永遠不要為了通過而削弱測試，要修復程式碼。

你輸入 /fix add pagination to the users endpoint，然後 Agent 就會撰寫、測試、並自我修復，直到整個套件變綠。

檔案 2：自動檢查鉤子

指令是按需執行。這個鉤子讓每次編輯後都能自動自我檢查。

加入到 .claude/settings.json：

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Write|Edit",
6        "hooks": [
7          { "type": "command", "command": "npm test --silent 2>&1 | tail -5 || echo 'TESTS FAILING, fix before continuing'" }
8        ]
9      }
10    ]
11  }
12}

現在每次 Claude 編輯檔案後，測試就會執行，結果會回到它的視野中。

失敗會立即顯示，所以 Agent 在同一個流程中修復它，而不是繼續前進並在壞掉的程式碼上疊加更多變更。

檔案 3：教它讀懂錯誤

這個檔案是真正的除錯器和亂猜者的分水嶺。大部分 Agent 看到「測試失敗」就開始隨機編輯。

好的 Agent 會先讀取錯誤類型，因為每種類型指向不同的原因。把它放到 CLAUDE.md 中：

1## 如何在修復前讀懂失敗
2
3永遠先指出錯誤類型。每一種都有不同的意義：
4
5- 斷言失敗（預期 X，得到 Y）：邏輯有問題。
6  從斷言往回追蹤到值被建立的地方。
7  修正計算，而不是測試的期望值。
8
9- 類型錯誤 / undefined is not a function：型別不符。
10  某個東西是 null，或錯誤的型別進入了這行程式碼。
11  找出該值的來源，在那裡防護或修正。
12
13- 超時 / 卡住：遺漏了 await，或 Promise 永遠不會解析。
14  尋找沒有 await 的非同步呼叫，或一個永遠不會翻轉的條件。
15
16- 匯入 / 找不到模組：路徑或依賴問題，不是邏輯問題。
17  修正路徑或安裝，不要碰使用它的程式碼。
18
19- 不穩定（有時通過有時失敗）：共享狀態或時序問題，永遠不是隨機的。
20  尋找依賴順序的測試或未模擬的時間/網路。
21
22規則：在編輯之前，大聲說出類型和一整句的根本原因。
23如果你說不出原因，那就是在亂猜。停下來。

類型錯誤和斷言失敗需要相反的做法：一個是上游的資料型別問題，另一個是該處的錯誤邏輯。先分類，Agent 就能修復正確的問題。

跳過分類，它就會隨機編輯直到紅色消失，這樣你得到的是雖然綠燈卻悄悄壞掉的測試套件。

你實際上會看到的

你輸入一行：

1/fix 日期格式化函式傳回錯誤的時區

然後它會自己運作：

1嘗試 1
2  執行測試 → 失敗
3  類型：斷言（預期 5，得到 11）
4  原因：分頁大小未套用到查詢中
5  修復了 LIMIT 子句
6
7嘗試 2
8  執行測試 → 失敗
9  類型：類型錯誤（offset 是 undefined）
10  原因：第 1 頁沒有傳入 offset，預設值設定錯誤
11  加入了 offset = (page-1)*size
12
13嘗試 3
14  執行測試 → 全部通過（7/7）
15
163 次嘗試後修復完成。要檢視差異嗎？

你完全不需要貼回錯誤。它讀取自己的失敗、指出每個原因、並持續修復直到套件通過。

常見錯誤

先修復再診斷。 最常見的錯誤。一個在指出錯誤類型之前就開始編輯的 Agent 是在亂猜，而亂猜只能靠運氣讓紅燈變綠，不是靠修復。先分類的規則是唯一的防禦。

對待每個錯誤都一樣。 超時和斷言失敗毫無共同點，但沒有錯誤類型指南的 Agent 把兩者都當作「有問題」然後編輯最近的程式碼行。你一半的修復會落在錯誤的檔案裡。

修補症狀。 用 try/catch 包住會拋出錯誤的呼叫讓測試通過，但留下了錯誤。協定禁止為了這個原因而靜默錯誤。

讓它削弱測試。 允許編輯測試的 Agent 最終會刪除那個失敗的測試來達到綠燈。一個什麼都證明不了的綠燈套組是最糟的結果，所以這個規則是沒有商量餘地的。

5 分鐘設定

2 分鐘：建立 .claude/commands/fix.md

1 分鐘：將 PostToolUse 鉤子加入 settings.json

1 分鐘：將自我除錯協定加入 CLAUDE.md

1 分鐘：對一個已知的錯誤執行 /fix，看著它一次一次地處理原因。

你不再需要一個轉傳錯誤的人類。Agent 讀取自己的紅色錯誤並修復直到變綠。它不是變聰明了，只是不再把問題丟回給你。

謝謝閱讀！

我每天在我的 Telegram 頻道分享 AI、金融和極速編碼的筆記：https://t.me/zodchixquant