diagnosing-bugs
针对棘手缺陷和性能回退的诊断循环。用户提出“诊断”/“调试这个问题”,或报告某项功能损坏、抛出异常、失败或运行缓慢时使用。
- License 许可
- MIT
- 最近更新
- 2026-07-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- diagnosing-bugs
- description
- 针对棘手缺陷和性能回退的诊断循环。用户提出“诊断”/“调试这个问题”,或报告某项功能损坏、抛出异常、失败或运行缓慢时使用。
02 资源文件 2
- 参考文档agents/openai.yaml93 B
- 脚本scripts/hitl-loop.template.sh1.2 KB
03 SKILL.md 正文
诊断缺陷
一套处理棘手缺陷的纪律。仅在明确说明理由时才可跳过阶段。
探索代码库时,请阅读 CONTEXT.md(如果存在),建立相关模块的清晰心智模型,并检查所涉及区域的 ADR。
阶段 1——建立反馈循环
这就是本技能的核心。 其他一切都只是机械操作。如果你针对该缺陷拥有一个紧密的通过/失败信号——一个会因 当前 缺陷而变红的信号——你就能找到原因;二分查找、假设检验和插桩都只是在使用这个信号。如果没有,无论盯着代码看多久都无济于事。
应当在这里投入不成比例的大量精力。要积极进取,要有创造力,绝不放弃。
构建方法——大致按以下顺序尝试
- 在任何能够触达缺陷的接缝处编写失败测试——单元测试、集成测试或端到端测试。
- 针对正在运行的开发服务器编写 Curl/HTTP 脚本。
- 使用夹具输入执行 CLI 调用,并将 stdout 与已知正常的快照比较。
- 编写无头浏览器脚本(Playwright/Puppeteer)——驱动 UI,并对 DOM/控制台/网络进行断言。
- 重放捕获的跟踪记录。 将真实网络请求/负载/事件日志保存到磁盘;在隔离环境中通过该代码路径重放。
- 用完即弃的测试支架。 启动系统的最小子集(一个服务、模拟依赖),通过单次函数调用执行缺陷代码路径。
- 属性/模糊测试循环。 如果缺陷表现为“有时输出错误”,则运行 1000 组随机输入,寻找失败模式。
- 二分测试支架。 如果缺陷出现在两个已知状态(提交、数据集、版本)之间,则自动执行“在状态 X 启动、检查、重复”,以便运行
git bisect run。 - 差分循环。 让同一输入分别通过旧版本和新版本(或两种配置),然后比较输出差异。
- 人在回路(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 中的某个具体预测。每次只改变一个变量。
工具优先级:
- 如果环境支持,优先使用调试器/REPL 检查。一个断点胜过十条日志。
- 在能够区分各假设的边界处添加定向日志。
- 绝不“记录一切再用 grep 搜索”。
为每条调试日志添加唯一前缀,例如 [DEBUG-a4f2]。这样最后只需执行一次 grep 即可清理。无标签日志保留;有标签日志删除。
性能分支。 对于性能回退,日志通常不是正确手段。应当先建立基线度量(计时测试支架、performance.now()、性能分析器、查询计划),然后进行二分查找。先测量,再修复。
阶段 5——修复 + 回归测试
在修复之前编写回归测试——但前提是存在适合它的正确接缝。
正确接缝应当让测试能够按调用点实际发生的方式,执行真实缺陷模式。如果唯一可用的接缝过浅(缺陷需要多个调用方,却只能做单调用方测试;单元测试无法重现触发缺陷的调用链),在该处编写回归测试只会带来虚假信心。
如果不存在正确接缝,这本身就是一项发现。 将其记录下来。代码库架构正在阻止你通过测试锁定该缺陷。为下一阶段标记这一点。
如果存在正确接缝:
- 将最小复现转化为该接缝处的失败测试。
- 观察它失败。
- 应用修复。
- 观察它通过。
- 针对原始(未最小化)场景重新运行阶段 1 的反馈循环。
阶段 6——清理 + 事后分析
宣布完成前必须满足:
- [ ] 原始复现不再复现问题(重新运行阶段 1 的循环)
- [ ] 回归测试通过(或已记录缺少接缝)
- [ ] 已移除所有
[DEBUG-...]插桩(用grep搜索前缀) - [ ] 已删除用完即弃的原型(或移到明确标记的调试位置)
- [ ] 已在提交/PR 消息中说明最终被证实正确的假设——让下一位调试者能够借鉴
然后问:什么本可以防止这个缺陷? 如果答案涉及架构变更(缺少良好测试接缝、调用方纠缠不清、隐藏耦合),请把具体信息移交给 /improve-codebase-architecture 技能。必须在修复完成之后提出建议,而不是之前——此刻掌握的信息比开始时更多。
04 同仓库更多 Skills
writing-great-skills
出色编写和编辑技能的参考资料——让技能具备可预测性的词汇与原则。
teach
在此工作区内向用户教授新的技能或概念。
handoff
将当前对话压缩成交接文档,以便另一个智能体接手。
grilling
围绕计划、决策或想法对用户进行不留情面的深度追问。当用户想对自己的思路进行压力测试,或使用任何“深度追问”触发措辞时使用。
grill-me
通过不留情面的深度追问打磨计划或设计。
obsidian-vault
使用 wikilink 和索引笔记搜索、创建和管理 Obsidian 仓库中的笔记。当用户想要在 Obsidian 中查找、创建或整理笔记时使用。