This resume is also available in English.

八、安全與 AI 協作第 5 / 7 篇 · 全部目錄

專欄 › 八、安全與 AI 協作 › 第 35 篇

用 AI 在專案裡 debug:從重現到修好

Debugging a Project with AI: From Reproduction to Fix

用 AI 代理在商店系統裡 debug 的一套紀律:把症狀寫清楚、先寫出會失敗的重現測試、餵給它證據而不是猜測、用 git bisect run 找出引入問題的 commit、一次驗證一個假設、修在根因,最後用測試、-race 與重複執行證明真的修好。

  • AI
  • Debugging
  • Go
這篇的步驟
  1. 這篇要解決什麼
  2. 第 1 步:把症狀寫清楚——預期、實際、範圍與頻率
  3. 第 2 步:先重現——讓代理寫出會失敗的測試,你確認它失敗的原因是對的
  4. 第 3 步:餵證據,不要餵猜測
  5. 第 4 步:用 git bisect run 讓代理自動找出引入問題的 commit
  6. 第 5 步:一次只驗證一個假設,並讓代理讀完整條路徑
  7. 第 6 步:修在根因,而且是在共用的程式碼裡——先找出所有呼叫者
  8. 第 7 步:證明修好了,而不是剛好好了
  9. 第 8 步:管理工作階段——分支、檢查點與上下文
  10. 第 9 步:留下回歸測試,並在 PR 裡寫下症狀、根因與證據
  11. 常見陷阱
  12. 重點整理
  13. 下一篇

上一篇〈用 AI 工作流自動化部署與排查問題〉處理的是正式環境的事故:告警響起、代理用唯讀權限收集證據、人決定先回滾。回滾讓服務恢復,但問題本身還留在程式碼裡;更多的 bug 根本不會走到正式環境,而是在開發、測試、壓力測試或同事試用時就被發現。這篇回到開發者自己的電腦上,談另一半的工作:在 repo 裡把一個 bug 從「有人說怪怪的」一路追到「有測試證明它修好了」,而且讓 AI 代理在過程中真的幫上忙。

這篇要解決什麼

把一段錯誤訊息貼給 AI、請它「幫我修」,是最直覺也最危險的用法。它通常會很快給出一個看起來合理的解釋和一段修改,測試也許還真的變綠了。問題在於:你不知道它修的是不是真正的原因,也不知道它是不是只是讓症狀暫時消失。AI 代理擅長的是讀大量程式碼、執行指令、整理輸出;它不擅長的是承認「我不知道」,以及分辨「說得通」和「是真的」。

這篇要建立的,是一套不依賴 AI 判斷力的 debug 流程。每一步都會產出可以被檢查的東西:一個會失敗的測試、一份工具產生的證據、一個附預測結果的實驗、一個 commit 雜湊、一個由紅轉綠的測試。AI 負責加速每一步,判斷依據則來自這些可以重跑的結果。

範例延續整個系列的商店系統:模組 example.com/shop,服務 api-gateway、order、payment、inventory,訂單是 Order{ID, UserID, Items, Total, Status},金額 Total 以分為單位存成 int64。文中會反覆用到三個示範用的 bug:

bug症狀難在哪裡
折扣後總額少一分少數訂單的 Total 和客服手算的差 1 分大部分訂單是對的,只有特定金額與折扣組合會錯
壓力測試下偶發超賣庫存 10 件,壓測後偶爾賣出 11 件單元測試全過,跑一百次才出現幾次
部署後 goroutine 變多order 服務的 goroutine 數量隨時間一直上升,記憶體跟著漲沒有錯誤訊息,只有一條慢慢往上的曲線

AI 代理以 Claude Code 為例,它的基本設定(CLAUDE.md、權限、hooks、plan 模式)已經在〈用 Claude Code 開發 Go 微服務:規則、權限與安全審查〉談過,這裡不重複,只談 debug 這件事本身。

1. 描述症狀 預期、實際、環境、頻率 2. 重現 失敗的測試,原因正確 3. 收集證據 堆疊、日誌、-race、pprof 4. 列出假設 每個附支持與反對證據 5. 一次測一個 預測結果,再跑實驗 被否定:回到假設清單 確認 6. 修根因 在共用程式碼,查所有呼叫者 7. 證明修好了 重現測試由紅轉綠 → 全套測試 → -race → 不穩定的測試跑 N 次 8. 留下回歸測試,在 PR 寫下症狀、根因、證據與驗證方式

圖:先描述、再重現、再收集證據;假設一次測一個,被否定就回到清單;確認後修根因,再用測試與重複執行證明修好,最後留下回歸測試與說明。

第 1 步:把症狀寫清楚——預期、實際、範圍與頻率

debug 的第一個產出不是程式碼,而是一段描述。這段描述要給 AI 看,也要給未來的自己與審查者看。描述得模糊,AI 就會用它最常見的猜測補上空白,而那個猜測未必適用於你的系統。

