Back to Details

systematic-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Systematic Debugging

系统化调试

Core principle: Find root cause before attempting fixes. Symptom fixes are failure.
核心原则： 先找到根本原因再尝试修复。仅修复症状是无效的。

The Four Phases

四个阶段

Complete each phase before proceeding to the next.
Debugging Progress:
- [ ] Phase 1: Root Cause Investigation
- [ ] Phase 2: Pattern Analysis
- [ ] Phase 3: Hypothesis Testing
- [ ] Phase 4: Implementation
完成当前阶段后再进入下一阶段。
Debugging Progress:
- [ ] Phase 1: Root Cause Investigation
- [ ] Phase 2: Pattern Analysis
- [ ] Phase 3: Hypothesis Testing
- [ ] Phase 4: Implementation

Phase 1: Root Cause Investigation

阶段1：根本原因排查

Before attempting ANY fix:
  1. Read error messages carefully - Stack traces often contain the solution
  2. Reproduce consistently - If not reproducible, gather more data
  3. Check recent changes - Git diff, new dependencies, config changes
  4. Trace data flow backward - Find where invalid data originates
For multi-component systems: Add diagnostic logging at each component boundary before proposing fixes. See references/debugging-techniques.md for instrumentation patterns.
For log-heavy investigations: Use 
Skill(ce:reading-logs)
for efficient analysis.
在尝试任何修复之前：
  1. 仔细阅读错误信息 - 堆栈跟踪通常包含解决方案
  2. 稳定复现问题 - 若无法复现，收集更多数据
  3. 检查近期变更 - Git diff、新增依赖、配置变更
  4. 反向追踪数据流 - 定位无效数据的来源
对于多组件系统： 在提出修复方案前，在每个组件边界添加诊断日志。有关插桩模式，请参考references/debugging-techniques.md。
对于日志密集型排查： 使用
Skill(ce:reading-logs)
进行高效分析。

Phase 2: Pattern Analysis

阶段2：模式分析

  1. Find working examples of similar code in the codebase
  2. Compare working vs broken - list every difference
  3. Read reference implementations completely, not just skimming
  1. 在代码库中找到类似代码的可运行示例
  2. 对比可运行代码与故障代码，列出所有差异
  3. 完整阅读参考实现，不要仅略读

Phase 3: Hypothesis Testing

阶段3：假设验证

  1. Form single hypothesis: "X is the root cause because Y"
  2. Make the SMALLEST possible change to test it
  3. Verify before continuing - if wrong, form NEW hypothesis
  1. 提出单一假设：“X是根本原因，因为Y”
  2. 做出最小幅度的变更来验证假设
  3. 验证后再继续 - 若假设错误，提出新假设

Phase 4: Implementation

阶段4：修复实施

  1. Create failing test case first
  2. Implement single fix at root cause
  3. Apply defense-in-depth - Validate at multiple layers
  4. Verify fix and run tests
If 3+ fixes have failed: Stop fixing symptoms. Question the architecture.
  1. 先编写失败的测试用例
  2. 针对根本原因实施单一修复
  3. 应用纵深防御 - 在多个层面进行验证
  4. 验证修复并运行测试
若3次以上修复均失败： 停止修复症状，重新审视架构。

Red Flags

危险信号

Stop and return to Phase 1 if you catch yourself:
  • Proposing fixes without completing investigation
  • "Just try changing X and see if it works"
  • Adding multiple changes at once
  • "It's probably X, let me fix that" (without evidence)
  • Each fix reveals new problems in different places
如果发现自己出现以下行为，请停止操作并回到阶段1：
  • 未完成排查就提出修复方案
  • “试试改X看看能不能解决问题”
  • 同时进行多项变更
  • “可能是X的问题，我来修复它”（无证据支持）
  • 每次修复都会在不同地方暴露新问题

Tactical Techniques

实用技巧

For specific debugging methods, see references/debugging-techniques.md:
  • Binary search / git bisect
  • Minimal reproduction
  • Strategic logging
  • Runtime assertions
  • Differential analysis
  • Multi-component instrumentation
  • Backward tracing
有关具体调试方法，请参考references/debugging-techniques.md：
  • 二分查找 / git bisect
  • 最小化复现
  • 策略性日志
  • 运行时断言
  • 差异分析
  • 多组件插桩
  • 反向追踪

Reporting Format

报告格式

markdown
undefined
markdown
undefined

Root Cause

Root Cause

[1-3 sentences explaining underlying issue] Located in: 
file.ts:123
[1-3 sentences explaining underlying issue] Located in: 
file.ts:123

What Was Wrong

What Was Wrong

[Specific problem - mutation, race condition, missing validation, etc.]
[Specific problem - mutation, race condition, missing validation, etc.]

The Fix

The Fix

[Changes made and why they address root cause]
[Changes made and why they address root cause]

Verification

Verification

  • Bug reproduced and confirmed fixed
  • Existing tests pass
  • Added regression test
undefined
  • Bug reproduced and confirmed fixed
  • Existing tests pass
  • Added regression test
undefined