Back to Details

systematic-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Systematic Debugging

系统化调试

Source: obra/superpowers
Source: obra/superpowers

Overview

概述

This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
本技能提供一种结构化的调试方法，可避免随机猜测，确保在解决问题前充分理解问题。

4-Phase Debugging Process

四阶段调试流程

Phase 1: Reproduce

阶段1：复现

Before fixing, reliably reproduce the issue.
markdown
undefined
在修复之前，需稳定复现问题。
markdown
undefined

Reproduction Steps

复现步骤

  1. [Exact step to reproduce]
  2. [Next step]
  3. [Expected vs actual result]
  1. [具体复现步骤]
  2. [下一步操作]
  3. [预期结果 vs 实际结果]

Reproduction Rate

复现概率

  • Always (100%)
  • Often (50-90%)
  • Sometimes (10-50%)
  • Rare (<10%)
undefined
  • 总是（100%）
  • 经常（50-90%）
  • 有时（10-50%）
  • 很少（<10%）
undefined

Phase 2: Isolate

阶段2：定位

Narrow down the source.
markdown
undefined
缩小问题来源范围。
markdown
undefined

Isolation Questions

定位问题的疑问点

  • When did this start happening?
  • What changed recently?
  • Does it happen in all environments?
  • Can we reproduce with minimal code?
  • What's the smallest change that triggers it?
undefined
  • 这个问题从何时开始出现？
  • 最近有哪些变更？
  • 是否在所有环境中都会出现？
  • 能否用最简代码复现问题？
  • 触发问题的最小变更是什么？
undefined

Phase 3: Understand

阶段3：分析

Find the root cause, not just symptoms.
markdown
undefined
找到根本原因，而非仅处理表面症状。
markdown
undefined

Root Cause Analysis

根本原因分析

The 5 Whys

5个为什么分析法

  1. Why: [First observation]
  2. Why: [Deeper reason]
  3. Why: [Still deeper]
  4. Why: [Getting closer]
  5. Why: [Root cause]
undefined
  1. 为什么：[首次观察到的现象]
  2. 为什么：[更深层原因]
  3. 为什么：[更核心的原因]
  4. 为什么：[接近根源的原因]
  5. 为什么：[根本原因]
undefined

Phase 4: Fix & Verify

阶段4：修复与验证

Fix and verify it's truly fixed.
markdown
undefined
修复问题并验证是否彻底解决。
markdown
undefined

Fix Verification

修复验证

  • Bug no longer reproduces
  • Related functionality still works
  • No new issues introduced
  • Test added to prevent regression
undefined
  • Bug不再复现
  • 相关功能仍正常运行
  • 未引入新问题
  • 添加测试以防止回归
undefined

Debugging Checklist

调试检查清单

markdown
undefined
markdown
undefined

Before Starting

开始调试前

  • Can reproduce consistently
  • Have minimal reproduction case
  • Understand expected behavior
  • 能够稳定复现问题
  • 拥有最简复现案例
  • 理解预期行为

During Investigation

调查过程中

  • Check recent changes (git log)
  • Check logs for errors
  • Add logging if needed
  • Use debugger/breakpoints
  • 查看最近的变更记录（git log）
  • 检查日志中的错误信息
  • 如有需要添加日志
  • 使用调试器/断点

After Fix

修复完成后

  • Root cause documented
  • Fix verified
  • Regression test added
  • Similar code checked
undefined
  • 记录根本原因
  • 验证修复效果
  • 添加回归测试
  • 检查相似代码
undefined

Common Debugging Commands

常用调试命令

bash
undefined
bash
undefined

Recent changes

最近的变更

git log --oneline -20 git diff HEAD~5
git log --oneline -20 git diff HEAD~5

Search for pattern

搜索指定模式

grep -r "errorPattern" --include="*.ts"
grep -r "errorPattern" --include="*.ts"

Check logs

查看日志

pm2 logs app-name --err --lines 100
undefined
pm2 logs app-name --err --lines 100
undefined

Anti-Patterns

反模式

❌ Random changes - "Maybe if I change this..." ❌ Ignoring evidence - "That can't be the cause" ❌ Assuming - "It must be X" without proof ❌ Not reproducing first - Fixing blindly ❌ Stopping at symptoms - Not finding root cause
❌ 随机修改 - “或许我改一下这个试试...” ❌ 忽略证据 - “那不可能是原因” ❌ 主观假设 - “肯定是X的问题”却没有证据 ❌ 未复现就修复 - 盲目尝试修复 ❌ 仅处理表面症状 - 未找到根本原因