| name | systematic-debugging |
| description | 当遇到任何 bug、测试失败或意外行为时使用,在提出修复方案之前 |
系统化调试
概述
随机修复浪费时间并制造新 bug。快速补丁掩盖潜在问题。
核心原则: 在尝试修复之前始终找到根本原因。修复症状是失败。
违反此流程的字面意思就是违反调试的精神。
铁律
没有根本原因调查就不能修复
如果你还没有完成阶段 1,就不能提出修复方案。
何时使用
用于任何技术问题:
- 测试失败
- 生产环境 bug
- 意外行为
- 性能问题
- 构建失败
- 集成问题
特别在以下情况使用:
- 时间压力下(紧急情况使猜测变得诱人)
- "只是一个快速修复"看起来很明显
- 你已经尝试了多种修复
- 之前的修复不起作用
- 你不完全理解问题
不要跳过:
- 问题看起来简单(简单的 bug 也有根本原因)
- 你很着急(匆忙保证返工)
- 经理要求立即修复(系统化比盲目尝试更快)
四个阶段
你必须完成每个阶段才能进入下一个。
阶段 1:根本原因调查
在尝试任何修复之前:
-
仔细阅读错误信息
- 不要跳过错误或警告
- 它们通常包含确切的解决方案
- 完整阅读堆栈跟踪
- 记录行号、文件路径、错误代码
-
一致地复现
- 你能可靠地触发它吗?
- 确切的步骤是什么?
- 每次都发生吗?
- 如果不可复现 → 收集更多数据,不要猜测
-
检查最近的更改
- 什么变化可能导致这个问题?
- Git diff、最近的提交
- 新依赖、配置更改
- 环境差异
-
在多组件系统中收集证据
当系统有多个组件时(CI → 构建 → 签名,API → 服务 → 数据库):
在提出修复之前,添加诊断埋点:
对于每个组件边界:
- 记录进入组件的数据
- 记录离开组件的数据
- 验证环境/配置传播
- 检查每层的状态
运行一次收集证据,显示在哪里中断
然后分析证据识别故障组件
然后调查该特定组件
示例(多层系统):
echo "=== Secrets available in workflow: ==="
echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
echo "=== Env vars in build script: ==="
env | grep IDENTITY || echo "IDENTITY not in environment"
echo "=== Keychain state: ==="
security list-keychains
security find-identity -v
codesign --sign "$IDENTITY" --verbose=4 "$APP"
这揭示: 哪层失败(secrets → workflow ✓, workflow → build ✗)
-
追踪数据流
当错误在调用栈深处时:
请参阅本目录中的 root-cause-tracing.md 了解完整的向后追踪技术。
快速版本:
- 错误值从哪里来?
- 谁用错误值调用了这个?
- 继续向上追踪直到找到源头
- 在源头修复,而非症状
阶段 2:模式分析
在修复之前找到模式:
-
找到工作示例
- 在同一代码库中找到类似的正常工作代码
- 有什么与损坏的相似但正常工作?
-
与参考对比
- 如果实现模式,完整阅读参考实现
- 不要略读 - 阅读每一行
- 在应用前完全理解模式
-
识别差异
- 正常工作和损坏之间有什么不同?
- 列出每个差异,无论多小
- 不要假设"那不可能重要"
-
理解依赖
- 这需要什么其他组件?
- 什么设置、配置、环境?
- 它做什么假设?
阶段 3:假设和测试
科学方法:
-
形成单一假设
- 清楚陈述:"我认为 X 是根本原因,因为 Y"
- 写下来
- 要具体,不要模糊
-
最小化测试
- 做最小的可能更改来测试假设
- 一次一个变量
- 不要同时修复多个东西
-
验证后再继续
- 起作用了吗?是 → 阶段 4
- 没起作用?形成新假设
- 不要在上面添加更多修复
-
当你不知道时
- 说"我不理解 X"
- 不要假装知道
- 寻求帮助
- 更多研究
阶段 4:实现
修复根本原因,而非症状:
-
创建失败测试用例
- 最简单的可能复现
- 尽可能自动化测试
- 如果没有框架则用一次性测试脚本
- 修复前必须有
- 使用
zjkycode:test-driven-development 技能编写正确的失败测试
-
实现单一修复
- 解决识别的根本原因
- 一次一个更改
- 没有"顺便"改进
- 没有捆绑重构
-
验证修复
- 测试现在通过了吗?
- 没有其他测试被破坏?
- 问题真的解决了?
-
如果修复不起作用
- 停止
- 计数:你尝试了多少次修复?
- 如果 < 3:返回阶段 1,用新信息重新分析
- 如果 ≥ 3:停止并质疑架构(下面的步骤 5)
- 不要在没有架构讨论的情况下尝试第 4 次修复
-
如果 3 次以上修复失败:质疑架构
表明架构问题的模式:
- 每次修复都在不同地方揭示新的共享状态/耦合/问题
- 修复需要"大规模重构"才能实现
- 每次修复在其他地方创建新症状
停止并质疑基础:
- 这个模式根本上合理吗?
- 我们是否"纯粹靠惯性坚持"?
- 我们应该重构架构 vs. 继续修复症状?
在尝试更多修复之前与你的伙伴讨论
这不是失败的假设 - 这是错误的架构。
危险信号 - 停止并遵循流程
如果你发现自己在想:
- "暂时快速修复,以后再调查"
- "只是尝试改变 X 看看是否有效"
- "添加多个更改,运行测试"
- "跳过测试,我会手动验证"
- "可能是 X,让我修复那个"
- "我不完全理解但这可能有效"
- "模式说 X 但我会不同地适应"
- "这是主要问题:[列出修复而没有调查]"
- 在追踪数据流之前提出解决方案
- "再尝试一次修复"(当已经尝试 2 次以上)
- 每次修复在不同地方揭示新问题
所有这些都意味着:停止。返回阶段 1。
如果 3 次以上修复失败: 质疑架构(见阶段 4.5)
你的伙伴发出的错误信号
注意这些重定向:
- "那没有发生吗?" - 你没有验证就假设了
- "它会显示我们...吗?" - 你应该添加证据收集
- "停止猜测" - 你在没有理解的情况下提出修复
- "深度思考这个" - 质疑基础,不只是症状
- "我们卡住了?"(沮丧)- 你的方法不起作用
当你看到这些:停止。返回阶段 1。
常见合理化
| 借口 | 现实 |
|---|
| "问题很简单,不需要流程" | 简单问题也有根本原因。流程对简单 bug 很快。 |
| "紧急情况,没时间走流程" | 系统化调试比猜测检查的盲目尝试更快。 |
| "先尝试这个,然后调查" | 第一次修复设定模式。从一开始就做对。 |
| "我会在确认修复有效后写测试" | 未测试的修复不会持久。测试先证明它。 |
| "一次多个修复节省时间" | 无法隔离什么有效。导致新 bug。 |
| "参考太长,我会适应模式" | 部分理解保证 bug。完整阅读。 |
| "我看到问题了,让我修复它" | 看到症状 ≠ 理解根本原因。 |
| "再尝试一次修复"(2 次以上失败后) | 3 次以上失败 = 架构问题。质疑模式,不要再修复。 |
快速参考
| 阶段 | 关键活动 | 成功标准 |
|---|
| 1. 根本原因 | 阅读错误、复现、检查更改、收集证据 | 理解什么和为什么 |
| 2. 模式 | 找到工作示例、对比 | 识别差异 |
| 3. 假设 | 形成理论、最小化测试 | 确认或新假设 |
| 4. 实现 | 创建测试、修复、验证 | Bug 解决,测试通过 |
当流程揭示"没有根本原因"
如果系统化调查揭示问题确实是环境、时序依赖或外部的:
- 你已完成流程
- 记录你调查了什么
- 实现适当的处理(重试、超时、错误消息)
- 添加监控/日志用于未来调查
但是: 95% 的"没有根本原因"案例是不完整的调查。
支持技术
这些技术是系统化调试的一部分,可在本目录中找到:
root-cause-tracing.md - 通过调用栈向后追踪 bug 以找到原始触发点
defense-in-depth.md - 在找到根本原因后在多层添加验证
condition-based-waiting.md - 用条件轮询替换任意超时
相关技能:
- zjkycode:test-driven-development - 用于创建失败测试用例(阶段 4,步骤 1)
- zjkycode:verification-before-completion - 在声称成功之前验证修复有效
实际影响
来自调试会话:
- 系统化方法:15-30 分钟修复
- 随机修复方法:2-3 小时的盲目尝试
- 首次修复率:95% vs 40%
- 引入新 bug:接近零 vs 常见