systematic-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Systematic Debugging

系统化调试

Find the cause before changing code. A fix should explain the evidence, not merely make one symptom disappear.

在修改代码前先找出原因。修复方案应能解释相关证据，而不只是让一个症状消失。

Investigate

调查

Observe and reproduce. Read the complete error or wrong output. Record the exact steps, inputs, environment, and expected versus actual result. If it is intermittent, gather more examples instead of claiming a reproduction.
Trace the failing path. Check recent changes and follow the relevant data or control flow from the observed failure toward its source. In multi-component systems, inspect the values at the boundaries to learn which component first diverges.
Compare with a working case. Find a similar successful path and identify the differences in inputs, state, configuration, dependencies, or timing.
State one hypothesis. Explain which evidence supports it. Test the smallest useful change or probe, changing one variable at a time.
Fix the root cause and verify. Preserve a reproducible failure before editing. Prefer the project's existing test setup; if none exists, record exact manual steps or use a small disposable check instead of scaffolding a framework unasked. After the fix, repeat the reproduction and run relevant checks. State what was and was not verified.

If the hypothesis is wrong, return to the evidence and form another one; do not stack guesses. If several well-supported fixes fail or each exposes a new coupling, pause and reconsider the design with the user before another attempt.

观察并复现。 阅读完整的错误信息或错误输出。记录准确的步骤、输入、环境，以及预期结果与实际结果。如果问题是间歇性的，应收集更多样例，而不是声称已经成功复现。
追踪失败路径。 检查近期变更，从观察到的失败点沿着相关数据流或控制流回溯到源头。在多组件系统中，检查边界处的值，以确定哪个组件最先出现偏差。
与正常案例比较。 找到一条相似的成功路径，并确定其在输入、状态、配置、依赖关系或执行时机上的差异。
提出一个假设。 说明支持该假设的证据。测试最小且有效的变更或探测，每次只改变一个变量。
修复根因并验证。 在编辑前保留可复现的失败。优先使用项目现有的测试设置；如果不存在，则记录准确的手动步骤，或使用小型的一次性检查，而不是未经要求便搭建测试框架。修复后，重复复现步骤并运行相关检查。说明验证了什么，以及未验证什么。

如果假设错误，应重新查看证据并形成另一个假设；不要叠加各种猜测。如果多个有充分证据支持的修复方案均告失败，或每次尝试都会暴露新的耦合问题，应暂停，并在再次尝试前与用户重新审视设计。

When the Failure Is in an Output

当故障出现在输出中

When a system produces incorrect decisions or reports without throwing an error, inspect the recorded inputs and outputs first. Compare like cases, identify the rule or branch associated with the failure, change one rule at a time, and measure the same outcome again. A metric that does not improve is evidence to investigate the implementation; by itself it is not a reason to delete the concept.

当系统给出错误的决策或报告，但没有抛出错误时，应先检查已记录的输入和输出。比较同类案例，识别与失败相关的规则或分支，每次只更改一条规则，然后再次测量相同结果。某个指标没有改善，是需要调查实现情况的证据；仅凭这一点不足以删除该概念。

Useful Supporting Techniques

有用的辅助技术

These files are optional deeper techniques in this skill's directory:

```
root-cause-tracing.md
```
— trace a defect back through a deep call chain.
```
defense-in-depth.md
```
— add layered checks after identifying the source.
```
condition-based-waiting.md
```
— replace timing guesses with condition-based waits.

以下是此 skill 目录中可选的深入技术：

```
root-cause-tracing.md
```
— 通过深层调用链追踪缺陷根源。
```
defense-in-depth.md
```
— 确定源头后添加分层检查。
```
condition-based-waiting.md
```
— 用基于条件的等待替代对时机的猜测。