---

name: systematic-debugging description: "遇到任何 bug、测试失败或意外行为时使用，在提出修复方案之前" risk: unknown source: community date_added: "2026-02-27"

系统化调试

概述

随机修复浪费时间并产生新 bug。快速补丁掩盖了底层问题。

核心原则： 在尝试修复之前，始终找到根本原因。症状修复即为失败。

违反此流程的字面意义就是违反调试的精神。

铁律

未经根本原因调查，不得进行任何修复

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

何时使用

用于任何技术问题：

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

特别在以下情况使用：

• 时间压力下（紧急情况使猜测变得诱人）
• "只需一个快速修复"看起来很明显
• 你已经尝试了多次修复
• 之前的修复没有生效
• 你没有完全理解问题

不要跳过当：

• 问题看起来很简单（简单的 bug 也有根本原因）
• 你很赶时间（匆忙保证返工）
• 经理要求立即修复（系统化比反复折腾更快）

四个阶段

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

第一阶段：根本原因调查

在尝试任何修复之前：

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: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   echo "=== Env vars in build script: ==="
   env | grep IDENTITY || 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 获取完整的反向追踪技术。

   快速版本：

   • 坏值从哪里来？
   • 什么用坏值调用了这个？
   • 继续向上追踪直到找到源头
   • 在源头修复，而不是在症状处

第二阶段：模式分析

在修复之前找到模式：

1. 找到工作示例

   • 在同一代码库中找到类似的工作代码
   • 什么类似的东西是正常工作的？

2. 与参考对比

   • 如果实现模式，完整阅读参考实现
   • 不要略读 - 阅读每一行
   • 在应用之前完全理解模式

3. 识别差异

   • 工作的和损坏的之间有什么不同？
   • 列出每个差异，无论多小
   • 不要假设"那不可能有影响"

4. 理解依赖关系

   • 这需要哪些其他组件？
   • 什么设置、配置、环境？
   • 它做了什么假设？

第三阶段：假设与测试

科学方法：

1. 形成单一假设

   • 清楚地陈述："我认为 X 是根本原因，因为 Y"
   • 写下来
   • 要具体，不要模糊

2. 最小化测试

   • 做最小的可能更改来测试假设
   • 一次一个变量
   • 不要同时修复多个问题

3. 继续之前验证

   • 有效吗？是 → 第四阶段
   • 没有效？形成新假设
   • 不要在上面叠加更多修复

4. 当你不知道时

   • 说"我不理解 X"
   • 不要假装知道
   • 寻求帮助
   • 进一步研究

第四阶段：实施

修复根本原因，而不是症状：

1. 创建失败测试用例
   • 最简单的可能复现
   • 如果可能使用自动化测试
   • 如果没有框架则使用一次性测试脚本
   • 修复前必须有
   • 使用 superpo