Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug Mode

Debug Mode

Systematic bug investigation and resolution.
系统性的Bug调查与解决方法。

Core Approach

核心方法

"Don't guess. Form hypotheses. Test them."
"不要猜测。提出假设。验证假设。"

The 4-Phase Process

四阶段流程

Phase 1: Assessment 🔍

阶段1：评估 🔍

Goal: Understand and reproduce
  • What is the expected behavior?
  • What is the actual behavior?
  • Can you reliably reproduce?
  • What changed recently?
Key Questions:
  • When did this start happening?
  • Does it happen consistently or intermittently?
  • What are the exact inputs that trigger it?
  • What error messages or symptoms appear?
目标: 理解并复现问题
  • 预期行为是什么？
  • 实际行为是什么？
  • 能否稳定复现问题？
  • 最近有哪些变更？
关键问题:
  • 这个问题从什么时候开始出现的？
  • 是持续出现还是间歇性发作？
  • 触发问题的精确输入是什么？
  • 出现了哪些错误信息或症状？

Phase 2: Investigation 🔬

阶段2：调查 🔬

Goal: Isolate and trace
  • Trace execution from entry point
  • Identify where expected diverges from actual
  • Form hypotheses about root cause
  • Test hypotheses systematically
Techniques:
  • Add strategic logging/prints
  • Use debugger breakpoints
  • Simplify inputs to minimal reproduction
  • Check boundary conditions
目标: 定位并追踪问题
  • 从入口点追踪执行流程
  • 找出预期行为与实际行为的分歧点
  • 对根本原因提出假设
  • 系统性地验证假设
常用技巧:
  • 添加针对性日志/打印信息
  • 使用调试器断点
  • 简化输入以实现最小化复现
  • 检查边界条件

Phase 3: Resolution 🔧

阶段3：修复 🔧

Goal: Fix minimally and verify
  • Implement the smallest fix that addresses root cause
  • Don't fix symptoms, fix the disease
  • Add regression test
  • Verify fix doesn't break other things
If fix doesn't work:
  • Count: How many fixes attempted?
  • If < 3: Return to Phase 1, re-analyze with new information
  • If ≥ 3: STOP. Question your understanding of the system.
目标: 最小化修复并验证
  • 实施针对根本原因的最小化修复
  • 不要只修复症状，要解决根源问题
  • 添加回归测试
  • 验证修复不会影响其他功能
如果修复无效:
  • 统计：已经尝试了多少次修复？
  • 若<3次：回到阶段1，结合新信息重新分析
  • 若≥3次：停止。重新审视你对系统的理解。

Phase 4: Quality ✅

阶段4：质量保障 ✅

Goal: Prevent recurrence
  • Add test covering the bug
  • Document if the cause was non-obvious
  • Consider if similar bugs exist elsewhere
  • Clean up debug code
目标: 防止问题复发
  • 添加覆盖该bug的测试用例
  • 若原因不明显则进行文档记录
  • 考虑是否存在类似的潜在bug
  • 清理调试代码

Debugging Checklist

调试检查表

markdown
- [ ] **Reproduced**: Can trigger bug consistently
- [ ] **Isolated**: Know which component is failing
- [ ] **Root Cause**: Understand WHY it fails
- [ ] **Fixed**: Minimal change addresses cause
- [ ] **Tested**: Regression test added
- [ ] **Clean**: Debug code removed
markdown
- [ ] **已复现**: 可稳定触发bug
- [ ] **已定位**: 明确故障组件
- [ ] **已找到根因**: 理解故障原因
- [ ] **已修复**: 最小化变更解决根因
- [ ] **已测试**: 添加回归测试
- [ ] **已清理**: 移除调试代码

Hypothesis Template

假设模板

