系统化调试

系统化调试#

中文说明：这是一个纯指令类技能，不含联网请求，也不会主动写文件或执行脚本；它指导 AI 在改代码之前先做根因调查，再最小化验证修复。附带 3 份参考文档和 1 个辅助脚本，按需阅读或使用。

概述#

核心原则： 在尝试修复之前，始终先找到根因。只修复症状就是失败。

违反本流程的字面要求，就是违反调试的精神。

铁律#

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

如果你还没有完成阶段 1，就不能提出修复方案。

何时使用#

适用于任何技术问题：

• 测试失败
• 生产环境中的 Bug
• 意外行为
• 性能问题
• 构建失败
• 集成问题

尤其要在以下情况使用：

• 时间紧迫时（紧急情况会让猜测变得诱人）
• “就快速修一下”看起来很明显时
• 你已经尝试过多次修复时
• 之前的修复没有起作用时
• 你还没有完全理解问题时

不要跳过，即使：

• 问题看起来很简单（简单的 Bug 也有根因）
• 你很着急（匆忙必然导致返工）
• 经理要求立刻修好（系统化比乱撞更快）

四个阶段#

你必须完成每个阶段，才能进入下一个阶段。

阶段 1：根因调查#

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们往往包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 记录行号、文件路径、错误码

2. 稳定复现

   • 你能可靠地触发它吗？
   • 确切的步骤是什么？
   • 每次都会发生吗？
   • 如果无法复现 → 收集更多数据，不要猜测

3. 检查最近的变更

   • 什么变更可能导致这个问题？
   • Git diff、最近的提交
   • 新增依赖、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统有多个组件时（CI → 构建 → 签名，API → 服务 → 数据库）：

   在提出修复方案之前，添加诊断埋点：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

   示例（多层系统）：

   # Layer 1: Workflow
   echo "=== Secrets available in workflow: ==="
   echo "IDENTITY: $([ -n "${IDENTITY:-}" ] && echo SET || echo UNSET)"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   printenv IDENTITY >/dev/null 2>&1 && echo "IDENTITY in environment" || echo "IDENTITY not in environment"
   
   # Layer 3: Signing script
   echo "=== Keychain state: ==="
   security list-keychains
   security find-identity -v
   
   # Layer 4: Actual signing
   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. 创建失败的测试用例

   • 尽可能最简单的复现
   • 如果可能，写成自动化测试
   • 如果没有测试框架，写一次性测试脚本
   • 修复之前必须有
   • 先写一个能稳定复现的失败测试（TDD 思路）

2. 实施单一修复

   • 针对已识别的根因
   • 一次只做一处变更
   • 不要做“顺便”的改进
   • 不要捆绑重构

3. 验证修复

   • 现在测试通过了吗？
   • 没有破坏其他测试？
   • 问题真的解决了吗？
   • 在宣布修复完成前，先做一次完整验证

4. 如果修复不起作用

   • 停下
   • 数一数：你已经尝试了几次修复？
   • 如果 < 3：回到阶段 1，用新信息重新分析
   • 如果 ≥ 3：停下，质疑架构（见下方第 5 步）
   • 没有架构层面的讨论，不要尝试第 4 次修复

5. 如果 3 次以上修复都失败了：质疑架构

   表明存在架构问题的模式：

   • 每次修复都在不同地方揭示出新的共享状态/耦合/问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都在别处制造新的症状

   停下，质疑根本假设：

   • 这个模式从根本上合理吗？
   • 我们是不是“纯粹出于惯性在坚持”？
   • 我们应该重构架构，还是继续修复症状？

   在尝试更多修复之前，与你的搭档讨论

   这不是一个失败的假设——这是一个错误的架构。

危险信号——停下并遵循流程#

如果你发现自己这样想：

• “先快速修一下，之后再调查”
• “就试着改一下 X，看看行不行”
• “同时做多处变更，然后跑测试”
• “跳过测试，我手动验证”
• “大概是 X，我来修一下”
• “我没有完全理解，但这可能有用”
• “模式说是 X，但我会换个方式改”
• “主要问题有这些：[未经调查就列出修复方案]”
• 在追踪数据流之前就提出解决方案
• “再试一次修复”（当已经试过 2 次以上）
• 每次修复都在不同地方揭示新问题

所有这些都意味着：停下。回到阶段 1。

如果 3 次以上修复都失败了： 质疑架构（见阶段 4.5）

你的搭档给出的“你做错了”的信号#

留意这些纠正：

• “那件事真的发生了吗？”——你没有验证就做了假设
• “这能让我们看到……吗？”——你本应添加证据收集
• “别猜了”——你在不理解的情况下提出修复方案
• “深入思考一下”——质疑根本假设，而不只是症状
• “我们卡住了？”（沮丧）——你的方法不起作用

当你看到这些时： 停下。回到阶段 1。

常见的合理化借口#

借口	现实
“问题很简单，不需要流程”	简单问题也有根因。对简单 Bug 来说流程很快。
“紧急情况，没时间走流程”	系统化调试比猜测-验证的乱撞更快。
“先试一下这个，然后再调查”	第一次修复就定下了模式。从一开始就做对。
“等确认修复有效后我再写测试”	未经测试的修复不会持久。先写测试才能证明它。
“同时做多个修复能节省时间”	无法隔离出哪个起了作用。会引入新 Bug。
“参考实现太长了，我照着改一下就行”	部分理解必然导致 Bug。完整阅读它。
“我看到问题了，让我来修”	看到症状 ≠ 理解根因。
“再试一次修复”（在 2 次以上失败后）	3 次以上失败 = 架构问题。质疑模式，不要再修。

快速参考#

阶段	关键活动	成功标准
1. 根因	阅读错误、复现、检查变更、收集证据	理解是什么（WHAT）和为什么（WHY）
2. 模式	找到可用示例、对比	找出差异
3. 假设	形成理论、最小化验证	得到确认或形成新假设
4. 实施	创建测试、修复、验证	Bug 解决，测试通过

当流程揭示“没有根因”时#

如果系统化调查揭示问题确实是环境性的、依赖时序的或外部的：

1. 你已经完成了流程
2. 记录你调查了什么
3. 实施适当的处理（重试、超时、错误信息）
4. 添加监控/日志，以便将来调查

但是： 95% 的“没有根因”案例都是调查不完整。

辅助技术#

这些技术是系统化调试的一部分，可在本目录中找到：

• root-cause-tracing.md - 沿调用栈反向追踪 Bug，找到最初的触发点
• defense-in-depth.md - 找到根因后，在多个层次添加校验
• condition-based-waiting.md - 用条件轮询替代任意超时