Back to Details

debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debugging

调试

Systematic approach to root cause analysis and debugging.
系统的根本原因分析与调试方法。

When to Use

适用场景

  • Encountering errors or exceptions
  • Test failures that need investigation
  • Unexpected behavior in code
  • Stack traces or error messages
  • Code behaving differently than expected
  • Performance issues or bugs
  • 遇到错误或异常时
  • 需要调查测试失败情况时
  • 代码出现意外行为时
  • 出现堆栈跟踪或错误消息时
  • 代码表现不符合预期时
  • 出现性能问题或漏洞时

Core Principles

核心原则

  • Evidence-based: Base diagnosis on error messages, logs, and reproducible steps
  • Systematic: Follow structured debugging process
  • Minimal fixes: Implement smallest change that resolves issue
  • Verify solutions: Confirm fix works and doesn't introduce regressions
  • 基于证据：根据错误消息、日志和可复现步骤进行诊断
  • 系统化：遵循结构化的调试流程
  • 最小修复：实施能解决问题的最小改动
  • 验证解决方案：确认修复有效且不会引入回归问题

Debugging Process

调试流程

Follow systematic debugging process:
  1. Capture error information (message, stack trace, logs, environment)
  2. Identify reproduction steps (minimal steps, conditions, edge cases)
  3. Isolate failure location (function/module, recent changes, dependencies)
  4. Form and test hypotheses (evidence-based, systematic testing, debug logging)
  5. Implement minimal fix (smallest change, preserve behavior, follow patterns)
  6. Verify solution (issue resolved, no regressions, tests pass)
See 
references/root-cause-analysis.md
for detailed methods.
遵循系统化的调试流程：
  1. 捕获错误信息（消息、堆栈跟踪、日志、环境信息）
  2. 确定复现步骤（最小步骤、条件、边缘情况）
  3. 定位失败位置（函数/模块、近期变更、依赖项）
  4. 形成并验证假设（基于证据、系统化测试、调试日志）
  5. 实施最小修复（最小改动、保留原有行为、遵循模式）
  6. 验证解决方案（问题已解决、无回归、测试通过）
详见
references/root-cause-analysis.md
获取详细方法。

Strategic Debug Logging

策略性调试日志

Add debug logging to entry/exit points, state transitions, conditional branches, external API calls, and data transformations. Remove after issue resolved unless it provides ongoing value.
在入口/出口点、状态转换、条件分支、外部API调用和数据转换处添加调试日志。问题解决后移除，除非日志具有持续价值。

Error Pattern Recognition

错误模式识别

Common patterns: null/undefined errors, type errors, timing issues, state corruption, configuration issues. See 
references/error-patterns.md
for detailed patterns and solutions.
常见模式：空值/未定义错误、类型错误、时序问题、状态损坏、配置问题。详见
references/error-patterns.md
获取详细模式与解决方案。

Integration

集成步骤

After fixing:
  • Verify CI passes (types, tests, lint)
  • Stage atomic changes (fix + tests)
  • Suggest semantic commit message
  • Confirm with user before committing
修复完成后：
  • 验证CI通过（类型检查、测试、代码规范检查）
  • 分阶段提交原子变更（修复+测试）
  • 建议语义化提交信息
  • 提交前与用户确认

References

参考资料

For detailed guidance, see:
  • references/root-cause-analysis.md
    - Systematic analysis methods
  • references/error-patterns.md
    - Common error patterns and solutions
  • references/debugging-tools.md
    - Debugging tools and techniques
如需详细指导，请参阅：
  • references/root-cause-analysis.md
    - 系统化分析方法
  • references/error-patterns.md
    - 常见错误模式与解决方案
  • references/debugging-tools.md
    - 调试工具与技巧