
关于
遇到任何 Bug、测试失败或意外行为时使用,在提出修复方案之前进行系统性调试
name: systematic-debugging description: "遇到任何 bug、测试失败或意外行为时使用,在提出修复方案之前" risk: unknown source: community date_added: "2026-02-27"
系统化调试
概述
随机修复浪费时间并产生新 bug。快速补丁掩盖了底层问题。
核心原则: 在尝试修复之前,始终找到根本原因。症状修复即为失败。
违反此流程的字面意义就是违反调试的精神。
铁律
未经根本原因调查,不得进行任何修复
如果你没有完成第一阶段,就不能提出修复方案。
何时使用
用于任何技术问题:
- 测试失败
- 生产环境 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
特别在以下情况使用:
- 时间压力下(紧急情况使猜测变得诱人)
- "只需一个快速修复"看起来很明显
- 你已经尝试了多次修复
- 之前的修复没有生效
- 你没有完全理解问题
不要跳过当:
- 问题看起来很简单(简单的 bug 也有根本原因)
- 你很赶时间(匆忙保证返工)
- 经理要求立即修复(系统化比反复折腾更快)
四个阶段
你必须完成每个阶段后才能进入下一个。
第一阶段:根本原因调查
在尝试任何修复之前:
-
仔细阅读错误信息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 记录行号、文件路径、错误代码
-
一致性复现
- 你能可靠地触发它吗?
- 确切的步骤是什么?
- 每次都会发生吗?
- 如果不可复现 → 收集更多数据,不要猜测
-
检查最近的更改
- 什么变化可能导致了这个问题?
- Git diff,最近的提交
- 新依赖、配置更改
- 环境差异
-
在多组件系统中收集证据
当系统有多个组件时(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 ✗)
-
追踪数据流
当错误深在调用栈中时:
参见此目录中的
root-cause-tracing.md获取完整的反向追踪技术。快速版本:
- 坏值从哪里来?
- 什么用坏值调用了这个?
- 继续向上追踪直到找到源头
- 在源头修复,而不是在症状处
第二阶段:模式分析
在修复之前找到模式:
-
找到工作示例
- 在同一代码库中找到类似的工作代码
- 什么类似的东西是正常工作的?
-
与参考对比
- 如果实现模式,完整阅读参考实现
- 不要略读 - 阅读每一行
- 在应用之前完全理解模式
-
识别差异
- 工作的和损坏的之间有什么不同?
- 列出每个差异,无论多小
- 不要假设"那不可能有影响"
-
理解依赖关系
- 这需要哪些其他组件?
- 什么设置、配置、环境?
- 它做了什么假设?
第三阶段:假设与测试
科学方法:
-
形成单一假设
- 清楚地陈述:"我认为 X 是根本原因,因为 Y"
- 写下来
- 要具体,不要模糊
-
最小化测试
- 做最小的可能更改来测试假设
- 一次一个变量
- 不要同时修复多个问题
-
继续之前验证
- 有效吗?是 → 第四阶段
- 没有效?形成新假设
- 不要在上面叠加更多修复
-
当你不知道时
- 说"我不理解 X"
- 不要假装知道
- 寻求帮助
- 进一步研究
第四阶段:实施
修复根本原因,而不是症状:
- 创建失败测试用例
- 最简单的可能复现
- 如果可能使用自动化测试
- 如果没有框架则使用一次性测试脚本
- 修复前必须有
- 使用
superpo
兼容工具
Claude CodeCursor
标签
前端开发