AGENT SKILL

diagnosing-bugs

针对棘手缺陷和性能回退的诊断循环。用户提出“诊断”/“调试这个问题”,或报告某项功能损坏、抛出异常、失败或运行缓慢时使用。

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
diagnosing-bugs
description
针对棘手缺陷和性能回退的诊断循环。用户提出“诊断”/“调试这个问题”,或报告某项功能损坏、抛出异常、失败或运行缓慢时使用。

02 资源文件 2

03 SKILL.md 正文

诊断缺陷

一套处理棘手缺陷的纪律。仅在明确说明理由时才可跳过阶段。

探索代码库时,请阅读 CONTEXT.md(如果存在),建立相关模块的清晰心智模型,并检查所涉及区域的 ADR。

阶段 1——建立反馈循环

这就是本技能的核心。 其他一切都只是机械操作。如果你针对该缺陷拥有一个紧密的通过/失败信号——一个会因 当前 缺陷而变红的信号——你就能找到原因;二分查找、假设检验和插桩都只是在使用这个信号。如果没有,无论盯着代码看多久都无济于事。

应当在这里投入不成比例的大量精力。要积极进取,要有创造力,绝不放弃。

构建方法——大致按以下顺序尝试

  1. 在任何能够触达缺陷的接缝处编写失败测试——单元测试、集成测试或端到端测试。
  2. 针对正在运行的开发服务器编写 Curl/HTTP 脚本。
  3. 使用夹具输入执行 CLI 调用,并将 stdout 与已知正常的快照比较。
  4. 编写无头浏览器脚本(Playwright/Puppeteer)——驱动 UI,并对 DOM/控制台/网络进行断言。
  5. 重放捕获的跟踪记录。 将真实网络请求/负载/事件日志保存到磁盘;在隔离环境中通过该代码路径重放。
  6. 用完即弃的测试支架。 启动系统的最小子集(一个服务、模拟依赖),通过单次函数调用执行缺陷代码路径。
  7. 属性/模糊测试循环。 如果缺陷表现为“有时输出错误”,则运行 1000 组随机输入,寻找失败模式。
  8. 二分测试支架。 如果缺陷出现在两个已知状态(提交、数据集、版本)之间,则自动执行“在状态 X 启动、检查、重复”,以便运行 git bisect run。
  9. 差分循环。 让同一输入分别通过旧版本和新版本(或两种配置),然后比较输出差异。
  10. 人在回路(HITL)bash 脚本。 这是最后的手段。如果必须由人点击,则引导 用户 使用 scripts/hitl-loop.template.sh,让循环仍然结构化。捕获的输出会反馈给你。

建立正确的反馈循环,缺陷就已经解决了 90%。

收紧循环

把循环当作产品。一旦有了 一个 循环,就要将其收紧:

  • 能否让它更快?(缓存设置、跳过无关初始化、缩小测试范围。)
  • 能否让信号更敏锐?(对具体症状进行断言,而不是只断言“没有崩溃”。)
  • 能否让它更具确定性?(固定时间、设定 RNG 种子、隔离文件系统、冻结网络。)

一个耗时 30 秒且不稳定的循环只比没有循环稍好;一个耗时 2 秒且结果确定的循环才算紧密——这是调试的超能力。

非确定性缺陷

目标不是干净复现,而是获得更高的复现率。将触发器循环 100 次、并行执行、施加压力、缩窄时间窗口、注入休眠。复现率为 50% 的不稳定缺陷可以调试;1% 则不行——不断提高复现率,直到可以调试。

确实无法建立循环时

停止并明确说明情况。列出你尝试过的方法。向用户请求:(a) 访问任何能够复现问题的环境;(b) 捕获的工件(HAR 文件、日志转储、核心转储、带时间戳的屏幕录制);或 (c) 添加临时生产插桩的权限。没有循环时,不得继续提出假设。

完成标准——一个会变红的紧密循环

当循环既紧密又具备变红能力时,阶段 1 才算完成:你可以指出一条命令——脚本路径、测试调用或 curl——并且你已经至少运行过一次(粘贴调用及其输出),该命令还满足:

  • [ ] 具备变红能力——它会驱动真实的缺陷代码路径,并对用户描述的确切症状进行断言,因此可因该缺陷而变红,并在修复后变绿。不能只是“运行时不报错”——它必须能够 捕获这个特定缺陷。
  • [ ] 确定性——每次运行得出相同结论(对于不稳定缺陷:按照上文固定在较高复现率)。
  • [ ] 快速——以秒计,而不是以分钟计。
  • [ ] 智能体可运行——你可以无人值守地运行它;只有通过 scripts/hitl-loop.template.sh 才允许人在回路。

