debug
系統性 debug 工作流：捕捉錯誤、分析日誌、關聯跨系統 pattern，產出有根因與修復驗證的報告。適用於 bug、test 失敗、生產異常。
SKILL.md.claude/skills/debug/SKILL.md
GitHubDebug — 系統性除錯
觸發條件
- 出現錯誤訊息或 stack trace
- 測試失敗
- 程式行為非預期
- 生產環境出現異常（日誌分析、error spike）
除錯流程（6 步驟）
- Capture — 取得完整錯誤訊息、stack trace、重現步驟
- Isolate — 縮小故障範圍（模組、函式、時間點）
- Hypothesize — 形成 2-3 個可能根因假設
- Test — 用證據驗證假設（不要憑感覺猜）
- Fix — 實作最小修復（不要順手清理無關的程式碼）
- Verify — 確認修復有效，並排除引入新問題
快速診斷指令
# 查看最近哪些變更可能引起問題
git log --oneline -10
git diff HEAD~3
# 搜尋日誌中的錯誤模式
grep -rn "error\|Error\|ERROR" logs/ 2>/dev/null | tail -20
# 執行測試並捕捉輸出
npm test 2>&1 | tail -50 # Node.js
pytest -x --tb=short 2>&1 # Python
cargo test 2>&1 | tail -50 # Rust
go test ./... 2>&1 # Go
日誌分析
# 最近的錯誤與上下文
grep -B 5 -A 10 "ERROR" /var/log/app.log
# 統計錯誤類型頻率
grep -oE "Error: [^:]*" app.log | sort | uniq -c | sort -rn
# 某時段的錯誤
awk '/2026-04-18 14:/ && /ERROR/' app.log
# 找出高頻錯誤
grep "ERROR" app.log | cut -d']' -f2 | sort | uniq -c | sort -rn | head -20
# 錯誤 spike 分析
grep "ERROR" app.log | cut -d' ' -f1-2 | uniq -c | sort -rn
常見 Error Pattern
| Pattern | 指向 | 行動 |
|---|---|---|
| NullPointer / undefined | 缺少 null check | 加入防衛性驗證 |
| Timeout | 依賴服務慢 | 加 timeout + retry |
| Connection refused | 服務未啟動 | 檢查 health endpoint |
| OOM | 記憶體洩漏 | 用 profiler 找洩漏點 |
| Rate limit | 請求過多 | 加 backoff + 佇列 |
跨系統關聯查詢（SQL）
-- 某 endpoint 的錯誤頻率
SELECT endpoint, count(*) as errors
FROM logs
WHERE level = 'ERROR' AND time > NOW() - INTERVAL '1 hour'
GROUP BY endpoint ORDER BY errors DESC;
-- 用 request_id 跨服務追蹤
SELECT service, message, time
FROM logs
WHERE request_id = 'req-xxxxx'
ORDER BY time;
輸出格式
## Debug Report
**Issue:** [一句話描述問題]
**Root Cause:** [實際根因]
### Evidence
- [找到的具體證據 1]
- [找到的具體證據 2]
### Fix
[程式碼或設定的最小修復]
### Verification
[如何確認修復有效：指令或測試]
### Prevention
[如何預防此問題再次發生]
Gotcha
- 只做最小修復：debug 不是重構，不要順手改不相關的程式碼
- 假設要有證據：每個假設必須由工具呼叫驗證，不憑直覺
- 先跑相關測試：不要跑全套測試套件，先跑最相關的一個測試確認方向
- 記錄 root cause：修完後把根因和修復方式寫進 commit message，有助於日後 retro 分析