概述
Systematic Debugging 是一套用于排查技术问题的四阶段调试框架。其出发点很直接：随机修复浪费时间并制造新缺陷，快速打补丁会掩盖底层问题。
核心原则是：在尝试修复之前，务必先找到根因。只修症状属于失败。资料强调，违反这一流程的字面要求，就是违反调试的精神。
铁律
没有根因调查之前不得修复。如果尚未完成第一阶段，就不能提出修复方案。
适用时机
适用于任何技术问题，包括测试失败、生产环境缺陷、异常行为、性能问题、构建失败、集成问题。
尤其应在以下情况下使用：时间压力大（紧急情况容易诱发猜测）、“只需要快速改一下”看起来很明显、已经尝试过多次修复、上一次修复没有生效、你对问题理解不充分。
不应跳过的情形包括：问题看起来很简单（简单缺陷也有根因）、你很着急（赶工必然导致返工）、管理者要求立刻修好（系统化方法比反复试错更快）。
四个阶段
每个阶段必须完成后才能进入下一阶段。
阶段一：根因调查
在尝试任何修复之前：
- 仔细阅读错误信息：不要跳过错误或警告，它们往往包含确切的解决方案；完整阅读堆栈跟踪，记录行号、文件路径和错误码。
- 稳定复现：能否可靠触发？确切的步骤是什么？是否每次都发生？若无法复现，应收集更多数据而不是猜测。
- 检查近期变更：有什么变更可能导致该问题？包括 git diff、近期提交、新依赖、配置变更、环境差异。
- 在多组件系统中采集证据：当系统涉及多个组件（如 CI → 构建 → 签名，API → 服务 → 数据库）时，在提出修复前先加入诊断埋点。对每个组件边界记录进入组件的数据、离开组件的数据，验证环境与配置的传递，检查每一层的状态。运行一次以采集证据，显示在哪一层失败，然后分析证据定位问题组件，再调查该组件。资料给出多层系统示例：在 workflow 中打印密钥是否可用、在构建脚本中检查环境变量、检查钥匙串状态、执行实际签名，从而揭示哪一层失败。
- 追踪数据流：当错误位于调用栈深处时，参考 root-cause-tracing 技巧进行反向追踪。快速版做法是：坏值从哪里产生？谁用坏值调用了这里？持续向上追踪直到找到源头，在源头修复而不是在症状处修复。
阶段二：模式分析
在修复之前先找模式：寻找可用的示例，在同一代码库中定位类似的可运行代码；与参考实现对照，如果是在实现某种模式，要完整阅读参考实现，不要略读，逐行读完；识别差异，列出可用代码与故障代码之间的每一项差异，无论多小，不要假设“这不重要”；理解依赖，该组件需要哪些其他组件、设置、配置和环境，它做了哪些假设。
阶段三：假设与验证
采用科学方法：提出单一假设，明确写出“我认为 X 是根因，因为 Y”，要具体而非含糊；最小化测试，做尽可能小的改动来验证假设，一次只改一个变量，不要同时修多个地方；继续之前先验证，成功则进入阶段四，失败则形成新假设，不要在原有基础上叠加更多修复。
当你确实不懂时，应说“我不理解 X”，不要假装知道，可以求助或继续研究。
阶段四：实施
修复根因而非症状：
- 创建失败测试用例：最简单可复现的用例，尽可能自动化测试；若没有测试框架，可写一次性测试脚本。修复前必须有此用例。资料指向 testing/test-driven-development 技能以编写规范。
- 实施单一修复：针对已识别的根因，一次只做一个改动，不要顺手做“既然来了就改一下”的优化，不要夹带重构。
- 验证修复：测试现在是否通过？是否有其他测试被破坏？问题是否真正解决？
若修复无效：先停止，统计已尝试的修复次数。少于 3 次，带着新信息返回阶段一重新分析；大于等于 3 次，停止并质疑架构，不要在未讨论架构的情况下尝试第 4 次修复。
三次以上修复失败：质疑架构
架构问题的模式包括：每次修复都在不同地方暴露新的共享状态、耦合或问题；修复需要“大规模重构”才能实现；每次修复都会在别处制造新症状。此时应停止并质疑根本假设：这个模式是否根本合理？我们是否只是靠惯性在坚持？应该重构架构还是继续修症状？在尝试更多修复之前，与人类搭档讨论。这不是假设失败，而是架构错误。
红旗信号：停止并遵循流程
如果发现自己有以下想法，应立即停止并返回阶段一：
- “先快速修一下，之后再调查”
- “先改一下 X 看看行不行”
- “一次加多个改动，然后跑测试”
- “跳过测试，我手动验证”
- “大概是 X，我把它修了”
- “我没完全理解，但这样可能行”
- “模式说是 X，但我换个方式改”
- “主要问题如下：[未调查就列出修复]”
- 在追踪数据流之前就提出解决方案
- “再试一次修复”（已经试过两次以上）
- 每次修复都在不同地方暴露新问题
若三次以上修复失败，应质疑架构。
人类搭档的提示信号
注意这些纠偏信号：“是不是没发生？”表示你未经核实就假设了；“能让我们看到……吗？”表示你应该加入证据采集；“别猜了”表示你在不理解的情况下提出修复；“深入思考一下”表示要质疑根本假设而非只看症状；“我们卡住了？”（带有挫败感）表示你的方法行不通。看到这些信号时，停止并返回阶段一。
常见借口与现实
资料列出常见错误想法及其现实：
- “问题很简单，不需要流程”——简单问题也有根因，流程对简单缺陷很快。
- “紧急情况，没时间走流程”——系统化调试比反复猜测试错更快。
- “先试这个，然后再调查”——第一次修复会定下模式，从一开始就要做对。
- “等确认修复有效后再写测试”——未经测试的修复不可靠，先写测试才能证明。
- “一次改多个地方省时间”——无法隔离哪个改动起了作用，还会引入新缺陷。
- “参考太长，我按自己的方式改模式”——部分理解必然导致缺陷，要完整阅读。
- “我看到问题了，让我修”——看到症状不等于理解根因。
- “再试一次修复”（在两次以上失败后）——三次以上失败说明是架构问题，应质疑模式而不是继续修。
快速参考
阶段一 根因：阅读错误、复现、检查变更、采集证据；成功标准是理解是什么和为什么。 阶段二 模式：寻找可用示例、对比；成功标准是识别差异。 阶段三 假设：形成理论、最小化测试；成功标准是确认或形成新假设。 阶段四 实施：创建测试、修复、验证；成功标准是缺陷解决、测试通过。
当流程显示“没有根因”时
如果系统化调查后发现问题确实属于环境性、时序相关或外部因素：流程已完成，记录你调查了什么，实施相应的处理（重试、超时、错误信息），并为未来调查添加监控和日志。但资料提醒，95% 的“没有根因”案例其实是调查不完整。
与其他技能的集成
该技能与以下内容配合：root-cause-tracing（如何沿调用栈反向追踪）、defense-in-depth（在找到根因后添加校验）、testing/condition-based-waiting（替换阶段二识别出的超时）、verification-before-completion（在宣称成功前验证修复有效）。
实际影响
资料引用调试会话数据：系统化方法 15 到 30 分钟修复，随机修复方法 2 到 3 小时反复试错；一次修复成功率 95% 对 40%；引入的新缺陷接近零，而随机方式则很常见。