如果你发现自己在这条命令存在之前就开始阅读代码、构建理论,立即停止——直接跳到假设,正是本技能要防止的失败。 没有具备变红能力的命令,就不能进入阶段 2。

阶段 2——复现 + 最小化

运行循环。观察它变红——缺陷出现了。

确认:

  • [ ] 循环产生的是用户描述的失败模式,而不是恰好发生在附近的另一种失败。缺陷找错 = 修复错误。
  • [ ] 该失败可在多次运行中复现(对于非确定性缺陷,复现率必须足够高,能够据此调试)。
  • [ ] 你已经捕获确切症状(错误消息、错误输出、缓慢耗时),以便后续阶段验证修复是否真正解决该症状。

最小化

变红后,将复现场景缩减为仍会变红的最小场景。每次只删除一个输入、调用方、配置、数据或步骤,并在每次删除后重新运行循环——只保留对失败不可或缺的内容。

这样做的原因是:最小复现可以缩小阶段 3 的假设空间(剩下的可疑活动部件更少),并会成为阶段 5 中干净的回归测试。

当剩余的每个元素都不可或缺时才算完成——移除其中任何一个都会让循环变绿。

在完成复现并且完成最小化之前,不得继续。

阶段 3——提出假设

在测试任何假设前,先生成 3–5 个按优先级排序的假设。只生成一个假设会让思路锚定在第一个看似合理的想法上。

每个假设都必须可证伪:明确说明它所作出的预测。

格式:“如果 <X> 是原因,那么 <改变 Y> 会让缺陷消失,或 <改变 Z> 会让缺陷恶化。”

如果无法说出预测,这个假设就只是一种感觉——丢弃它或进一步明确它。

测试前向用户展示排序后的列表。 用户往往拥有能立即改变排序的领域知识(“我们刚刚部署了与第 3 项有关的变更”),或者知道哪些假设已经被排除。这是成本很低、却能节省大量时间的检查点。不要因此阻塞——如果用户人离开键盘(AFK),就按你的排序继续。

阶段 4——插桩

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

工具优先级:

  1. 如果环境支持,优先使用调试器/REPL 检查。一个断点胜过十条日志。
  2. 在能够区分各假设的边界处添加定向日志。
  3. 绝不“记录一切再用 grep 搜索”。

为每条调试日志添加唯一前缀,例如 [DEBUG-a4f2]。这样最后只需执行一次 grep 即可清理。无标签日志保留;有标签日志删除。

性能分支。 对于性能回退,日志通常不是正确手段。应当先建立基线度量(计时测试支架、performance.now()、性能分析器、查询计划),然后进行二分查找。先测量,再修复。

阶段 5——修复 + 回归测试

在修复之前编写回归测试——但前提是存在适合它的正确接缝。

正确接缝应当让测试能够按调用点实际发生的方式,执行真实缺陷模式。如果唯一可用的接缝过浅(缺陷需要多个调用方,却只能做单调用方测试;单元测试无法重现触发缺陷的调用链),在该处编写回归测试只会带来虚假信心。

如果不存在正确接缝,这本身就是一项发现。 将其记录下来。代码库架构正在阻止你通过测试锁定该缺陷。为下一阶段标记这一点。

如果存在正确接缝:

  1. 将最小复现转化为该接缝处的失败测试。
  2. 观察它失败。
  3. 应用修复。
  4. 观察它通过。
  5. 针对原始(未最小化)场景重新运行阶段 1 的反馈循环。

阶段 6——清理 + 事后分析

宣布完成前必须满足:

  • [ ] 原始复现不再复现问题(重新运行阶段 1 的循环)
  • [ ] 回归测试通过(或已记录缺少接缝)
  • [ ] 已移除所有 [DEBUG-...] 插桩(用 grep 搜索前缀)
  • [ ] 已删除用完即弃的原型(或移到明确标记的调试位置)
  • [ ] 已在提交/PR 消息中说明最终被证实正确的假设——让下一位调试者能够借鉴

然后问:什么本可以防止这个缺陷? 如果答案涉及架构变更(缺少良好测试接缝、调用方纠缠不清、隐藏耦合),请把具体信息移交给 /improve-codebase-architecture 技能。必须在修复完成之后提出建议,而不是之前——此刻掌握的信息比开始时更多。

04 同仓库更多 Skills