一份好的症狀描述至少回答四件事:

  1. 預期與實際。不是「金額錯了」,而是「訂單小計 1990 分、折扣 15%,預期 1692 分,實際 1691 分」。有具體數字,才有辦法寫成測試。
  2. 範圍。哪個服務、哪個端點、哪個版本開始;所有訂單都錯,還是只有某些組合錯;只有正式環境,還是本機也會。
  3. 頻率。每次都會、偶爾會(大約幾次中有一次),還是只在壓力或長時間執行之後才會。頻率決定了重現的方法:每次都會的寫成單元測試就好,偶發的要靠重複執行與競爭偵測器。
  4. 已經知道的事。最近改了什麼、已經排除了什麼、有哪些證據的連結。把「已經排除」寫下來,可以避免 AI 花時間重新走一遍你已經走過的路。

下面這張表是同一個問題的兩種描述方式:

模糊的描述可以拿來 debug 的描述
折扣算錯了小計 1990 分、折扣 15%,Total 是 1691,依需求四捨五入應為 1692;1999 分、15% 則正確
壓測會超賣inventory 的 Reserve,庫存 10、100 個並發請求,跑 100 次約有數次成功預留 11 件以上
order 好像有記憶體洩漏部署 v1.9.0 後,go_goroutines 每小時增加約固定數量,重啟後歸零再上升;v1.8.x 沒有這個現象

注意右欄裡沒有任何「原因」。描述症狀時刻意不寫猜測,是因為一旦你寫了「應該是浮點數的問題」,AI 很容易直接沿著這個方向找,找到一個符合的地方就停下來。猜測可以有,但要寫在「已經知道的事」底下,標明是猜測,並且請它也驗證其他可能。

提示:把症狀描述寫在 issue 或工單裡,而不是只寫在對話中。對話會結束、會被壓縮,工單會留下來,之後的 PR 也可以直接連過去。

第 2 步:先重現——讓代理寫出會失敗的測試,你確認它失敗的原因是對的

沒有重現,就沒有辦法證明修好。這一步的目標是一個會失敗的自動化測試,或至少是一個能穩定觸發問題的最小腳本。這是整個流程裡最值得花時間的一步,也是 AI 代理最能幫上忙的地方:它可以很快讀完相關程式碼、找出計算總額的路徑、寫出表格驅動測試、執行並貼出結果。

但你必須親自確認一件事:測試失敗的原因,正是你描述的那個症狀。一個測試會因為很多原因失敗:編譯錯誤、匯入路徑錯了、測試資料打錯、斷言寫反、測到了另一個函式。代理寫出一個失敗的測試,然後回報「已重現」,這句話本身不能證明任何事。你要看的是失敗訊息:它說的是 ApplyDiscount(1990, 15) = 1691, want 1692,還是 undefined: ApplyDiscount?

下面是一份交給代理的 debug 提示。它不是請它修,而是請它只做重現:

# 重現:折扣後總額少一分(issue #412)

## 症狀

- 預期:小計 1990 分、折扣 15%,`Total` = 1692(需求:以分為單位四捨五入,0.5 進位)。
- 實際:1691。小計 1999 分、折扣 15% 則正確(1699)。
- 範圍:`order` 建立訂單、`payment` 退款都會用到折扣計算;本機也能重現。

## 已經知道的事

- 計算在 `internal/pricing`,三週前有一次「統一折扣計算」的重構。
- 猜測(未驗證):可能是浮點數。請不要只驗證這個方向。

## 這一輪只做重現,不要修改任何非測試檔案

1. 讀 `internal/pricing` 與呼叫它的地方,說明計算路徑(檔案:行號)。
2. 在 `internal/pricing/discount_test.go` 寫表格驅動測試:上面兩筆、整除、0%、100%,
   以及你認為可能出錯的其他邊界,每一列註明預期值怎麼算出來。
3. 執行 `go test -run TestApplyDiscount -count=1 -v ./internal/pricing/`,貼出完整輸出。
4. 說明每一列失敗的原因;如果失敗訊息和症狀無關(例如編譯錯誤),先修測試本身。

最後一條「不要修改任何非測試檔案」很重要。重現階段就讓它動手修,等於跳過了「確認失敗原因」這一步;而且修和測混在同一個 diff 裡,你很難判斷測試是不是為了配合修改而寫的。

代理產出的測試大致如下:

// internal/pricing/discount_test.go
package pricing

import "testing"

// 規則(來自需求):折扣後的金額以「分」為單位四捨五入,0.5 分進位。
func TestApplyDiscount(t *testing.T) {
	tests := []struct {
		name    string
		cents   int64
		percent int64
		want    int64
	}{
		{"整除", 10000, 10, 9000},
		{"不打折", 1999, 0, 1999},
		{"全額折抵", 1999, 100, 0},
		{"小數未滿 0.5 捨去", 1999, 15, 1699}, // 1699.15
		{"小數剛好 0.5 進位", 1990, 15, 1692}, // 1691.5:回報的那張訂單
		{"浮點誤差", 2900, 30, 2030},        // 剛好 2030,不能變成 2029
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			if got := ApplyDiscount(tt.cents, tt.percent); got != tt.want {
				t.Errorf("ApplyDiscount(%d, %d) = %d, want %d", tt.cents, tt.percent, got, tt.want)
			}
		})
	}
}

