结构化工程调试

它在解决什么问题

排障时最常见的两种失败模式：一是时间压力下「先打个补丁再说」，结果把表面 bug 变成更难排查的深层问题；二是盯着崩溃现场修——错误出现在某一行，就把那行改掉，而真正偏离预期的输入早在上游几层就已产生。这个技能针对这两类情况，把「定位根因」明确为调试的核心交付物，而不是修复动作本身。

核心能力与关键步骤

不可妥协的底线：任何修复提案之前必须先给出根因。唯一例外是「显而易见的 bug」，且判定标准是原因已写在错误信息里，例如 ModuleNotFoundError: no module named foo。若错误只说明在哪里失败、没说为什么（如某个值为 undefined），不算显而易见，仍需追溯。

六步流程：

1. 读错误：完整读完错误信息与堆栈，不跳过。
2. 复现：先建立快速、确定性的反馈回路，优先失败测试，也可用 curl、CLI harness 或 /tmp 下的一次性脚本；已有测试就先跑出 RED 再动源码。构建不出回路就停下，说明缺什么并向用户提问。
3. 初始假设：给出 2–3 个假设，每个必须附至少一条具体观测证据，「感觉不太对」不算证据。
4. 精简：剥离到最小失败用例，剩下的最后一块就是触发器。
5. 调查：从症状反向追踪调用链，用差分分析对比正常与异常状态；多组件系统在每个边界记录流入与流出数据，用 console.error() 而非可能被测试吞掉的 logger。
6. 修复并验证：先写失败测试再修；之后做绕过自检——想一个能绕开本次改动、仍触发同一坏状态的输入变体，若存在说明修错了层。

配套机制：git bisect 定位引入问题的提交；根因需至少两层证据（「这里失败是因为 X 为 null，而 X 为 null 是因为 Y 从未赋值」）；跨组件原因模糊时用竞争假设（ACH）排序验证；三次修复失败即停止并升级给用户，因为这通常是结构性问题。

适用边界与注意点

• 它是一套流程约束，不替代领域知识，也不替你读代码。
• 前提是能拿到可复现信号。没有反馈回路就强制停止，避免退化成模式匹配式的猜测。
• 明确反对抑制型修复：try/except: pass、关掉断言、特判复现输入都不算修复。
• 间歇性问题（竞态、死锁、资源耗尽）与防御性分层校验只给出索引，需查阅 specialized-patterns.md 等参考文件。