debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

常见根本原因

Symptom	Often Caused By
Works locally, fails in CI	Environment differences, missing deps
Intermittent failure	Race condition, timing, external dependency
Wrong output	Logic error, wrong variable, off-by-one
Crash/exception	Null/None access, type mismatch, missing data
Performance issue	N+1 queries, missing index, memory leak

症状	常见原因
本地正常，CI环境失败	环境差异、依赖缺失
间歇性故障	竞态条件、时序问题、外部依赖
输出错误	逻辑错误、变量误用、差一错误
崩溃/异常	空值/None访问、类型不匹配、数据缺失
性能问题	N+1查询、索引缺失、内存泄漏

Rationalization Prevention

合理化借口规避

Excuse	Reality
"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

复现步骤

[Step to reproduce]
[Step to reproduce]
[Observe bug]

Minimal reproduction: [simplest case that triggers bug]

[复现步骤1]
[复现步骤2]
[观察到bug]

最小化复现用例: [能触发bug的最简场景]

Investigation

调查过程

Hypothesis	Test	Result
[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