執行結果:

$ go test -run TestApplyDiscount -count=1 -v ./internal/pricing/
=== RUN   TestApplyDiscount
=== RUN   TestApplyDiscount/整除
=== RUN   TestApplyDiscount/不打折
=== RUN   TestApplyDiscount/全額折抵
=== RUN   TestApplyDiscount/小數未滿_0.5_捨去
=== RUN   TestApplyDiscount/小數剛好_0.5_進位
    discount_test.go:24: ApplyDiscount(1990, 15) = 1691, want 1692
=== RUN   TestApplyDiscount/浮點誤差
    discount_test.go:24: ApplyDiscount(2900, 30) = 2029, want 2030
--- FAIL: TestApplyDiscount (0.00s)
    --- PASS: TestApplyDiscount/整除 (0.00s)
    --- PASS: TestApplyDiscount/不打折 (0.00s)
    --- PASS: TestApplyDiscount/全額折抵 (0.00s)
    --- PASS: TestApplyDiscount/小數未滿_0.5_捨去 (0.00s)
    --- FAIL: TestApplyDiscount/小數剛好_0.5_進位 (0.00s)
    --- FAIL: TestApplyDiscount/浮點誤差 (0.00s)
FAIL
FAIL	example.com/shop/internal/pricing	0.012s
FAIL

這份輸出值得仔細讀,因為它其實已經給了比原始回報更多的資訊。第一,回報的那一筆(1990、15%)確實失敗,而且失敗訊息就是症狀本身,重現成立。第二,代理多加的「浮點誤差」那一列也失敗了:2900 分打七折,精確值剛好是 2030,結果卻是 2029。這一列和「0.5 要進位」是兩個不同的現象:前者是捨入規則錯了,後者是運算本身就不精確。一個好的重現測試常常會這樣擴大你對問題的理解。

第三,你要親自檢查每一列的預期值。測試裡的 want 是代理算的,它也可能算錯;1990 × 0.85 = 1691.5,依需求進位到 1692,這一點要對照需求文件,而不是對照目前程式的輸出。預期值來自需求,不來自現有程式碼,這是重現測試和「描述現狀的測試」最大的差別。

偶發的問題無法用一個普通的單元測試重現,但原則一樣:寫一個能觸發它的測試,然後用重複執行把機率放大。超賣的例子可以寫成一個 100 個 goroutine 同時預留的測試,斷言「成功預留的數量不超過庫存」,再用 -count 重複跑(下一步會談旗標)。goroutine 洩漏則可以寫成「呼叫 N 次之後,runtime.NumGoroutine() 回到接近起始值」的測試,或直接在測試結束時檢查洩漏。〈併發常見問題:從資料競爭到超賣〉整理過這幾類問題的成因與修法,重現時可以直接參考那裡的測試寫法。

第 3 步:餵證據,不要餵猜測

有了重現,接下來是找原因。這一步最常見的錯誤,是把自己的猜測當成事實交給 AI:「我覺得是資料庫連線池的問題,幫我看一下」。AI 很樂意配合,它會在連線池的程式碼裡找到某個「可能有問題」的地方,然後給你一個說得通的故事。你得到的不是原因,而是你自己猜測的回聲。

比較好的做法是給它工具產生的證據,讓它從證據推論,而不是從你的猜測推論。下面是 Go 專案裡最常用的幾種證據,以及怎麼取得:

證據怎麼取得適合的問題
單一測試的完整輸出go test -run '^TestApplyDiscount$' -count=1 -v ./internal/pricing/計算錯誤、邏輯錯誤
panic 的完整堆疊測試輸出本身;需要所有 goroutine 時加 GOTRACEBACK=allnil 指標、索引越界
卡住時的所有 goroutinego test -timeout 30s ...:逾時會 panic 並印出所有 goroutine 的堆疊死結、等不到的 channel
資料競爭報告go test -race -count=50 -run TestReserveConcurrent ./internal/inventory/偶發的錯誤結果、超賣
順序相依go test -shuffle=on -count=1 ./...,失敗時會印出可以重現的種子單獨跑會過、一起跑會錯的測試
goroutine 與記憶體快照curl -s 'localhost:6060/debug/pprof/goroutine?debug=1';兩份快照用 go tool pprof -base before.pb.gz after.pb.gz 比較goroutine 洩漏、記憶體成長
同一次請求的日誌依 trace ID 篩選,見〈可觀測性:日誌、指標、追蹤〉跨服務的錯誤、時序問題
程式碼的變更歷史git log -p -S 'ApplyDiscount' -- internal/pricing/(找出新增或刪除這個字串的 commit)「以前是好的」

