首頁 全景圖 學習路線 ← 技能主頁 systematic-debugging

CREATION-LOG

systematic-debugging · 附屬文件

Creation Log: Systematic Debugging Skill

建立日誌：系統化除錯技能

Reference example of extracting, structuring, and bulletproofing a critical skill.

萃取、結構化並加固一個關鍵技能的參考範例。

Source Material

原始素材

Extracted debugging framework from ~/.claude/CLAUDE.md: - 4-phase systematic process (Investigation → Pattern Analysis → Hypothesis → Implementation) - Core mandate: ALWAYS find root cause, NEVER fix symptoms - Rules designed to resist time pressure and rationalization

從 ~/.claude/CLAUDE.md 萃取除錯框架： - 四階段系統化流程（調查 → 模式分析 → 假設 → 實作） - 核心使命：一律找出根因，絕對不修症狀 - 設計成能抵抗時間壓力與合理化藉口的規則

Extraction Decisions

萃取決策

What to include: - Complete 4-phase framework with all rules - Anti-shortcuts ("NEVER fix symptom", "STOP and re-analyze") - Pressure-resistant language ("even if faster", "even if I seem in a hurry") - Concrete steps for each phase

要納入什麼： - 完整的四階段框架與所有規則 - 反抄捷徑（「絕對不修症狀」「停下來重新分析」） - 抗壓語言（「即使更快」「即使我看起來很趕」） - 每個階段的具體步驟

What to leave out: - Project-specific context - Repetitive variations of same rule - Narrative explanations (condensed to principles)

要排除什麼： - 專案特定脈絡 - 同一規則的重複變體 - 敘事性說明（濃縮成原則）

Structure Following skill-creation/SKILL.md

遵循 skill-creation/SKILL.md 的結構

  1. Rich when_to_use - Included symptoms and anti-patterns
  2. Type: technique - Concrete process with steps
  3. Keywords - "root cause", "symptom", "workaround", "debugging", "investigation"
  4. Flowchart - Decision point for "fix failed" → re-analyze vs add more fixes
  5. Phase-by-phase breakdown - Scannable checklist format
  6. Anti-patterns section - What NOT to do (critical for this skill)
  1. 豐富的 when_to_use —— 包含症狀與反模式
  2. Type: technique —— 有步驟的具體流程
  3. Keywords —— 「root cause」「symptom」「workaround」「debugging」「investigation」
  4. 流程圖 —— 「修復失敗」的決策點：重新分析 vs 再加修復
  5. 逐階段拆解 —— 可快速掃讀的檢查清單格式
  6. 反模式章節 —— 什麼「不該」做（對這個技能至關重要）

Bulletproofing Elements

加固要素

Framework designed to resist rationalization under pressure:

框架設計成能在壓力下抵抗合理化：

Language Choices

  • "ALWAYS" / "NEVER" (not "should" / "try to")
  • "even if faster" / "even if I seem in a hurry"
  • "STOP and re-analyze" (explicit pause)
  • "Don't skip past" (catches the actual behavior)

語言選擇

  • 「ALWAYS」/「NEVER」（不用「should」/「try to」）
  • 「即使更快」/「即使我看起來很趕」
  • 「停下來重新分析」（明確的暫停）
  • 「不要跳過」（攔截實際的行為）

Structural Defenses

  • Phase 1 required - Can't skip to implementation
  • Single hypothesis rule - Forces thinking, prevents shotgun fixes
  • Explicit failure mode - "IF your first fix doesn't work" with mandatory action
  • Anti-patterns section - Shows exactly what shortcuts look like

結構性防禦

  • 第一階段為必備 —— 不能直接跳到實作
  • 單一假設規則 —— 強迫思考，防止亂槍打鳥
  • 明確的失敗模式 ——「如果第一次修復沒有效」並附強制動作
  • 反模式章節 —— 具體呈現抄捷徑長什麼樣

Redundancy

  • Root cause mandate in overview + when_to_use + Phase 1 + implementation rules
  • "NEVER fix symptom" appears 4 times in different contexts
  • Each phase has explicit "don't skip" guidance

冗餘

  • 根因使命同時出現在概述、when_to_use、第一階段與實作規則
  • 「絕對不修症狀」在四個不同脈絡各出現一次
  • 每個階段都有明確的「不可跳過」指引

Testing Approach

