遇到任何 bug、测试失败或异常行为时使用，在提出修复方案之前执行

系统化调试概述核心原则：在尝试修复之前，务必先找到根本原因。只修症状就是失败。敷衍走流程等于违背调试的精神。铁律如果你还没完成第一阶段，就不能提出修复方案。何时使用用于任何技术问题：测试失败生产环境 bug 异常行为性能问题构建失败集成问题尤其在以下情况必须使用：时间紧迫（紧急情况最容易让人猜测式修复）觉得"一个小修改"就能搞定已经尝试了多种修复上一次修复没有生效你没有完全理解问题以下情况也不要跳过：问题看起来很简单（简单的 bug 也有根本原因）你很赶时间（越急越容易返工）领导要求立刻修好（系统化调试比反复尝试更快）四个阶段你必须完成每个阶段后才能进入下一个。第一阶段：根因调查在尝试任何修复之前： 1. 仔细阅读错误信息不要跳过错误或警告它们往往直接包含解决方案完整阅读堆栈跟踪记下行号、文件路径、错误码 2. 稳定复现你能可靠地触发它吗？具体的复现步骤是什么？每次都能复现吗？如果无法复现 → 收集更多数据，不要猜测 3. 检查近期变更什么变更可能导致了这个问题？ git diff、最近的提交新依赖、配置变更环境差异 4. 在多组件系统中收集证据当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：在提出修复方案之前，先添加诊断埋点：示例（多层系统）：由此可以看出：哪一层出了问题（secrets → workflow ✓, workflow → build ✗） 5. 跟踪数据流当错误发生在调用栈深处时：参见本目录下的 root cause tracing.md ，了解完整的反向追踪技术。简要版本：错误值从哪里产生的？谁用错误值调用了这里？持续向上追踪直到找到源头在源头修复，而不是在症状处修复第二阶段：模式分析先找到模式，再修复： 1. 找到可正常工作的示例在同一代码库中找到类似的正常代码有什么正常的代码与出问题的代码相似？ 2. 与参考实现对比如果是实现某个模式，完整阅读参考实现不要略读——逐行阅读在应用之前彻底理解该模式 3. 识别差异正常代码和出问题的代码之间有什么不同？列出每一个差异，无论多小不要假设"那不可能有影响" 4. 理解依赖关系这个功能需要哪些其他组件？需要哪些设置、配置、环境？它有哪些隐含假设？第三阶段：假设与验证科学方法： 1. 提出单一假设清晰地陈述："我认为 X 是根本原因，因为 Y" 写下来要具体，不要含糊 2. 最小化测试做出最小的改动来验证假设每次只改一个变量不要同时修复多个问题 3. 继续之前先验证生效了？是 → 进入第四阶段没生效？提出新假设不要在上面叠加更多修复 4. 当你不确定时说"我不理解 X" 不要假装自己知道寻求帮助做更多调研第四阶段：实施修复根本原因，而非症状： 1. 创建失败的测试用例最简化的复现尽可能用自动化测试没有测试框架就写一次性测试脚本修复前必须先有测试使用 test driven development 技能来编写规范的失败测试 2. 实施单一修复修复已定位的根本原因每次只改一处不做"顺便改改"的优化不捆绑重构 3. 验证修复测试现在通过了吗？其他测试没有被破坏吧？问题真的解决了吗？宣称成功之前，使用 verification before completion 技能 4. 如果修复不起作用停下来数一数：你已经尝试了几次修复？少于 3 次：回到第一阶段，用新信息重新分析 3 次或以上：停下来质疑架构（见下方第 5 步）没有经过架构讨论，不要尝试第 4 次修复 5. 如果 3 次以上修复都失败了：质疑架构以下模式表明存在架构问题：每次修复都暴露出新的共享状态/耦合/其他位置的问题修复需要"大规模重构"才能实现每次修复都在其他地方产生新的症状停下来质疑根本性问题：这个模式从根本上合理吗？我们是不是在"惯性驱动"下坚持了错误方案？应该重构架构还是继续修补症状？在尝试更多修复之前，和你的搭档讨论这不是假设失败——这是架构有误。红线——停下来，按流程走如果你发现自己在想： "先临时修一下，以后再排查" "试着改改 X 看看行不行" "一次性改多个地方，跑测试看看" "跳过测试，我手动验证" "大概是 X 的问题，让我修一下" "我不完全理解，但这应该能行" "模式说的是 X，但我换个方式用" "主要问题有这些：[未经调查就列出修复方案]" 没有追踪数据流就提出解决方案 "再试一次修复"（已经尝试了 2 次以上）每次修复都暴露出不同地方的新问题以上这些都意味着：停下来。回到第一阶段。如果 3 次以上修复都失败了：质疑架构（见第四阶段第 5 步）搭档发出的信号——说明你的方法不对留意这些提醒： "难道不是这样吗？"——你在没有验证的情况下做了假设 "它能告诉我们……吗？"——你应该先收集证据 "别猜了"——你在没有理解的情况下提出修复 "深入想想"——要质疑根本性问题，而不只是症状 "我们卡住了？"（沮丧的语气）——你的方法没有奏效当你看到这些信号时：停下来。回到第一阶段。常见借口借口现实 "问题很简单，不需要走流程" 简单问题也有根本原因。对于简单 bug，流程很快就能走完。 "紧急情况，没时间走流程" 系统化调试比反复猜测式修复更快。 "先试一下，再排查" 第一次修复就定下了基调。从一开始就做对。 "确认修复有效后再写测试" 没有测试的修复留不住。先写测试才能证明修复有效。 "一次修多个问题省时间" 无法隔离哪个生效了。还会引入新 bug。 "参考实现太长了，我自己改改" 一知半解必然出 bug。完整阅读。 "我看出问题了，让我修一下" 看到症状 ≠ 理解根因。 "再试一次"（在 2 次以上失败后） 3 次以上失败 = 架构问题。质疑模式，不要继续修。速查表阶段关键活动通过标准 1. 根因阅读错误、复现、检查变更、收集证据理解了什么出了问题以及为什么 2. 模式找到正常示例、对比识别出差异 3. 假设提出理论、最小化验证假设被验证或产生新假设 4. 实施创建测试、修复、验证 bug 已修复，测试通过当流程显示"找不到根因" 如果系统化排查后发现问题确实是环境相关、时序相关或外部因素导致的： 1. 你已经完成了流程 2. 记录你排查了什么 3. 实施适当的处理措施（重试、超时、错误提示） 4. 添加监控/日志以便后续排查但是： 95% 的"找不到根因"其实是排查不充分。辅助技术以下技术是系统化调试的组成部分，可在本目录中找到： root cause tracing.md 沿调用栈反向追踪 bug，找到最初的触发点 defense in depth.md 找到根因后，在多个层级添加校验 condition based waiting.md 用条件轮询替代硬编码等待时间

systematic-debugging