幾個旗標值得多說一句。-count=1 會停用測試結果快取,確保你看到的是這一次真的執行的結果,而不是上一次的快取;debug 時每次都加上它,可以避免「我明明改了,結果怎麼一樣」的困惑。-run 接的是正規表示式,TestApplyDiscount 也會匹配到 TestApplyDiscountMatchesExactRounding,要精確指定就寫成 '^TestApplyDiscount$'。-race 只能發現實際執行到的競爭,所以要搭配會觸發併發的測試與足夠的重複次數;它回報的兩段堆疊(一個寫入、一個讀取或寫入)就是最直接的證據。pprof 的細節在〈效能調校:pprof 與 benchmark〉,對 goroutine 洩漏來說,debug=1 會把相同堆疊的 goroutine 合併並附上數量,一眼就能看出「哪一行開出來的 goroutine 有好幾千個」。

證據(先篩選、去敏感) go test -run X -count=1 -v panic 堆疊、錯誤訊息全文 依 trace ID 篩選的日誌 -race 報告(兩段存取的堆疊) pprof:goroutine、heap git log -p、git bisect 結果 代理 讀完整條呼叫路徑 跑實驗、回報結果 假設 說明 支持的證據 反對的證據 確認用的實驗 預期結果 不送:正式資料、密鑰、個資、整份日誌 事實由工具產生,代理負責讀懂與串起來;說不出證據的假設不追。

圖:測試輸出、堆疊、依 trace ID 篩選的日誌、競爭報告、pprof 與 git 歷史由工具產生;代理把它們串起來,產出每一條都附有證據的假設。

讓代理自己執行這些指令,通常比你執行再貼給它更好:它看到的是完整輸出,而不是你挑過的片段,也能依結果決定下一個指令。但有兩條界線。

第一,不要把正式環境的資料直接交給它。正式環境的日誌裡有使用者的 Email、地址、訂單內容,可能還有不小心印出來的權杖。debug 需要的通常只是其中幾行:某個 trace ID 的那幾筆、錯誤訊息的格式、欄位的值。先篩選、再遮蔽,然後才交出去;能用測試資料重現的,就不要用真實資料。上一篇談事故排查時強調過同樣的事,開發時也一樣。

第二,證據要能重跑。代理說「我執行了測試,現在通過了」,你要看到它實際執行的指令與輸出;必要時自己再跑一次。把「我跑過了」當成需要證據的陳述,而不是事實。

第 4 步:用 git bisect run 讓代理自動找出引入問題的 commit

很多 bug 都有一個共同點:「以前是好的」。折扣計算在三週前的版本是對的,現在錯了;goroutine 數量在 v1.8.x 是平的,v1.9.0 開始往上爬。這時候與其讀程式碼猜原因,不如直接找出是哪一個 commit 引入的。找到那個 commit,問題的範圍就從整個 repo 縮小成一份 diff。

git bisect 用二分搜尋做這件事:你告訴它一個已知正常的版本與一個已知壞掉的版本,它每次切到中間的 commit,問你這個版本好不好,範圍就減半。一千個 commit 大約十輪就能找到。git bisect run 則把「好不好」交給一個腳本判斷:腳本結束碼 0 代表正常,1 到 127(125 除外)代表壞掉,125 代表這個 commit 無法判斷、跳過。

這正是適合交給代理的工作:機械、重複、結果明確。你只要確認兩件事:起點與終點真的分別是好與壞,以及判斷腳本測的是你要的東西。

# 1. 先把重現測試存到 repo 之外:舊的 commit 裡沒有這個檔案,每一輪都要複製進去
cp internal/pricing/discount_test.go "$TMPDIR/discount_repro_test.go"

# 2. 確認端點:v1.8.0 應該是好的、HEAD 應該是壞的(各跑一次,親眼看結果)
git stash -u   # 工作目錄要乾淨,bisect 才能切換 commit

# 3. 開始二分搜尋
git bisect start HEAD v1.8.0
git bisect run sh -c '
  cp "$TMPDIR/discount_repro_test.go" internal/pricing/discount_test.go
  # 編譯不過的 commit 無法判斷,回 125 跳過,而不是當成壞的
  if go test -count=1 -run "^$" ./internal/pricing/ >/dev/null 2>&1; then
    go test -count=1 -run "^TestApplyDiscount$" ./internal/pricing/
    rc=$?
  else
    rc=125
  fi
  # 還原這個 commit 原本的檔案,刪掉複製進來的測試,下一輪才切換得了
  git checkout -- internal/pricing/ && git clean -fq internal/pricing/
  exit $rc
'

# 4. 存下過程,回到原本的分支
git bisect log > "$TMPDIR/bisect-412.log"
git bisect reset
git stash pop

# 5. 看那個 commit 改了什麼
git show --stat <找到的 commit>
git show <找到的 commit> -- internal/pricing/