markdown
**Hypothesis**: [What you think is wrong]
**Test**: [How you'll verify]
**Result**: [What happened]
**Conclusion**: [Confirmed/Rejected/Needs more info]
markdown
**假设**: [你认为存在的问题]
**测试方法**: [你将如何验证]
**结果**: [实际发生的情况]
**结论**: [已确认/已推翻/需要更多信息]

Common Root Causes

常见根本原因

SymptomOften Caused By
Works locally, fails in CIEnvironment differences, missing deps
Intermittent failureRace condition, timing, external dependency
Wrong outputLogic error, wrong variable, off-by-one
Crash/exceptionNull/None access, type mismatch, missing data
Performance issueN+1 queries, missing index, memory leak
症状常见原因
本地正常，CI环境失败环境差异、依赖缺失
间歇性故障竞态条件、时序问题、外部依赖
输出错误逻辑错误、变量误用、差一错误
崩溃/异常空值/None访问、类型不匹配、数据缺失
性能问题N+1查询、索引缺失、内存泄漏

Rationalization Prevention

合理化借口规避

ExcuseReality
"I'll just add a quick fix"Quick fixes hide root cause. Follow Phase 1 first.
"It's probably X""Probably" isn't evidence. Test the hypothesis.
"This is too simple to debug formally"Simple bugs waste the most time when undiagnosed.
"I've tried 3 things, might as well try a 4th"STOP. Return to Phase 1. Re-analyze with new info.
"It works now, not sure why"If you don't know why it works, it will break again.
借口实际情况
"我先快速修复一下"快速修复会掩盖根因。先执行阶段1。
"可能是X的问题""可能"不是证据。请验证假设。
"这个太简单了，不用正式调试"简单bug在未诊断时会浪费最多时间。
"我已经试了3种方法，不如再试第4种"停止。回到阶段1，结合新信息重新分析。
"现在能用了，不知道为什么"如果你不知道原因，它还会再次故障。

Red Flags - STOP and Re-Assess

危险信号 - 立即停止并重新评估

  • Adding a 3rd fix attempt without returning to Phase 1
  • Saying "should work now" without verification
  • Fixing a symptom because root cause is unclear
  • Skipping reproduction because "I know what's wrong"
  • Multiple hypotheses being tested simultaneously
  • 未回到阶段1就尝试第3次修复
  • 未验证就说"现在应该能用了"
  • 因根因不明而只修复症状
  • 因"我知道问题所在"而跳过复现步骤
  • 同时测试多个假设

Debug Report Format

调试报告格式

markdown
undefined
markdown
undefined

Debug Report

调试报告

Bug Summary

Bug摘要

  • Expected: [what should happen]
  • Actual: [what happens instead]
  • Severity: [critical/high/medium/low]
  • 预期: [应该发生的情况]
  • 实际: [实际发生的情况]
  • 严重程度: [严重/高/中/低]

Reproduction

复现步骤

  1. [Step to reproduce]
  2. [Step to reproduce]
  3. [Observe bug]
Minimal reproduction: [simplest case that triggers bug]
  1. [复现步骤1]
  2. [复现步骤2]
  3. [观察到bug]
最小化复现用例: [能触发bug的最简场景]

Investigation

调查过程

HypothesisTestResult
[theory][what I tried]✅ Confirmed / ❌ Rejected
假设测试方法结果
[理论][我尝试的操作]✅ 已确认 / ❌ 已推翻

Root Cause

根本原因

[What's actually wrong and why]
[实际问题及原因]

Fix Applied

修复方案

  • File: 
    path/to/file.py
  • Change: [what was modified]
  • Why: [how this fixes the root cause]
  • 文件: 
    path/to/file.py
  • 变更内容: [修改的内容]
  • 修复原因: [该变更如何解决根本原因]

Verification

验证情况

  • Bug no longer reproduces
  • Existing tests pass
  • Regression test added: 
    test_name
  • No debug code left behind
  • Bug不再复现
  • 现有测试全部通过
  • 已添加回归测试: 
    test_name
  • 无遗留调试代码

Prevention

预防措施

[How to prevent similar bugs in the future]
undefined
[如何防止未来出现类似bug]
undefined