Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

dot-skills Debugging Best Practices

dot-skills 调试最佳实践

Comprehensive debugging methodology guide for software engineers, containing 54 rules across 10 categories prioritized by impact. Based on research from Andreas Zeller's "Why Programs Fail" and academic debugging curricula.
面向软件工程师的全面调试方法论指南，包含按影响优先级划分的10个类别共54条规则。基于Andreas Zeller的《Why Programs Fail》及学术调试课程研究而成。

When to Apply

适用场景

Reference these guidelines when:
  • Investigating a bug or unexpected behavior
  • Debugging code during development
  • Code produces wrong results or crashes
  • Performance issues need root cause analysis
  • Triaging incoming bug reports and prioritizing fixes
  • Conducting root cause analysis for incidents
  • Reviewing debugging approaches or code for common bug patterns
在以下场景中可参考本指南：
  • 排查bug或意外行为
  • 开发过程中调试代码
  • 代码输出错误结果或崩溃
  • 需要对性能问题进行根因分析
  • 分类处理收到的bug报告并确定修复优先级
  • 针对事件开展根因分析
  • 审查调试方法或代码中的常见bug模式

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefix
1Problem DefinitionCRITICAL
prob-
2Hypothesis-Driven SearchCRITICAL
hypo-
3Observation TechniquesHIGH
obs-
4Root Cause AnalysisHIGH
rca-
5Tool MasteryMEDIUM-HIGH
tool-
6Bug Triage and ClassificationMEDIUM
triage-
7Common Bug PatternsMEDIUM
pattern-
8Fix VerificationMEDIUM
verify-
9Anti-PatternsMEDIUM
anti-
10Prevention & LearningLOW-MEDIUM
prev-
优先级类别影响级别前缀
1问题定义CRITICAL
prob-
2基于假设的排查CRITICAL
hypo-
3观测技巧HIGH
obs-
4根因分析HIGH
rca-
5工具精通MEDIUM-HIGH
tool-
6Bug分类与优先级划分MEDIUM
triage-
7常见Bug模式MEDIUM
pattern-
8修复验证MEDIUM
verify-
9反模式MEDIUM
anti-
10预防与学习LOW-MEDIUM
prev-

Quick Reference

快速参考

1. Problem Definition (CRITICAL)

1. 问题定义（CRITICAL）

  • prob-reproduce-before-debug
    - Reproduce the bug before investigating
  • prob-minimal-reproduction
    - Create minimal reproduction cases
  • prob-document-symptoms
    - Document symptoms precisely
  • prob-separate-symptoms-causes
    - Separate symptoms from causes
  • prob-state-expected-actual
    - State expected vs actual behavior
  • prob-recent-changes
    - Check recent changes first
  • prob-reproduce-before-debug
    - 先复现bug再开展排查
  • prob-minimal-reproduction
    - 创建最小化复现案例
  • prob-document-symptoms
    - 精准记录症状
  • prob-separate-symptoms-causes
    - 区分症状与原因
  • prob-state-expected-actual
    - 明确预期行为与实际行为的差异
  • prob-recent-changes
    - 优先检查近期变更

2. Hypothesis-Driven Search (CRITICAL)

2. 基于假设的排查（CRITICAL）

  • hypo-scientific-method
    - Apply the scientific method
  • hypo-binary-search
    - Use binary search to localize bugs
  • hypo-one-change-at-time
    - Test one hypothesis at a time
  • hypo-where-not-what
    - Find WHERE before asking WHAT
  • hypo-rule-out-obvious
    - Rule out obvious causes first
  • hypo-rubber-duck
    - Explain the problem aloud
  • hypo-scientific-method
    - 应用科学方法
  • hypo-binary-search
    - 使用二分法定位bug
  • hypo-one-change-at-time
    - 每次仅测试一个假设
  • hypo-where-not-what
    - 先确定位置再探究问题
  • hypo-rule-out-obvious
    - 先排除明显原因
  • hypo-rubber-duck
    - 大声讲解问题

3. Observation Techniques (HIGH)

3. 观测技巧（HIGH）

  • obs-strategic-logging
    - Use strategic logging
  • obs-log-inputs-outputs
    - Log function inputs and outputs
  • obs-breakpoint-strategy
    - Use breakpoints strategically
  • obs-stack-trace-reading
    - Read stack traces bottom to top
  • obs-watch-expressions
    - Use watch expressions for state
  • obs-trace-data-flow
    - Trace data flow through system
  • obs-strategic-logging
    - 采用策略性日志
  • obs-log-inputs-outputs
    - 记录函数的输入与输出
  • obs-breakpoint-strategy
    - 策略性使用断点
  • obs-stack-trace-reading
    - 从下往上阅读堆栈跟踪信息
  • obs-watch-expressions
    - 使用监视表达式查看状态
  • obs-trace-data-flow
    - 跟踪系统中的数据流

4. Root Cause Analysis (HIGH)

4. 根因分析（HIGH）

  • rca-five-whys
    - Use the 5 Whys technique
  • rca-fault-propagation
    - Trace fault propagation chains
  • rca-last-known-good
    - Find the last known good state
  • rca-question-assumptions
    - Question your assumptions
  • rca-examine-boundaries
    - Examine system boundaries
  • rca-five-whys
    - 使用5Why分析法
  • rca-fault-propagation
    - 跟踪故障传播链
  • rca-last-known-good
    - 找到最后一个正常状态
  • rca-question-assumptions
    - 质疑既有假设
  • rca-examine-boundaries
    - 检查系统边界