這段腳本有幾個容易出錯的地方,正好也是代理容易漏掉的:

  • 測試檔案要從外面帶進去。新寫的重現測試只存在於你的工作目錄,舊的 commit 裡沒有它。每一輪複製進去、測完再還原,否則切換 commit 時會和未追蹤的檔案衝突,或者測到的是舊版本自己的測試。
  • 編譯失敗不等於壞掉。舊版本的函式簽章可能不同,或者某個中間的 commit 本來就編譯不過。-run "^$" 會編譯測試但不執行任何測試,編譯不過就回 125 跳過;如果直接讓 go test 回 1,bisect 會把「編譯不過」誤判成「引入 bug」,找到一個完全無關的 commit。
  • 偶發的問題要先放大機率。超賣這類問題,一次測試可能剛好通過,bisect 就會把壞的 commit 標成好的,整個結果都錯。判斷腳本裡要用 -race -count=50 之類的重複次數,把「偶發」變成「幾乎必然」;代價是每一輪比較慢,但比起找錯 commit 便宜得多。
  • 端點要親自確認。如果 v1.8.0 其實也是壞的,bisect 會給你一個看起來很肯定、實際上沒有意義的答案。
git bisect run:每一輪測中間那個 commit,範圍減半 good bad 第 1 輪:正常 → 往右半找 第 2 輪:壞掉 → 往左 第 3 輪:找到第一個壞的 結束碼 0 這個 commit 正常 1–127(125 除外) 這個 commit 壞掉 結束碼 125 無法判斷,跳過 (例如編譯不過)

圖:每一輪測中間的 commit,依腳本的結束碼決定往左或往右;125 代表無法判斷,跳過這個 commit。

找到 commit 之後,把它的 diff 交給代理,請它解釋這次變更如何造成測試裡看到的結果。這時候它的解釋就有了錨點:不是「我覺得可能是這裡」,而是「這個 commit 把 (cents*(100-percent)+50)/100 改成了 int64(float64(cents)*(1-float64(percent)/100)),int64() 轉換會無條件捨去,而 0.7 在二進位浮點數裡無法精確表示」。這樣的解釋你可以逐字對照 diff 驗證。

提示:bisect 只適用於「有一個版本是好的」的問題。如果是新功能本身就寫錯,或問題來自資料與環境而不是程式碼,bisect 會在每一個 commit 都得到相同結果,這時就回到第 3 步,從證據找。

第 5 步:一次只驗證一個假設,並讓代理讀完整條路徑

有了證據,就可以開始列假設。好的假設有三個特徵:它能解釋所有觀察到的證據,而不只是其中一部分;它附帶一個可以執行的實驗;它事先說明實驗結果是什麼代表成立、什麼代表不成立。

以超賣為例,代理讀完 inventory 的程式碼與 -race 報告之後,可能列出這樣的清單:

假設支持的證據實驗預期
Reserve 先讀庫存、再另外寫入(先檢查後執行)-race 報告指向同一個欄位的讀與寫把讀與寫放在同一個鎖或同一個條件式 UPDATE 內,重跑 200 次若成立,超賣次數歸零
重試造成同一個預留被執行兩次日誌裡同一個 order_id 出現兩次 reserved用冪等鍵檢查重複;統計重複的比例若成立,超賣數量等於重複預留的數量
測試本身的計數有競爭無用 atomic.Int64 計數後重跑若成立,改完測試後就不再失敗

第三列看起來多餘,其實很重要:重現測試本身也可能有 bug。測試用一般的 int 在多個 goroutine 裡累加成功次數,競爭偵測器會指向測試而不是產品程式碼,結論就完全不同。

接著,一次只測一個。如果同時把三個地方都改了,超賣消失了,你不會知道是哪一個改動有效,也可能其中某個改動引入了新的問題。每次只做一個實驗,先寫下預測,再看結果;被否定的假設劃掉,把新的證據加進清單。這聽起來很慢,但比起「改了一堆、好像好了、兩週後又出現」快得多。

這個過程中,請代理讀完整條呼叫路徑,而不是只看錯誤訊息指向的那一行。超賣的根因常常不在 Reserve 本身,而在它被呼叫的方式:handler 在交易外先查庫存、訊息消費者在重新投遞時重複處理、或者 gateway 的重試讓同一個請求進來兩次(〈逾時、重試與熔斷〉、〈冪等與分散式鎖〉)。goroutine 洩漏也一樣:pprof 告訴你 goroutine 卡在哪一行,但真正的問題通常是「誰開了它、誰應該讓它結束」,例如某個 time.NewTicker 沒有 Stop、某個 goroutine 在等一個沒有人會關閉的 channel、或某個背景工作沒有接上服務的 context,在〈設定與優雅關閉〉設計的關閉流程裡被遺漏。

