Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Systematic Debugging

系统化调试

Iron Law

铁律

IF >= 3 FIXES TRIED, STOP AND QUESTION THE ARCHITECTURE
IF >= 3 FIXES TRIED, STOP AND QUESTION THE ARCHITECTURE

Phases

阶段

1. Reproduce

1. 重现

Confirm the bug with a minimal, exact reproduction case.
  • Get the exact error message and stack trace
  • Write a failing test if possible
  • If you cannot reproduce it, you cannot fix it
通过最小化的精确复现案例确认bug。
  • 获取精确的错误信息和堆栈跟踪
  • 如有可能，编写一个失败测试用例
  • 无法复现的bug，也无法修复

2. Hypothesize

2. 假设

Form 3 hypotheses about the root cause.
  • Rank them by likelihood
  • Explain the reasoning behind each
  • Do NOT skip to fixing before hypothesizing
针对根本原因提出3个假设。
  • 按可能性排序
  • 解释每个假设的推理依据
  • 在提出假设前，切勿直接跳到修复步骤

3. Investigate

3. 调查

Pick ONE investigation technique and apply it:
  • Binary search: narrow the problem space by halving (comment out half the code, does it still fail?)
  • Trace: follow the execution path from input to failure point
  • Instrument: add logging/assertions at key points to observe state
选择一种调查技术并应用：
  • 二分查找：通过减半（注释掉一半代码，查看是否仍会失败）缩小问题范围
  • 追踪：沿着从输入到失败点的执行路径排查
  • 插桩：在关键位置添加日志/断言以观察状态

4. Fix

4. 修复

Apply a minimal, targeted change that addresses the root cause.
  • Explain what the fix does and why it solves the root cause
  • Do NOT fix symptoms — fix root causes
  • If the fix touches more than 10 lines, question whether it's minimal
实施针对根本原因的最小化、精准修改。
  • 说明修复的内容以及为何能解决根本原因
  • 切勿只修复症状——要修复根本原因
  • 如果修复修改了超过10行代码，需质疑是否做到了最小化

5. Verify

5. 验证

Run the original reproduction case.
  • It must pass
  • The bug must no longer occur
运行最初的复现案例。
  • 必须通过
  • bug必须不再出现

6. Regression

6. 回归测试

Run the full test suite.
  • No new failures introduced
  • If regressions appear, your fix changed behavior — investigate before committing
运行完整测试套件。
  • 不得引入新的失败
  • 如果出现回归问题，说明你的修复改变了原有行为——提交前需调查清楚

Red Flags — If You Catch Yourself Thinking:

危险信号——如果你发现自己有以下想法：

ThoughtReality
"I think I know what's wrong, let me just fix it"You have NO hypothesis until you've reproduced. Reproduce FIRST.
"Let me try a different fix" (3rd time)STOP. You're guessing. Question the architecture.
"The fix is too big to test incrementally"Break it down. Every fix is testable.
"It works on my end"Reproduce in the EXACT environment where it fails.
想法实际情况
“我觉得我知道问题出在哪，直接修复就行”在复现之前，你没有任何假设。先复现。
“我试试另一个修复方案”（第三次尝试）停止。你在猜测。质疑架构。
“这个修复太大了，无法逐步测试”拆分它。所有修复都可测试。
“在我这边是正常的”在问题出现的完全相同的环境中复现。

Rules

规则

  • NEVER skip reproduction
  • NEVER apply more than 3 fixes without stepping back and questioning the architecture
  • ALWAYS verify the fix doesn't introduce regressions
  • Document what you tried and what you learned in progress.txt
  • 永远不要跳过重现步骤
  • 永远不要在未退一步质疑架构的情况下尝试超过3次修复
  • 始终验证修复不会引入回归问题
  • 在progress.txt中记录你尝试过的方法和学到的内容