5. Tool Mastery (MEDIUM-HIGH)

5. 工具精通（MEDIUM-HIGH）

  • tool-conditional-breakpoints
    - Use conditional breakpoints
  • tool-logpoints
    - Use logpoints instead of modifying code
  • tool-step-commands
    - Master step over/into/out
  • tool-call-stack-navigation
    - Navigate the call stack
  • tool-memory-inspection
    - Inspect memory and object state
  • tool-exception-breakpoints
    - Use exception breakpoints
  • tool-conditional-breakpoints
    - 使用条件断点
  • tool-logpoints
    - 使用日志断点而非修改代码
  • tool-step-commands
    - 精通单步跳过/单步进入/单步跳出命令
  • tool-call-stack-navigation
    - 导航调用栈
  • tool-memory-inspection
    - 检查内存与对象状态
  • tool-exception-breakpoints
    - 使用异常断点

6. Bug Triage and Classification (MEDIUM)

6. Bug分类与优先级划分（MEDIUM）

  • triage-severity-vs-priority
    - Separate severity from priority
  • triage-user-impact-assessment
    - Assess user impact before prioritizing
  • triage-reproducibility-matters
    - Factor reproducibility into triage
  • triage-quick-wins-first
    - Identify and ship quick wins first
  • triage-duplicate-detection
    - Detect and link duplicate bug reports
  • triage-severity-vs-priority
    - 区分严重程度与优先级
  • triage-user-impact-assessment
    - 先评估用户影响再确定优先级
  • triage-reproducibility-matters
    - 将可复现性纳入分类考量
  • triage-quick-wins-first
    - 先识别并交付快速修复项
  • triage-duplicate-detection
    - 检测并关联重复的bug报告

7. Common Bug Patterns (MEDIUM)

7. 常见Bug模式（MEDIUM）

  • pattern-null-pointer
    - Recognize null pointer patterns
  • pattern-off-by-one
    - Spot off-by-one errors
  • pattern-race-condition
    - Identify race condition symptoms
  • pattern-memory-leak
    - Detect memory leak patterns
  • pattern-type-coercion
    - Watch for type coercion bugs
  • pattern-async-await-errors
    - Catch async/await error handling mistakes
  • pattern-timezone-issues
    - Recognize timezone and date bugs
  • pattern-null-pointer
    - 识别空指针模式
  • pattern-off-by-one
    - 发现差一错误
  • pattern-race-condition
    - 识别竞态条件症状
  • pattern-memory-leak
    - 检测内存泄漏模式
  • pattern-type-coercion
    - 注意类型转换bug
  • pattern-async-await-errors
    - 捕获async/await错误处理失误
  • pattern-timezone-issues
    - 识别时区与日期bug

8. Fix Verification (MEDIUM)

8. 修复验证（MEDIUM）

  • verify-reproduce-fix
    - Verify with original reproduction
  • verify-regression-check
    - Check for regressions
  • verify-understand-why-fix-works
    - Understand why fix works
  • verify-add-test
    - Add test to prevent recurrence
  • verify-reproduce-fix
    - 使用原始复现案例验证修复效果
  • verify-regression-check
    - 检查是否存在回归问题
  • verify-understand-why-fix-works
    - 理解修复生效的原因
  • verify-add-test
    - 添加测试以防止问题复发

9. Anti-Patterns (MEDIUM)

9. 反模式（MEDIUM）

  • anti-shotgun-debugging
    - Avoid shotgun debugging
  • anti-quick-patch
    - Avoid quick patches without understanding
  • anti-tunnel-vision
    - Avoid tunnel vision on initial hypothesis
  • anti-debug-fatigue
    - Recognize debugging fatigue
  • anti-blame-tool
    - Don't blame the tool too quickly
  • anti-shotgun-debugging
    - 避免盲目调试
  • anti-quick-patch
    - 避免未理解问题就仓促打补丁
  • anti-tunnel-vision
    - 避免局限于初始假设
  • anti-debug-fatigue
    - 警惕调试疲劳
  • anti-blame-tool
    - 不要轻易归咎于工具

10. Prevention & Learning (LOW-MEDIUM)

10. 预防与学习（LOW-MEDIUM）

  • prev-document-solution
    - Document bug solutions
  • prev-postmortem
    - Conduct blameless postmortems
  • prev-defensive-coding
    - Add defensive code at boundaries
  • prev-improve-error-messages
    - Improve error messages
  • prev-document-solution
    - 记录bug解决方案
  • prev-postmortem
    - 开展无责事后复盘
  • prev-defensive-coding
    - 在系统边界添加防御性代码
  • prev-improve-error-messages
    - 优化错误提示信息

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:
  • Section definitions - Category structure and impact levels
  • Rule template - Template for adding new rules
  • Example rules: prob-reproduce-before-debug, hypo-binary-search
阅读单独的参考文件获取详细说明及代码示例：
  • 章节定义 - 类别结构与影响级别说明
  • 规则模板 - 添加新规则的模板
  • 示例规则：prob-reproduce-before-debug, hypo-binary-search

Full Compiled Document

完整编译文档

For the complete guide with all rules expanded: AGENTS.md
如需查看包含所有扩展规则的完整指南：AGENTS.md