Claude Code 幫你查卡住嘅 bug：記錄、二分搜尋同最小重現

改咗幾次都唔得，先停低整理證據

同一個 bug 試咗幾個修正仍然出現，再加一段長 prompt 未必有幫助。先記低現象、預期結果、最後正常版本、最近改動，同已經試過但冇用嘅方法。Claude 先知道唔應該重複邊條路。

# 調查記錄
現象：GET /api/orders 回傳 500。
預期：回傳 200 及訂單清單。
錯誤：undefined is not iterable。
最後正常版本：[填寫已驗證嘅 commit]
最近改動：[填寫]
已試方法：重新啟動無效；清除快取無效。
重現步驟：[填寫]

以下三種方法各有用途，唔需要每次全部做。

方法一：由記錄分辨假設

錯誤堆疊指出失敗位置，但起因可能喺更早嘅輸入、資料轉換或者非同步操作。先截取同一個請求前後嘅相關記錄，保留時間同追蹤 ID，去除密鑰、個人資料同無關雜訊。

先讀 .debug-notes.md，同指定錯誤記錄及相關程式。

列出最多三個可能原因，每個附上支持同反對證據。再提出一個最能分辨佢哋嘅檢查：要睇邊個檔案、變數或者事件次序。

暫時唔修正程式。如果現有證據不足，清楚講仲欠乜。新增記錄只顯示必要資料，唔好輸出完整請求、token 或客戶資料。

你可以請 Claude 加診斷記錄，但每個記錄都應該回答一條問題。無目的印晒所有變數，會令資料更難睇，亦可能改變問題出現嘅時序。

方法二：用 git bisect 搵引入問題嘅提交

當你有一個已確認正常嘅版本，同一個確定出錯嘅版本，可以用 Git 二分搜尋。先保存目前工作，最好喺獨立 checkout 調查；過程會切換版本，唔好同其他人共用修改中嘅工作目錄。

git bisect start
git bisect bad HEAD
git bisect good GOOD_COMMIT
git bisect run ./check-bug.sh
git bisect reset

將 GOOD_COMMIT 換成實際已測過嘅提交。最後 reset 係結束 bisect、返回原先版本，唔係叫你清除未提交改動。

根據調查記錄寫 check-bug.sh，先畀我審閱。

回傳 0：請求成功，且內容符合預期。
回傳 1：重現指定錯誤，而唔係任何 500 都算。
回傳 125：依賴裝唔到、服務起唔到，或者結果無法判斷。

用獨立連接埠、啟動等待同超時；結束時只清理自己啟動嘅程序。按每個提交嘅鎖定檔安裝，唔好更新依賴。先喺已知好、壞版本各試一次腳本。

好多中間提交都要跳過，或者問題時有時無，bisect 可能無法唯一定位。唔好將輸出嘅第一個候選提交直接當成根本原因，要讀差異再驗證。Git 嘅退出碼規則可查官方 bisect 文件。

方法三：保留錯誤，逐步縮細重現例子

複製一份可控制嘅測試環境，每次只移走一項無關內容，再重跑。目標唔係硬縮到兩個檔案，而係保留真正需要嘅設定、依賴同事件次序。

呢個資料夾可以用 [指令] 重現 [現象]。請先實際重現，再讀相關檔案。

解釋出錯位置前後嘅資料流，指出邊個假設唔成立。提出最小修正同一個會喺舊程式失敗、修正後通過嘅測試。

如果重現唔到或者仲欠外部條件，直接列出，唔好猜一個修正當完成。

移走某個依賴後錯誤消失，本身就係線索。記低呢一步，唔好將已經正常嘅版本交畀 Claude，仍要求佢一定搵到 bug。

間歇同正式環境問題點處理

並行問題要保留請求 ID、事件順序同必要時間資訊，盡量用可控制嘅測試重現交錯次序。加記錄之後問題消失，只能支持時序相關嘅可能性，唔足以證明係某一類競態。

只喺正式環境出現時，比對版本、時區、設定名稱、資料形狀同負載；唔好為咗比較而輸出環境變數真值。先用已去識別化嘅資料重建測試，避免直接喺正式資料上試修正。

修正後點先算完成

保留一個防止同類問題再次出現嘅測試，檢查受影響呼叫端，再跑專案要求嘅相關測試同建置。將已證實原因、改動、驗證結果同未覆蓋情況寫返調查記錄。

Claude 嘅解釋可以好順，但完成依據應該係同一組重現步驟喺修正前失敗、修正後通過，而唔係佢話「應該搞掂」。