請代理讀路徑時,要求它回報檔案與行號,例如「internal/order/handler.go:88 呼叫 service.Create,internal/order/service.go:142 在交易開始前呼叫 inventory.Check」。這樣你可以自己打開那幾行確認,而不是相信一段摘要。大範圍的搜尋可以交給子代理:它在獨立的上下文裡讀檔、搜尋,只把結論交回來,主對話不會被大量的搜尋結果塞滿。

提示:要求代理在每個假設旁邊寫出「反對的證據」。一個只列支持證據的假設,往往是先有結論再找證據;能主動說出「這個假設解釋不了為什麼 1999 分是對的」,才代表它真的在比對證據。

第 6 步:修在根因,而且是在共用的程式碼裡——先找出所有呼叫者

確認了原因,才開始修。修的位置有兩種選擇:在出問題的地方補一個例外處理,或在造成問題的地方把它改對。前者是修症狀,後者是修根因。

以折扣為例,修症狀的寫法可能是在 order 建立訂單時多加一行 +1 的修正,或在算完之後用 math.Round 再處理一次。測試會過,但 payment 的退款也呼叫同一個 ApplyDiscount,它還是錯的;而且下一個呼叫它的新功能也會錯。AI 代理特別容易給出這種修法,因為它的上下文裡只有那個失敗的測試,最短的路徑就是讓那個測試通過。

所以在動手之前,先找出所有呼叫者。可以讓代理用 grep -rn 'ApplyDiscount(' --include='*.go' . 搜尋,或用 gopls 的「尋找參考」功能找出所有引用(包括透過介面的呼叫),然後列成一張表:每個呼叫者在哪裡、傳進去的參數從哪裡來、修正後它的行為會不會改變。這張表同時也是 PR 說明的一部分:審查者需要知道這次修改影響了哪些地方。

// internal/pricing/discount.go
package pricing

// ApplyDiscount 回傳打 percent(0–100)折扣後的金額(分),以分為單位四捨五入,0.5 進位。
// 只用整數運算;cents*(100-percent) 在 cents 小於 9e16 時不會溢位。
// 金額與百分比的範圍在建立訂單與折扣碼時就驗證過,這裡不重複檢查。
func ApplyDiscount(cents, percent int64) int64 {
	return (cents*(100-percent) + 50) / 100
}

這個修正刻意保持函式簽章不變:所有呼叫者都不用改,第 2 步的重現測試也原封不動地變成回歸測試。它也刻意沒有「順便」改別的東西,例如把百分比改成 float64、加一個捨入模式的參數、或重構整個 pricing 套件。這些改動也許有價值,但它們應該是另一個 PR;混在 bug 修正裡,會讓審查者無法分辨哪一行是修正、哪一行是重構,也讓之後的 bisect 更難用。金額計算為什麼要用整數分、什麼時候需要 math/big 或 decimal,在〈Go 處理金額:整數分、decimal、幣別、四捨五入與分攤〉有完整的討論。

修根因時要特別注意 AI 的兩個習慣。第一,它可能使用不存在的 API:一個看起來很合理的 math.RoundHalfUp、某個套件裡沒有的選項、或某個函式庫舊版本才有的方法。編譯器會擋下大部分,但不會擋下「存在、卻不是你以為的行為」,例如 math.Round 是遠離零的四捨五入,math.RoundToEven 是銀行家捨入,兩者對 .5 的處理不同。凡是它引用的標準函式庫或套件行為,都要對照文件或用一個小測試確認。第二,它可能過度修改:為了修一個捨入問題改了二十個檔案。diff 越大,審查越難,藏在裡面的意外就越多。要求它「只修改根因所在的函式與必要的呼叫者,其他改動另列建議」。

第 7 步:證明修好了,而不是剛好好了

測試變綠,不代表問題解決了。這一步要排除三種「剛好好了」的情況:修改只對測試裡的那幾個數字有效、偶發的問題這一次剛好沒出現、以及測試本身被改到不會失敗。

用更大的範圍驗證,而不只是那幾筆。回報的那張訂單只是一個樣本。對於純計算的函式,可以用一個獨立、明顯正確的方法算出精確值,然後在一整個範圍內逐一比對:

// internal/pricing/discount_exact_test.go
package pricing

import (
	"math/big"
	"testing"
)

// 用 math/big 的有理數算出精確值再四捨五入,和 ApplyDiscount 逐一比對。
// 不只驗證回報的那一筆,而是一整個範圍,避免「剛好修好那個數字」。
func TestApplyDiscountMatchesExactRounding(t *testing.T) {
	half := big.NewRat(1, 2)
	for cents := int64(0); cents <= 20000; cents++ {
		for percent := int64(0); percent <= 100; percent += 5 {
			exact := new(big.Rat).SetFrac64(cents*(100-percent), 100)
			exact.Add(exact, half)
			want := new(big.Int).Quo(exact.Num(), exact.Denom()).Int64() // 非負數,Quo 即無條件捨去

			if got := ApplyDiscount(cents, percent); got != want {
				t.Fatalf("ApplyDiscount(%d, %d) = %d, want %d", cents, percent, got, want)
			}
		}
	}
}