測試方式

Created 4 validation tests following skills/meta/testing-skills-with-subagents:

依照 skills/meta/testing-skills-with-subagents 建立 4 個驗證測試：

Test 1: Academic Context (No Pressure)

  • Simple bug, no time pressure
  • Result: Perfect compliance, complete investigation

測試 1：學術情境（無壓力）

  • 簡單 bug，無時間壓力
  • 結果： 完全合規，調查完整

Test 2: Time Pressure + Obvious Quick Fix

  • User "in a hurry", symptom fix looks easy
  • Result: Resisted shortcut, followed full process, found real root cause

測試 2：時間壓力 + 明顯的快速修復

  • 使用者「很趕」，症狀修復看起來很簡單
  • 結果： 抵抗了抄捷徑，走完完整流程，找出真正的根因

Test 3: Complex System + Uncertainty

  • Multi-layer failure, unclear if can find root cause
  • Result: Systematic investigation, traced through all layers, found source

測試 3：複雜系統 + 不確定性

  • 多層失敗，不確定能否找出根因
  • 結果： 系統化調查，追蹤穿過所有層次，找出源頭

Test 4: Failed First Fix

  • Hypothesis doesn't work, temptation to add more fixes
  • Result: Stopped, re-analyzed, formed new hypothesis (no shotgun)

測試 4：第一次修復失敗

  • 假設無效，誘惑是加更多修復
  • 結果： 停下來，重新分析，形成新假設（沒有亂槍打鳥）

All tests passed. No rationalizations found.

所有測試通過。 沒有發現合理化藉口。

Iterations

迭代

Initial Version

  • Complete 4-phase framework
  • Anti-patterns section
  • Flowchart for "fix failed" decision

初版

  • 完整的四階段框架
  • 反模式章節
  • 「修復失敗」決策的流程圖

Enhancement 1: TDD Reference

  • Added link to skills/testing/test-driven-development
  • Note explaining TDD's "simplest code" ≠ debugging's "root cause"
  • Prevents confusion between methodologies

增強 1：TDD 參考

  • 加入連到 skills/testing/test-driven-development 的連結
  • 說明 TDD 的「最簡程式碼」≠ 除錯的「根因」
  • 防止兩個方法論之間的混淆

Final Outcome

最終成果

Bulletproof skill that: - ✅ Clearly mandates root cause investigation - ✅ Resists time pressure rationalization - ✅ Provides concrete steps for each phase - ✅ Shows anti-patterns explicitly - ✅ Tested under multiple pressure scenarios - ✅ Clarifies relationship to TDD - ✅ Ready for use

一個可抗攻擊的技能，具備： - ✅ 明確規定根因調查 - ✅ 抵抗時間壓力的合理化 - ✅ 每個階段都有具體步驟 - ✅ 明確呈現反模式 - ✅ 在多重壓力情境下測試過 - ✅ 釐清與 TDD 的關係 - ✅ 可立即使用

Key Insight

關鍵領悟

Most important bulletproofing: Anti-patterns section showing exact shortcuts that feel justified in the moment. When Claude thinks "I'll just add this one quick fix", seeing that exact pattern listed as wrong creates cognitive friction.

最重要的加固： 反模式章節具體呈現那些當下感覺合理的抄捷徑。當 Claude 心想「我就加這個快速修復就好」，看到同一個模式被明確標記為錯誤，會產生認知摩擦。

Usage Example

使用範例

When encountering a bug: 1. Load skill: skills/debugging/systematic-debugging 2. Read overview (10 sec) - reminded of mandate 3. Follow Phase 1 checklist - forced investigation 4. If tempted to skip - see anti-pattern, stop 5. Complete all phases - root cause found

遇到 bug 時： 1. 載入技能：skills/debugging/systematic-debugging 2. 閱讀概述（10 秒）—— 喚起使命 3. 依循第一階段檢查清單 —— 強制調查 4. 若想跳過 —— 看到反模式，停下來 5. 完成所有階段 —— 找到根因

Time investment: 5-10 minutes Time saved: Hours of symptom-whack-a-mole

時間投資： 5-10 分鐘 省下的時間： 數小時的症狀打地鼠

Created: 2025-10-03 Purpose: Reference example for skill extraction and bulletproofing

建立日期：2025-10-03 目的：作為技能萃取與加固的參考範例