Systematic Debugging

系统化调试

概述

随意修复浪费时间，并制造新 bug。快速补丁掩盖底层问题。

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

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

铁律

没有根因调查就不要谈修复

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

何时使用

适用于任何技术问题：

• 测试失败
• 生产 bug
• 异常行为
• 性能问题
• 构建失败
• 集成问题

尤其在这些情况下使用：

• 时间压力大（紧急情况下容易诱使你猜测）
• "就这一处快修一下" 看起来显而易见
• 你已经试过多次修复
• 之前的修复无效
• 你并不完全理解问题

不要在以下情况下跳过：

• 问题看似简单（简单 bug 也有根因）
• 你在赶时间（赶时间一定要返工）
• 经理要求"现在就修"（系统化比乱撞更快）

四个阶段

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

阶段 1：根因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

• 不要跳过错误或警告
• 它们经常含有确切答案
• 完整阅读 stack trace
• 记下行号、文件路径、错误码

1. 稳定复现

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

1. 检查近期变更

• 什么变化可能导致这个？
• Git diff、最近的 commits
• 新依赖、配置变更
• 环境差异

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

当系统有多个组件时（CI → build → 签名，API → service → 数据库）：

在提议修复前，加诊断埋点： ``` 对每个组件边界：

• 记录进入组件的数据
• 记录离开组件的数据
• 验证环境/配置是否传播
• 检查每层的状态

跑一次以收集证据，找出在哪儿断 然后分析证据，识别失败的组件 然后调查那个具体组件 ```

示例（多层系统）： ```bash # 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 ✗）

1. 追踪数据流

当错误深处于调用栈中：

完整的反向追踪技术见本目录的 root-cause-tracing.md。

简版：

• 坏值从哪儿来？
• 谁用坏值调用了它？
• 一路追到源头
• 在源头修，而不是症状处

阶段 2：模式分析

在修复前先找到模式：

1. 找有效示例

• 在同代码库中定位类似的有效代码
• 哪些"和坏的相似"的东西是工作的？

1. 对照参考实现

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

1. 找出差异

• 工作的 vs 坏的之间有什么不同？
• 列出每一处差异，再小也列
• 不要假设"这不可能要紧"

1. 理解依赖

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

阶段 3：假设与验证

科学方法：

1. 形成一个假设

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

1. 以最小变更测试

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

1. 继续前先验证

• 有效？是 → 阶段 4
• 无效？形成新假设
• 不要在上面继续叠加修复

1. 当你不知道时

• 说 "I don't understand X"
• 不要假装知道
• 求助
• 多研究

阶段 4：实施

修根因，不修症状：

1. 建立可靠的复现步骤

• 最简化的复现路径
• 默认：可手动复现的清晰步骤，或一次性脚本
• 仅当任务/项目明确要求测试覆盖时，才写自动化测试（先红后绿）
• 修复前必须能稳定复现

1. 实施单一修复

• 解决识别出的根因
• 一次只改一处
• 不要"顺手"改其他
• 不要捆绑重构

1. 验证修复

• 复现步骤现在不再触发问题？
• 跑项目已有的静态检查（类型检查 / lint / 构建），未引入新错误？
• 如有自动化测试，相关测试通过且未破坏其他？

1. 如果修复无效

• 停下
• 数一数：你试过多少次修复？
• 若 < 3：回到阶段 1，用新信息重新分析
• 若 ≥ 3：停下并质疑架构（下文步骤 5）
• 不要在无架构讨论的情况下尝试第 4 次修复

1. 若 3 次以上修复都失败：质疑架构

指向架构问题的模式：

• 每次修复都在不同地方暴露新的共享状态/耦合/问题
• 修复要求"大规模重构"才能实现
• 每次修复都在别处产生新症状

停下并质疑根本：

• 这个模式根本上合理吗？
• 我们是不是"靠惯性硬撑"？
• 应不应该重构架构而非继续修症状？

在尝试更多修复前与你的协作伙伴讨论

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

红色信号 - 停下并遵循流程

如果你抓到自己在想：

• "先快修一下，回头调查"
• "试着改 X 看看行不行"
• "加多个变更，看结果"
• "懒得复现，我猜一下就改"
• "应该是 X，让我修了它"
• "我没完全理解但这可能行"
• "模式说 X，但我改一下用"
• "这是主要问题：[未经调查就列修复]"
• 在追踪数据流之前提出解决方案
• "再试一次"（已经试过 2 次以上）
• 每次修复都在别处暴露新问题

以上所有都意味着：停下，回到阶段 1。

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

你的协作伙伴提示你"方法错了"的信号

留意这些重定向：

• "Is that not happening?" - 你没验证就假设了
• "Will it show us...?" - 你本应加证据收集
• "Stop guessing" - 你没理解就提议修复
• "Ultrathink this" - 质疑根本，而非只看症状
• "We're stuck?"（沮丧地） - 你的方法不奏效

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

常见自我合理化

| 借口 | 现实 | |--------|---------| | "问题简单，不用流程" | 简单问题也有根因。流程对简单 bug 很快。 | | "紧急，没时间走流程" | 系统化调试比瞎试更快。 | | "先这样修，回头再查" | 第一次修复定下基调。一开始就做对。 | | "复现都没做就直接修" | 没复现的修复站不住。能可靠复现才能证明修对了。 | | "一次修多个省时间" | 没法隔离哪个起作用。导致新 bug。 | | "参考太长，我变通一下" | 部分理解保证有 bug。完整地读。 | | "我看见问题了，让我修" | 看到症状 ≠ 理解根因。 | | "再修一次"（已 2 次以上失败） | 3 次以上失败 = 架构问题。质疑模式，不要继续修。 |

速查

| 阶段 | 关键活动 | 成功标准 | |-------|---------------|------------------| | 1. 根因 | 读错误、复现、查变更、收证据 | 理解发生了什么、为什么 | | 2. 模式 | 找有效示例、对比 | 识别差异 | | 3. 假设 | 形成理论、最小测试 | 确认或新假设 | | 4. 实施 | 建立复现、修、验证 | bug 解决、复现不再触发、静态检查通过 |

当流程显示"没有根因"

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

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

但： 95% 的"没有根因"案例实际是调查不彻底。

支撑技术

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

• root-cause-tracing.md - 沿调用栈反向追踪 bug 到原始触发点
• defense-in-depth.md - 找到根因后，在多个层添加验证
• condition-based-waiting.md - 用条件轮询替换任意 timeout

真实世界影响

来自调试会话：

• 系统化方法：15-30 分钟修完
• 随意修复方法：2-3 小时来回折腾
• 一次修对率：95% vs 40%
• 引入新 bug：接近零 vs 常见

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MySwallow
• Source: MySwallow/superpowers-lite
• License: MIT

Install and usage instructions live in the source repository linked above.