AGENT SKILL

diagnosing-bugs

针对硬 bug 和性能回归的诊断循环。在用户说「diagnose」/「debug this」,或报告有东西坏了/在抛错/在失败/很慢时使用。

License 许可
MIT
最近更新
2026-08-19
Stars
★ 0
Forks
0

01 前言 Front Matter

name
diagnosing-bugs
description
针对硬 bug 和性能回归的诊断循环。在用户说「diagnose」/「debug this」,或报告有东西坏了/在抛错/在失败/很慢时使用。

02 资源文件 2

03 SKILL.md 正文

诊断 Bug

给硬 bug 用的纪律。只有在明确说得通时才跳过阶段。

探索代码库时,阅读 CONTEXT.md(若存在)以获得相关模块的清晰心智模型,并检查你正在触碰的区域里的 ADR。

脱敏

本 skill 会让你展示命令、输出和捕获的产物。先脱敏每一个秘密 — 用 <REDACTED> 替换。针对环境变量构建循环,这样凭证留在环境里,而不是出现在你展示的内容中。捕获的产物会带 auth 头:只引用携带信号的那些行。

若脱敏后的输出不足以诊断这个 bug,说出来并询问用户。

阶段 1 — 构建反馈循环

这就是本 skill。 其余都是机械步骤。若你对这个 bug 有一个 紧 的通过/失败信号 — 会在 这个 bug 上变红的信号 — 你就会找到原因;二分、假设检验和插桩都只是在消费它。若你没有,再怎么盯代码也救不了你。

在这里花不成比例的力气。要凶。要有创造力。拒绝放弃。

构造循环的方式 — 大致按这个顺序尝试

  1. 失败测试,在能到达该 bug 的任何 seam 上 — 单元、集成、e2e。
  2. Curl / HTTP 脚本,打向正在运行的开发服务器。
  3. CLI 调用,带 fixture 输入,把 stdout 与已知良好快照做 diff。
  4. 无头浏览器脚本(Playwright / Puppeteer)— 驱动 UI,对 DOM/console/network 断言。
  5. 重放捕获的 trace。 把真实的网络请求 / payload / 事件日志存到磁盘;在隔离中把它重放过代码路径。
  6. 一次性 harness。 拉起系统的最小子集(一个服务、mocked 依赖),用一次函数调用走这条 bug 代码路径。
  7. Property / fuzz 循环。 若 bug 是「有时输出不对」,跑 1000 个随机输入并寻找失败模式。
  8. 二分 harness。 若 bug 出现在两个已知状态之间(commit、数据集、版本),自动化「在状态 X 启动、检查、重复」,以便你可以 git bisect run 它。
  9. 差分循环。 把同一输入跑过旧版本 vs 新版本(或两套配置)并 diff 输出。
  10. HITL bash 脚本。 最后手段。若必须有人点击,用 scripts/hitl-loop.template.sh 驱动 他们,让循环仍然有结构。捕获的输出反馈给你。

建对反馈循环,这个 bug 就修了 90%。

收紧循环

把循环当产品对待。一旦你有了 一个 循环,就去 收紧 它:

  • 我能让它更快吗?(缓存准备、跳过无关初始化、收窄测试范围。)
  • 我能让信号更锐利吗?(对具体症状断言,而不是「没崩」。)
  • 我能让它更确定吗?(钉死时间、给 RNG 设种子、隔离文件系统、冻结网络。)

一个 30 秒的不稳定循环几乎不比没有循环好;一个 2 秒的确定性循环才紧 — 调试超能力。

非确定性 bug

目标不是干净的复现,而是 更高的复现率。把触发循环 100 次、并行化、加压、收窄时间窗口、注入 sleep。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 个已排序的假设。只生成单一假设会锚定在第一个说得通的想法上。

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

格式:"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

若你陈述不出预测,这个假设就是感觉 — 丢掉或磨锋利它。

在测试之前把排序列表展示给用户。 他们常常有能立刻重排的领域知识(「我们刚部署了一项改到 #3」),或知道他们已经排除过的假设。便宜的检查点,省下大量时间。不要卡在这里 — 若用户 AFK,按你的排序继续。

阶段 4 — 插桩

每次探测都必须映射到阶段 3 的某个具体预测。一次只改一个变量。

工具偏好:

  1. 若环境支持,调试器 / REPL 检查。一个断点胜过十条日志。
  2. 在能区分假设的边界上打 定向日志。
  3. 永远不要「全打日志再 grep」。

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

性能分支。 对性能回归,日志通常是错的。取而代之:建立基线测量(计时 harness、performance.now()、profiler、查询计划),然后二分。先测量,后修复。

阶段 5 — 修复 + 回归测试

在修复 之前 写回归测试 — 但仅当存在 正确的 seam。

正确的 seam 是测试在调用点实际发生时行使 真正 bug 模式 的地方。若唯一可用的 seam 太浅(bug 需要多个调用方时却只有单调用方测试;单元测试无法复现触发该 bug 的链条),那里的回归测试会给虚假信心。

若不存在正确的 seam,那本身就是发现。 记下来。代码库架构正在阻止这个 bug 被锁死。把这一点标给下一阶段。

若存在正确的 seam:

  1. 把最小化后的复现变成该 seam 上的失败测试。
  2. 看它失败。
  3. 应用修复。
  4. 看它通过。
  5. 针对原始(未最小化的)场景重跑阶段 1 的反馈循环。

阶段 6 — 清理 + 事后回顾

在宣布完成之前必须:

  • [ ] 原始复现不再复现(重跑阶段 1 循环)
  • [ ] 回归测试通过(或已文档化缺少 seam)
  • [ ] 所有 [DEBUG-...] 插桩已移除(grep 该前缀)
  • [ ] 一次性原型已删除(或移到明确标记的调试位置)
  • [ ] 被证实正确的那个假设写进了 commit / PR 信息 — 好让下一个调试者学到

然后问:什么本可以阻止这个 bug? 若答案涉及架构变更(没有好的测试 seam、纠缠的调用方、隐藏的耦合),把具体细节交接给 /improve-codebase-architecture skill。在修复落地 之后 再给建议,而不是之前 — 你现在比开始时掌握的信息更多。

04 同仓库更多 Skills