這個測試在原本有 bug 的版本上,第一組就失敗了:ApplyDiscount(1, 5) 應該是 1(0.95 四捨五入),浮點版本卻得到 0。換句話說,原本的 bug 影響的不只是回報的那幾張訂單,而是大量的小額組合。這種「比對參考實作」的測試寫起來不難,卻比手寫十個案例更能證明修正是全面的。對於更複雜的輸入,Go 內建的模糊測試(func FuzzXxx(f *testing.F))也能用同樣的思路,讓工具產生輸入、和參考實作比對。

確認回歸測試真的會抓到這個 bug。把修正暫時還原(git stash 只收起實作的修改,或請代理把那一行改回去),重跑測試,確認它失敗;再把修正放回來,確認它通過。這個「先紅、後綠、再紅、再綠」的檢查只要一分鐘,卻能證明測試和修正之間真的有因果關係,而不是測試在任何版本上都會過。

偶發的問題要重複執行。超賣這類問題,修正之後跑一次通過幾乎沒有意義。要用和重現時相同、甚至更高的次數去跑,例如 go test -race -count=200 -run TestReserveConcurrent ./internal/inventory/。如果修正前 200 次中有數次失敗,修正後 200 次全部通過,這才是有說服力的證據;在 PR 裡寫下修正前後的次數,審查者就能自己判斷。同樣的道理,goroutine 洩漏的修正要看的是一段時間內的曲線或兩份 pprof 快照的差異,而不是「看起來沒問題了」。

最後跑完整的檢查。go vet ./...、go test -race ./...,以及專案在 CI 上會跑的其他檢查。修正共用程式碼時,失敗常常出現在你沒想到的地方:某個別的測試原本依賴錯誤的行為,或某個 golden 檔案裡存著錯誤的金額。這種時候要停下來判斷:那個測試是對的而修正有問題,還是那個測試本來就把錯誤當成預期?後者要和需求確認後再改,並在 PR 裡說明。

提示:留意代理是否為了讓測試通過而修改了測試的預期值、加上 t.Skip、刪掉某一列、或放寬斷言。在 PR 審查時,先看 _test.go 的 diff:回歸測試只應該新增,不應該被弱化。〈測試:表格驅動、httptest、整合測試〉裡談過,測試的價值在於它代表需求,而不是代表程式目前的行為。

第 8 步:管理工作階段——分支、檢查點與上下文

debug 常常是一段很長的對話:讀檔、跑指令、試一個方向、放棄、換一個方向。這種工作方式有幾個專屬的風險,值得用工具的功能處理。

在分支或 worktree 上工作。debug 時會有很多實驗性的修改,有的要留、有的要丟。把它們放在獨立的分支,主分支永遠是乾淨的;最後要提交的,是整理過的修正與測試,而不是實驗的過程。

用檢查點退回,但知道它的限制。Claude Code 會在你每次送出提示時自動建立檢查點,用 /rewind(或在輸入框為空時按兩次 Esc)可以把程式碼、對話或兩者退回到之前的某個時間點。這很適合「這個方向不對,回到剛才」的情況。但依官方文件,檢查點追蹤的是它用檔案編輯工具做的修改:只被 Bash 指令改過的檔案不會被追蹤,子代理的修改通常也不會被還原,它也不是版本控制的替代品。debug 時常會執行產生檔案、改資料的指令,所以真正可靠的退路仍然是 git:實驗前先 commit 一個乾淨的狀態,需要時直接比對或還原。

控制上下文。一段很長的 debug 對話會塞滿早期的錯誤假設、被否定的實驗與大量的指令輸出,代理有時會被這些舊資訊誤導,回頭去用已經被排除的解釋。幾個做法:把確認過的事實與被否定的假設寫回 issue,需要時開一個新的工作階段,只帶著這份整理過的摘要繼續;大範圍的搜尋交給子代理;第 5 步的假設表放在檔案裡,而不是只存在對話中。

先計畫,再修改。當原因已經確認、修正會牽涉好幾個檔案時,用 plan 模式讓它先列出要改哪些地方、怎麼驗證,你確認之後才開始修改。這和第 6 步的「先找出所有呼叫者」是同一件事:先看清楚範圍,再動手。

第 9 步:留下回歸測試,並在 PR 裡寫下症狀、根因與證據

修好之後,這次 debug 的成果要變成兩樣會留下來的東西。

第一是回歸測試。第 2 步的重現測試與第 7 步的參考實作比對,都應該進入 repo、在 CI 上執行。測試的名稱與註解要寫清楚它在守什麼:「小數剛好 0.5 進位:回報的那張訂單」比「case 5」有用得多,因為下一個讓它失敗的人,會從這裡開始理解為什麼。偶發的問題,可以在 CI 上用較少的重複次數執行,另外在排程工作裡用較多的次數執行。

