遇到任何bug、测试失败或异常行为时必须遵循的调试方法论。包含四阶段流程（根因调查→模式分析→假设验证→实施修复）、铁律「不做根因调查不许提修复方案」、DOT格式流程图、常见借口对照表。适用生产环境bug修复、性能问题排查、集成问题诊断等场景。

系统化调试：根因调查四阶段方法论

【适用场景】

Step 1：生产环境Bug修复

当生产环境出现bug时，系统化调试确保找到真正根因而非症状。

Step 2：测试失败排查

当测试失败时，在提出修复方案之前必须完成根因调查阶段。

Step 3：性能问题诊断

当系统性能下降时，遵循四阶段方法找到性能瓶颈根因。

Step 4：集成问题排查

当多组件系统出现集成问题时，收集边界证据定位断裂点。

【操作步骤】

第一阶段：根因调查 1. 仔细阅读错误信息和堆栈跟踪 2. 稳定复现问题，记录复现步骤 3. 检查近期变更（git diff、配置变更） 4. 在多组件系统中添加诊断埋点收集证据

第二阶段：模式分析 1. 找到可正常工作的类似代码 2. 与参考实现逐行对比 3. 识别正常与异常代码的差异 4. 理解依赖关系和隐含假设

第三阶段：假设与验证 1. 提出单一具体假设 2. 做出最小改动验证假设 3. 生效则进入第四阶段，无效则提出新假设

第四阶段：实施 1. 创建失败的测试用例 2. 实施单一修复（根因，非症状） 3. 验证修复有效 4. 3次以上失败则质疑架构

【代码模板】

多组件诊断埋点 ```bash

第1层：工作流

echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"

第2层：构建脚本

env | grep IDENTITY || echo "IDENTITY not found"

第3层：签名脚本

security list-keychains security find-identity -v

第4层：实际签名

codesign --sign "$IDENTITY" --verbose=4 "$APP" ```

红线规则 遇到以下想法时必须停下来回到第一阶段： - 「先临时修一下」 - 「试着改改X看看行不行」 - 「我不太理解但应该能行」 - 3次以上修复失败

【复盘要点】

核心铁律：不做根因调查，不许提修复方案

成功标准：bug已修复，测试通过

速查表：

阶段	关键活动	通过标准
根因	阅读错误、复现、检查变更	理解问题及原因
模式	找正常示例、对比	识别差异
假设	提出理论、验证	假设被验证
实施	测试、修复、验证	bug已修复

来源：GitHub https://github.com/jnmetacode/superpowers-zh/blob/main/skills/systematic-debugging/SKILL.md