诊断疑难 bug

对付硬 bug 的纪律。跳过任何阶段都要有明确理由。

探索代码库时读 .agentdocs/glossary.md(若存在),建立相关模块的清晰心智模型,并检查所涉区域的决策记录(adr/)。

脱敏

本 skill 会展示命令、输出与捕获的产物。先脱敏每个密钥:原位写 <REDACTED>。针对环境变量建循环,让凭据留在环境里而不是展示里。捕获的产物带着鉴权头:只引用载有信号的那几行。

脱敏后的输出不够诊断时,直说,并问用户。

阶段 1:建反馈回路

这一步就是本 skill 的全部。 其余都是机械操作。有了一个对本 bug 变红的紧凑通过/失败信号(一条命令就能抓住这个 bug),原因一定能找到:二分、假设检验、插桩都只是消费它。没有它,盯着代码看多久都没用。

在这里下不成比例的功夫。激进。有创意。拒绝放弃。

构造回路的方式,大致按序

1. 失败的测试,在够得到 bug 的任何接缝:单元、集成、端到端;
2. curl / HTTP 脚本打运行中的 dev server;
3. CLI 调用带 fixture 输入,stdout 与已知快照 diff;
4. 无头浏览器脚本(Playwright / Puppeteer)驱动 UI,断言 DOM/控制台/网络;
5. 回放捕获的痕迹。 真实网络请求 / 载荷 / 事件日志存盘;隔离地回放进代码路径;
6. 抛弃型 harness。 系统最小子集(一个服务、mock 依赖)一次函数调用踩中 bug 路径;
7. 性质 / 模糊循环。 bug 是"偶尔输出错"时,跑 1000 个随机输入找失败模式;
8. 二分 harness。 bug 出现在两个已知状态之间(commit、数据集、版本)时,自动化"在状态 X 启动、检查、重复",交给 git bisect run;
9. 差分循环。 同一输入穿过旧版 vs 新版(或两份配置),diff 输出;
10. HITL bash 脚本。 最后手段。必须人来点的话,用 scripts/hitl-loop.template.sh 驱动他们,让循环仍有结构。捕获的输出回流给你。

建对回路,bug 已修好九成。

收紧回路

把回路当产品。有了回路就收紧它:

• 能不能更快?(缓存初始化、跳过无关启动、缩小测试范围)
• 信号能不能更锐?(断言具体症状,不是"没崩")
• 能不能更确定?(钉住时间、固定随机种子、隔离文件系统、冻结网络)

30 秒的摇摆回路比没有回路好不了多少;2 秒的确定回路是紧凑的,是调试的超能力。

非确定性 bug

目标不是干净复现,而是更高的复现率。触发条件循环 100 遍、并行、加压、收窄时序窗口、注入延迟。50% 的闪烁 bug 可调试;1% 的不可,持续提高复现率直到可调试。

确实建不出回路时

停下,明说。列出试过什么。向用户要:(a) 能复现它的环境访问权,(b) 脱敏后的捕获产物(HAR、日志转储、core dump、带时间戳的录屏),或 (c) 加临时生产插桩的许可。没有回路不进入假设阶段。

完成判据:一条会变红的紧凑回路

阶段 1 完成 = 回路紧凑且可变红:你能说出一条命令(脚本路径、测试调用、一个 curl),它已经至少跑过一次(展示调用与输出,脱敏),并且:

• 可变红:它驱动真实的 bug 代码路径,断言用户描述的确切症状,能对这个 bug 变红、修好后变绿。不是"跑起来没报错";它必须能抓住这个特定的 bug;
• 确定:每次运行同一结论(闪烁 bug:按上法固定到高复现率);
• 快:秒级,不是分钟级;
• agent 可运行:能无人值守地跑;人在环里只经 scripts/hitl-loop.template.sh。

发现自己在命令存在之前读代码建理论,停:直接跳到假设正是本 skill 要防的失败。没有可变红的命令,没有阶段 2。

阶段 2:复现并最小化

跑回路。看它随 bug 出现变红。

确认:

• 回路产出的是用户描述的失败模式,不是碰巧在附近的另一个失败。错的 bug = 错的修复;
• 多次运行可复现(非确定性 bug:复现率高到可对着调试);
• 已捕获确切症状(报错、错误输出、耗时),后续阶段据此验证修复真的对症。

最小化

红了之后,把复现缩到仍会变红的最小场景。一次删一个:输入、调用方、配置、数据、步骤,每删一次重跑回路,只留对失败承重的部分。

为什么:最小复现缩小阶段 3 的假设空间(剩下来怀疑的活动部件更少),并成为阶段 5 干净的回归测试。

完成判据:剩下的每个元素都承重:去掉任何一个,回路变绿。

复现并且最小化之前不继续。

阶段 3:假设

测试任何一个之前,先产出3–5 个排好序的假设。单假设生成会锚死在第一个貌似合理的想法上。

每个假设必须可证伪:说出它的预测。

格式:"若 <X> 是原因,则 <改 Y> 会让 bug 消失 / <改 Z> 会让它更糟。"

说不出预测的假设是感觉:丢弃或磨利。

测试前把排序清单展示给用户。 他们常有瞬间重排的领域知识("我们刚部署了对 #3 的变更"),或已排除过某些假设。便宜的检查点,大的时间节省。用户不在也不阻塞:按你的排序继续。

阶段 4:插桩

每个探针对应阶段 3 的一个具体预测。一次只改一个变量。

工具偏好:

1. 环境支持时用调试器 / REPL 检查。一个断点胜过十条日志;
2. 在能区分假设的边界上放定向日志;
3. 永不"全量打日志然后 grep"。

每条调试日志打唯一前缀标签,如 [DEBUG-a4f2]。收尾清理变成一次 grep。没标签的日志会活下来;有标签的会死。

性能分支。 性能回退时日志通常不对。改为:先建基线测量(计时 harness、performance.now()、profiler、查询计划),再二分。先测量,后修复。

阶段 5:修复 + 回归测试

修复之前写回归测试,但仅在存在正确接缝时。

正确的接缝是:测试在调用现场以真实方式踩到真实的 bug 模式。仅有的接缝太浅时(单调用方的测试,而 bug 需要多个调用方;无法复现触发链路的单元测试),在那儿写回归测试给出的是虚假信心。

没有正确接缝,这本身就是发现。 记下来。代码库的架构正在阻止这个 bug 被锁死。把它标记给下一阶段。

存在正确接缝时:

1. 把最小化复现转成该接缝上的失败测试;
2. 看它失败;
3. 实施修复;
4. 看它通过;
5. 用阶段 1 的回路对着原始(未最小化)场景再跑一遍。

阶段 6:清理

宣布完成前必须:

• 原始复现不再复现(重跑阶段 1 回路)
• 回归测试通过(或已记录无接缝)
• 全部 [DEBUG-...] 插桩已移除(grep 该前缀)
• 抛弃型产物已删除(或移到明确标记的调试位置)
• 被证实的那个假设已写进 commit / PR 信息,下一个调试的人会学到