第二是PR 說明。一個 bug 修正的 PR,至少要讓審查者在幾分鐘內回答這些問題:

  • 症狀:預期、實際、範圍,連到原本的 issue。
  • 根因:一兩句話說明為什麼會錯,附上引入問題的 commit(如果有用 bisect 找到)與相關的檔案:行號。
  • 修正:改了什麼、為什麼改在這裡;受影響的呼叫者清單,以及它們的行為是否改變。
  • 證據:修正前測試失敗、修正後通過的輸出;偶發問題的重複次數與結果;go test -race ./... 的結果。
  • 沒有做的事:例如「沒有處理歷史訂單的金額,需要另外評估是否回補」。這一條很容易被忽略,卻常常是最重要的後續工作:已經用錯誤金額建立的訂單與退款,需要和財務或客服確認如何處理。
  • AI 協助:哪些部分由代理產生、你如何驗證。〈AI 工作流接進團隊流程:PR 審查、CI 與人工把關〉談過這個欄位的用意:不是為了追究責任,而是讓審查者知道該把注意力放在哪裡。

這份說明也可以請代理起草,因為它手上有完整的過程。但「根因」與「證據」兩欄要由你確認:它們必須對得回實際執行過的指令與輸出,而不是代理對過程的回憶。

常見陷阱

說得通但錯誤的解釋。AI 最大的風險不是答不出來,而是很有自信地給出一個合理、但不是真的解釋。對策是每一個解釋都要對回證據:哪一行程式碼、哪一段輸出、哪一個 commit。對不回去的,只是假設。

修改測試讓它通過。改預期值、加 t.Skip、刪掉失敗的那一列、把 == 改成「誤差在 1 以內」。這些修改可能很隱密,夾在一大份 diff 裡。審查時先看測試檔案的 diff。

修症狀而不是根因。加一個 recover() 吞掉 panic、加一個 time.Sleep 讓競爭不容易出現、加一次重試讓偶發的錯誤消失、在某一個呼叫者那裡補一行修正。症狀消失了,問題還在,而且更難發現。

幻想出來的 API。不存在的函式、不存在的旗標、某個版本才有的行為。編譯與文件是最好的檢查;對工具旗標也一樣,不確定時先跑 go help testflag 或看官方文件。

一大份沒有人仔細看的 diff。「順便」重構、改格式、升級相依。bug 修正越小越好,其他改動另外開 PR。

把正式環境資料或密鑰貼進提示詞。日誌、資料庫匯出、設定檔、環境變數裡的內容都可能包含個資與權杖。先篩選與遮蔽,能用測試資料重現就不用真實資料;不小心貼了密鑰,就當作外洩,立即輪替。

偶發問題跑一次就宣布修好。沒有和修正前相同等級的重複次數,「通過」沒有意義。bisect 時也一樣,判斷腳本裡沒有放大機率,就會找錯 commit。

相信「我已經跑過測試了」。要看到實際的指令與輸出,必要時自己再跑一次;尤其要確認用了 -count=1,而不是看到快取的結果。

跳過重現直接修。沒有會失敗的測試,就沒有辦法證明修好,也沒有辦法防止它回來。

重點整理

  • 先寫症狀:預期、實際、範圍、頻率與已經排除的事,不要把猜測寫成事實。
  • 先重現:讓代理寫出會失敗的測試,你親自確認失敗訊息就是症狀本身,預期值來自需求而不是現有程式。
  • 餵證據:go test -run '^X$' -count=1 -v、-race -count=N、-shuffle=on、-timeout 印出的堆疊、pprof 快照比較、依 trace ID 篩選的日誌、git log -p -S;正式資料與密鑰先篩選遮蔽。
  • 「以前是好的」就用 git bisect run:重現測試從 repo 外帶入,編譯不過回 125,偶發問題先放大機率,端點親自確認。
  • 假設要能解釋所有證據、附帶實驗與預期結果;一次只測一個,讓代理回報完整呼叫路徑的檔案與行號。
  • 修在根因所在的共用程式碼,先列出所有呼叫者;保持修改小,重構另開 PR,引用的 API 行為要查證。
  • 用參考實作比對、修正前後的紅綠檢查、和重現時相同等級的重複次數,以及完整的 go test -race ./... 證明修好。
  • 用分支與 git 當作可靠的退路,檢查點只是方便的輔助;長對話要整理成摘要再繼續。
  • 回歸測試進 CI,PR 寫明症狀、根因、修正、證據、沒有處理的後續與 AI 協助的部分。

下一篇

debug 是找出程式「沒有照預期運作」的地方;安全問題則常常是程式「完全照寫的運作」,只是寫的東西允許了不該允許的事。下一篇〈用 AI 做安全性檢查:威脅建模、追蹤輸入與驗證發現〉沿用同一套「要證據、要能重跑」的紀律,談怎麼讓 AI 協助找出商店系統的安全問題,同時不被它的誤判牽著走。