Skip to content

zeuikli/claude-code-workspace / .claude/skills/debug

系統性 debug 工作流:捕捉錯誤、分析日誌、關聯跨系統 pattern,產出有根因與修復驗證的報告。適用於 bug、test 失敗、生產異常。

FileKindSize
SKILL.mdskill md3.1 KB
---
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** — 確認修復有效,並排除引入新問題

## 快速診斷指令

```bash
# 查看最近哪些變更可能引起問題
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
```

## 日誌分析

```bash
# 最近的錯誤與上下文
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)

```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;
```

## 輸出格式

```markdown
## Debug Report

**Issue:** [一句話描述問題]
**Root Cause:** [實際根因]

### Evidence
- [找到的具體證據 1]
- [找到的具體證據 2]

### Fix
[程式碼或設定的最小修復]

### Verification
[如何確認修復有效:指令或測試]

### Prevention
[如何預防此問題再次發生]
```

## Gotcha

- **只做最小修復**:debug 不是重構,不要順手改不相關的程式碼
- **假設要有證據**:每個假設必須由工具呼叫驗證,不憑直覺
- **先跑相關測試**:不要跑全套測試套件,先跑最相關的一個測試確認方向
- **記錄 root cause**:修完後把根因和修復方式寫進 commit message,有助於日後 retro 分析
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 197kUpdated Claude CodeCodexVerifiedInstall