Back to Details

debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging

调试

Comprehensive debugging framework combining systematic investigation, root cause tracing, defense-in-depth validation, and verification protocols.
结合系统化调查、根本原因追踪、纵深防御验证及确认协议的综合性调试框架。

Core Principle

核心原则

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
Random fixes waste time and create new bugs. Find the root cause, fix at source, validate at every layer, verify before claiming success.
未完成根本原因调查，绝不修复问题
随机修复只会浪费时间并引入新Bug。找到根本原因，从源头修复，在每一层进行验证，在宣称成功前先确认修复效果。

When to Use

适用场景

Always use for: Test failures, bugs, unexpected behavior, performance issues, build failures, integration problems, before claiming work complete
Especially when: Under time pressure, "quick fix" seems obvious, tried multiple fixes, don't fully understand issue, about to claim success
始终适用于： 测试失败、Bug、意外行为、性能问题、构建失败、集成问题、在宣称工作完成前
尤其适用于： 处于时间压力下、“快速修复”看似可行、已尝试多种修复方案、未完全理解问题、即将宣称工作完成时

The Four Techniques

四大技术

1. Systematic Debugging (
references/systematic-debugging.md
)

1. 系统化调试（
references/systematic-debugging.md
）

Four-phase framework ensuring proper investigation:
  • Phase 1: Root Cause Investigation (read errors, reproduce, check changes, gather evidence)
  • Phase 2: Pattern Analysis (find working examples, compare, identify differences)
  • Phase 3: Hypothesis and Testing (form theory, test minimally, verify)
  • Phase 4: Implementation (create test, fix once, verify)
Key rule: Complete each phase before proceeding. No fixes without Phase 1.
Load when: Any bug/issue requiring investigation and fix
四阶段框架确保进行充分调查：
  • 阶段1：根本原因调查（读取错误信息、复现问题、检查变更、收集证据）
  • 阶段2：模式分析（寻找可用示例、对比、识别差异）
  • 阶段3：假设与测试（形成理论、最小化测试、验证）
  • 阶段4：实施（创建测试、一次性修复、验证）
关键规则： 完成当前阶段后再进入下一阶段。未完成阶段1，绝不修复问题。
加载时机： 任何需要调查与修复的Bug/问题

2. Root Cause Tracing (
references/root-cause-tracing.md
)

2. 根本原因追踪（
references/root-cause-tracing.md
）

Trace bugs backward through call stack to find original trigger.
Technique: When error appears deep in execution, trace backward level-by-level until finding source where invalid data originated. Fix at source, not at symptom.
Includes: 
scripts/find-polluter.sh
for bisecting test pollution
Load when: Error deep in call stack, unclear where invalid data originated
通过调用栈反向追踪Bug，找到最初的触发点。
技巧： 当错误出现在执行流程深处时，逐层反向追踪，直到找到无效数据的源头。从源头修复，而非仅修复症状。
包含： 用于二分查找测试污染的
scripts/find-polluter.sh
脚本
加载时机： 错误出现在调用栈深处、不清楚无效数据来源时

3. Defense-in-Depth (
references/defense-in-depth.md
)

3. 纵深防御（
references/defense-in-depth.md
）

Validate at every layer data passes through. Make bugs impossible.
Four layers: Entry validation → Business logic → Environment guards → Debug instrumentation
Load when: After finding root cause, need to add comprehensive validation
在数据流经的每一层进行验证，从根源杜绝Bug。
四层验证： 入口验证 → 业务逻辑 → 环境防护 → 调试工具
加载时机： 找到根本原因后，需要添加全面验证时

4. Verification (
references/verification.md
)

4. 确认（
references/verification.md
）

Run verification commands and confirm output before claiming success.
Iron law: NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
Run the command. Read the output. Then claim the result.
Load when: About to claim work complete, fixed, or passing
在宣称成功前，运行确认命令并核对输出结果。
铁律： 无最新确认证据，绝不宣称完成
运行命令，读取输出，再宣称结果。
加载时机： 即将宣称工作完成、问题已修复或测试通过时

Quick Reference

快速参考

Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md (trace backward)
  Found root cause? → defense-in-depth.md (add layers)
  About to claim success? → verification.md (verify first)
Bug → systematic-debugging.md (Phase 1-4)
  Error deep in stack? → root-cause-tracing.md (trace backward)
  Found root cause? → defense-in-depth.md (add layers)
  About to claim success? → verification.md (verify first)

Red Flags

危险信号

Stop and follow process if thinking:
  • "Quick fix for now, investigate later"
  • "Just try changing X and see if it works"
  • "It's probably X, let me fix that"
  • "Should work now" / "Seems fixed"
  • "Tests pass, we're done"
All mean: Return to systematic process.
若出现以下想法，请立即停止并遵循流程：
  • “先快速修复，之后再调查”
  • “试试修改X，看是否有效”
  • “可能是X的问题，我来修复它”
  • “现在应该没问题了” / “看起来已经修复了”
  • “测试通过了，我们完成了”
以上所有想法都意味着： 回到系统化流程中。