debug

name	debug
description	系統性 debug 工作流：捕捉錯誤、分析日誌、關聯跨系統 pattern，產出有根因與修復驗證的報告。適用於 bug、test 失敗、生產異常。
disable-model-invocation	true
context	fork

Debug — 系統性除錯

觸發條件

• 出現錯誤訊息或 stack trace
• 測試失敗
• 程式行為非預期
• 生產環境出現異常（日誌分析、error spike）

除錯流程（6 步驟）

1. Capture — 取得完整錯誤訊息、stack trace、重現步驟
2. Isolate — 縮小故障範圍（模組、函式、時間點）
3. Hypothesize — 形成 2-3 個可能根因假設
4. Test — 用證據驗證假設（不要憑感覺猜）
5. Fix — 實作最小修復（不要順手清理無關的程式碼）
6. 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 分析