systematic-debugging git:20260919.7add278A

Immutable. This exact content never changes and is served at /api/v1/blob/ff1a3b7f7ce5603d.

---
name: systematic-debugging
description: 在缺陷、测试或构建失败、异常行为和反复修错时使用；先建立可区分假设的反馈环和根因证据，再按用户授权决定是否修复。普通代码审查、明确的小修改或只执行已有测试不触发。
---

# 系统化排查问题

目标是找到能解释现象的根因，并用同一个反馈环证明修复有效。诊断请求默认只定位和报告；用户要求修复时才修改代码。

## 核心循环

1. **固定现象**：记录错误、环境、输入、期望、实际结果和最近已知正常状态。
2. **建立反馈环**：优先使用最小测试、复现命令、页面路径、日志条件或可观察状态，使问题能失败、复跑并在修复后变绿。
3. **收集独立证据**：日志、堆栈、配置差异、近期变更、相关源码、网络和环境状态可以并行读取，但结论必须汇入同一证据链。
4. **排序假设**：维护轻量矩阵：

   `假设 | 支持证据 | 反证 | 置信度 | 下一步最小检查`

5. **验证一个假设**：用最小观测或可逆改动获取能证实或证伪的结果，不同时改变多个变量。
6. **更新模型**：记录被排除方向；同一症状未消失时停止叠补丁，回到矩阵重新排序。
7. **修复与回归**：根因明确且用户授权修复后，做最小修改；先用原反馈环证明问题消失，再按风险扩大验证。

在改代码前，应能用一句话表达当前假设：`我认为根因是 X，因为证据 Y；结果 Z 会证伪它。`

## 没有稳定复现时

只能做读取、加观测和缩小范围，不把猜测提交成修复。记录可替代证据，例如 CI 失败、生产日志、用户的稳定步骤、状态差异或最小监控指标，并说明它比本地复现弱在哪里。

运行一次后通过不能自动判定 flaky。至少需要近期重复运行、通过对照和能解释失败的基础设施或时序证据。

## 参考路由

只在命中对应问题时读取：

- [root-cause-tracing.md](root-cause-tracing.md)：错误出现在深层调用链，需要追踪原始输入或触发点。
- [condition-based-waiting.md](condition-based-waiting.md)：异步或测试依赖时序，需要用条件轮询替代固定 `sleep`。
- [defense-in-depth.md](defense-in-depth.md)：根因修复后仍需要在多个边界阻止无效状态传播。
- [references/advanced-modes.md](references/advanced-modes.md)：回归对照、二分定位、同型缺陷搜索、运行时证据和配置诊断。

## 安全边界

- 修改配置、版本、端口、权限或网络参数前，记录原值、目标文件和要验证的假设；失败后恢复本轮临时变化。
- 生产和共享环境先做只读检查；修复、重启、删除、回滚和权限操作需要明确目标与授权。
- 临时日志只记录能区分假设的事实，不输出凭据或敏感数据，并在任务结束前移除不需要的观测代码。
- 保护用户工作区中的无关改动，不用破坏性 Git 命令清理环境。
- 编译或静态检查通过不能证明界面、网络、生成物、状态机或生产行为已经恢复。

## 停止与重置

- 连续两个假设被证伪后，重新排序矩阵，不沿熟悉方向继续加码。
- 连续三个假设被证据推翻后，汇总现象、证据和已排除方向，重新选择诊断方法；有已授权的有效检查时继续，不因计数自动交接。
- 同一阈值、超时、间距或数值调整三次仍不对时，停止调参，检查结构约束和不变量。
- 缺少完成诊断所必需的访问、日志或复现条件时，报告具体缺口和能继续的最小输入。

## 输出契约

报告：

- 现象、范围和复现/替代证据；
- 当前最高置信假设及其反证条件；
- 已排除方向和关键命令/观察；
- 根因结论及证据强度，或为什么仍不能确定；
- 若已修复：实际改动、原反馈环结果、更宽验证和残余风险；
- 若只诊断：不修改文件，并给出下一步最小检查。