systematic-debugging

# Systematic Debugging / 系统化调试 ## 概览 随机修复浪费时间并制造新的 bug。快速的补丁掩盖了底层问题。 **核心原则：** 在尝试任何修复之前，必须找到根因。只修症状就是失败。 **违反此流程的字面意义，就是违反调试的精神。** ## 铁律 ``` 没有先进行根因调查，就不做任何修复 ``` 如果你没有完成阶段 1，你不能提出修复方案。 ## 何时使用 用于任何技术问题： - 测试失败 - 生产环境的 bug - 意外行为 - 性能问题 - 构建失败 - 集成问题 **尤其在这些情况下使用：** - 在时间压力下（紧急情况让猜测显得诱人） - "就一个小修复"看起来很明显 - 你已经尝试了多次修复 - 上一次修复没生效 - 你并没有完全理解这个问题 **不要在这些情况下跳过：** - 问题看起来简单（简单的 bug 也有根因） - 你很赶时间（赶工必然导致返工） - 经理要求现在就修好（系统化比瞎折腾更快） ## 四个阶段 你必须完成每个阶段才能进入下一个。 ### 阶段 1：根因调查 **在尝试任何修复之前：** 1. **仔细阅读错误信息** - 不要跳过错误或警告 - 它们通常包含确切的解决方案 - 完整阅读堆栈追踪 - 记下行号、文件路径、错误码 2. **稳定复现** - 你能可靠地触发它吗？ - 确切的步骤是什么？ - 每次都发生吗？ - 如果无法复现 → 收集更多数据，不要猜 3. **检查最近变更** - 什么变了可能导致了这个问题？ - Git diff、最近的提交 - 新依赖、配置变更 - 环境差异 4. **在多组件系统中收集证据** **当系统有多个组件时（CI → build → signing，API → service → database）：** **在提出修复之前，添加诊断插桩：** ``` 对每个组件边界： - 记录进入组件的数据 - 记录离开组件的数据 - 验证环境/配置的传递 - 检查每一层的状态 运行一次以收集证据，显示它在哪里中断 然后分析证据以识别失败的组件 然后调查那个具体组件 ``` **示例（多层系统）：** ```bash # 第 1 层：工作流 echo "=== Secrets available in workflow: ===" echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" # 第 2 层：构建脚本 echo "=== Env vars in build script: ===" env | grep IDENTITY || echo "IDENTITY not in environment" # 第 3 层：签名脚本 echo "=== Keychain state: ===" security list-keychains security find-identity -v # 第 4 层：实际签名 codesign --sign "$IDENTITY" --verbose=4 "$APP" ``` **这揭示：** 哪一层失败（secrets → workflow ✓，workflow → build ✗） 5. **追踪数据流** **当错误深在调用栈中时：** 参见本目录下的 `root-cause-tracing.md`，了解完整的反向追踪技术。 **快速版本：** - 错误值源自哪里？ - 是什么用错误值调用了它？ - 持续向上追踪直到找到源头 - 在源头修复，而不是在症状处 ### 阶段 2：模式分析 **在修复之前先找到模式：** 1. **找到可用的示例** - 在同一个代码库中定位相似的可用代码 - 有什么与坏掉的相似的东西是可用的？ 2. **与参考对比** - 如果在实现某个模式，完整地阅读参考实现 - 不要略读——逐行阅读 - 在应用之前充分理解该模式 3. **识别差异** - 可用的和坏掉的之间有什么不同？ - 列出每一个差异，无论多小 - 不要假设"那不重要" 4. **理解依赖** - 这还需要哪些其他组件？ - 需要什么设置、配置、环境？ - 它做了哪些假设？ ### 阶段 3：假设与测试 **科学方法：** 1. **形成单一假设** - 清晰地陈述："我认为 X 是根因，因为 Y" - 写下来 - 要具体，不要含糊 2. **最小化测试** - 做最小的可能改动来测试假设 - 一次只改一个变量 - 不要同时修复多件事 3. **在继续之前验证** - 生效了？是 → 阶段 4 - 没生效？形成新的假设 - 不要在上面叠加更多修复 4. **当你不知道时** - 说"我不理解 X" - 不要假装知道 - 请求帮助 - 做更多研究 ### 阶段 4：实现 **修复根因，而不是症状：** 1. **创建失败的测试用例** - 最简单的可能复现 - 尽可能用自动化测试 - 没有框架时用一次性测试脚本 - 修复前必须有 - 使用 `superpowers:test-driven-development` skill 来编写规范的失败测试 2. **实现单一修复** - 针对已识别的根因 - 一次一个改动 - 没有"顺手"的改进 - 不打包重构 3. **验证修复** - 测试现在通过了？ - 没有破坏其他测试？ - 问题确实解决了？ 4. **如果修复没生效** - 停下 - 计数：你已经尝试了多少次修复？ - 如果 < 3：回到阶段 1，用新信息重新分析 - **如果 ≥ 3：停下并质疑架构（下面的步骤 5）** - 在没有架构讨论之前不要尝试第 4 次修复 5. **如果 3 次以上修复失败：质疑架构** **指示架构问题的模式：** - 每次修复都揭示新的共享状态/耦合/在不同地方的问题 - 修复需要"大规模重构"才能实现 - 每次修复都在别处制造新的症状 **停下并质疑根本：** - 这个模式从根本上合理吗？ - 我们是不是"纯粹出于惯性在硬撑"？ - 我们应该重构架构，还是继续修症状？ **在尝试更多修复之前与你的 human partner 讨论** 这不是失败的假设——这是错误的架构。 ## 危险信号（Red Flags）- 停下并遵循流程 如果你发现自己在想： - "先临时修一下，以后再调查" - "就试着改一下 X 看看能不能用" - "加多个改动，跑测试" - "跳过测试，我手动验证" - "大概是 X，让我修一下" - "我没有完全理解，但这可能有效" - "模式说 X，但我用另一种方式适配" - "主要问题是这些：[没调查就列出修复方案]" - 在追踪数据流之前就提出解决方案 - **"再试一次修复"（当已经尝试 2 次以上时）** - **每次修复都在不同地方揭示新问题** **以上全部意味着：停下。回到阶段 1。** **如果 3 次以上修复失败：** 质疑架构（见阶段 4.5） ## 你的 human partner 示意你做错了 **注意这些纠正：** - "那没发生吗？" - 你假设了却没有验证 - "它会向我们展示……吗？" - 你本应该添加证据收集 - "别猜了" - 你在不理解的情况下提出修复 - "深度思考一下" - 质疑根本，而不只是症状 - "我们卡住了？"（沮丧地）- 你的方法不奏效 **当你看到这些时：** 停下。回到阶段 1。 ## 常见合理化借口 | 借口 | 现实 | |--------|---------| | "问题很简单，不需要流程" | 简单问题也有根因。流程对简单 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`** - 用条件轮询替代随意超时 **相关 skills：** - **superpowers:test-driven-development** - 用于创建失败的测试用例（阶段 4，步骤 1） - **superpowers:verification-before-completion** - 在宣称成功之前验证修复有效 ## 真实世界的影响 来自调试会话： - 系统化方法：15-30 分钟修复 - 随机修复方法：2-3 小时瞎折腾 - 一次修复成功率：95% vs 40% - 引入的新 bug：几乎为零 vs 常见