AGENT SKILL

diagnosing-bugs

针对困难 bug 与性能回归的诊断回路。当用户要求诊断或调试某个东西,或报告某个东西坏掉/抛错/失败/变慢时使用。

License 许可
MIT
所属仓库
luestr/skills
最近更新
2026-11-14
Stars
★ 94
Forks
1

01 前言 Front Matter

name
diagnosing-bugs
metadata
{ "language": "zh-CN" }
description
针对困难 bug 与性能回归的诊断回路。当用户要求诊断或调试某个东西,或报告某个东西坏掉/抛错/失败/变慢时使用。

02 资源文件 2

03 SKILL.md 正文

诊断 bug

应对困难 bug 的一套纪律。只有在明确说明理由时才跳过阶段。

探索代码库时,读 GLOSSARY.md(如果存在),建立对相关模块的清晰心智模型,并查看你正在触碰的那片区域的 ADR。

脱敏

本技能要求你展示命令、输出和捕获到的产物。先把所有秘密脱敏:在原位写 <REDACTED>。让回路基于环境变量来跑,这样凭据留在环境里,而不是留在你展示的内容里。捕获到的产物带有认证头:只引用承载信号的那几行。

如果脱敏后的输出不足以诊断这个 bug,就直说,并向用户询问。

阶段 1:搭建反馈回路

这一步才是技能的本体。 其余都是机械操作。如果你为这个 bug 拿到了紧凑的通过/失败信号(一个会在这个 bug 上变红的信号),你就能找到原因;二分查找、假设检验、插桩都只是在消费它。如果没有,死盯着代码也救不了你。

在这里投入不成比例的精力。要激进。要敢想。绝不放弃。

构造回路的方法,大致按此顺序

  1. 失败测试——放在任何能抵达这个 bug 的接缝上:单元、集成、e2e。
  2. Curl / HTTP 脚本——针对运行中的开发服务器。
  3. CLI 调用——用夹具输入,把 stdout 与已知正确的快照做比对(diff)。
  4. 无头浏览器脚本(Playwright / Puppeteer)——驱动 UI,对 DOM/控制台/网络做断言。
  5. 重放捕获到的轨迹。 把真实的网络请求 / 载荷 / 事件日志存到磁盘;在隔离环境中让它重走一遍那段代码路径。
  6. 一次性 harness(运行环境)。 起一个系统的最小子集(单个服务、mock 掉依赖),用一次函数调用就能跑过 bug 所在的代码路径。
  7. 属性 / 模糊测试回路。 如果 bug 是“偶尔输出错误”,就跑 1000 个随机输入,寻找那种失败模式。
  8. 二分查找 harness。 如果 bug 出现在两个已知状态(提交、数据集、版本)之间,把“在状态 X 启动、检查、重复”自动化,这样就能用 git bisect run 跑它。
  9. 差分回路。 让同一输入分别跑旧版本和新版本(或两份配置),把输出做比对(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 才需要人在回路上。

如果你发现自己在命令存在之前就读代码、构建理论,停下:直接跳到假设,正是本技能要防的那种失败。 没有能变红的命令,就没有阶段 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()、性能分析器、查询计划),再做二分。先测量,后修复。

阶段 5:修复 + 回归测试

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

正确的接缝是指:测试在那里跑的是真实的 bug 模式,与它在调用点出现的方式一致。如果唯一可用的接缝太浅(bug 需要多个调用方,却只能写单调用方测试;单元测试无法复现触发 bug 的那条链路),在那里写回归测试只会带来虚假的信心。

如果不存在正确的接缝,这本身就是结论。 记下它。代码库架构正在妨碍把这个 bug 锁死。把这一点标出来,留给下一阶段。

如果存在正确的接缝:

  1. 把最小化后的复现改写成该接缝上的失败测试。
  2. 看着它失败。如果你是通过改动代码或夹具来强制变红,先和一份干净副本 diff,证明改动确实生效,再去相信它。
  3. 应用修复。
  4. 看着它通过。
  5. 针对原始的(未最小化的)场景重跑阶段 1 的反馈回路。

阶段 6:清理

在宣布完成之前必须做到:

  • [ ] 原始复现不再复现(重跑阶段 1 的回路)
  • [ ] 回归测试通过(或者接缝缺失已被记录在案)
  • [ ] 所有 [DEBUG-...] 插桩都已移除(grep 该前缀)
  • [ ] 一次性原型已删除(或移到明确标记的调试位置)
  • [ ] 最终证明正确的假设写进了提交信息 / PR 描述,好让下一个调试的人学到东西

04 同仓库更多 Skills

luestr
luestr/skills

write-ublock-origin-filters

完整的 uBlock Origin (uBO) 静态过滤语法参考。编写 uBlock Origin 自定义过滤规则时使用此技能,涵盖广告拦截、隐私保护或内容过滤。包含基础网络过滤模式(||、*、^、|)、所有网络过滤选项($domain、$third-party、$important、$redirect、$removeparam、$csp、$replace、$header、$method、$denyallow、$badfilter、$all 等)、内容类型选项($script、$image、$stylesheet、$font、$media、$xhr、$popup、$document、$frame 等)、元素隐藏规则(## 选择器、实体匹配、主机名正则)、过程式元素隐藏过滤器(:has、:has-text、:matches-css、:upward、:xpath、:matches-path、:watch-attr 等)、动作操作符(:remove、:style、:remove-attr、:remove-class)、HTML 过滤器(##^)、响应头过滤(##^responseheader)、脚本注入(##+js())以及预处理指令(!#include、!#if)。当用户提到 uBlock Origin 过滤规则、uBO 语法、广告拦截规则、元素隐藏规则、过程式选择器、脚本注入或希望编写/调试任何 uBO 兼容过滤列表时触发。即使用户只是在编写或调试 uBlock Origin 过滤规则、创建自定义过滤列表或从 AdBlock Plus/AdGuard 迁移过滤规则到 uBO,也应使用此技能。

★ 94
luestr
luestr/skills

write-ublock-origin-filters

Complete uBlock Origin (uBO) static filter reference. Use this skill when writing or debugging uBO custom filters or filter lists for ad blocking, privacy or content filtering, or when migrating filters from AdBlock Plus/AdGuard. Covers network patterns (||, *, ^, |) and options ($domain, $third-party, $important, $redirect, $removeparam, $csp, $replace, $header, $method, $badfilter, $all), content-type options ($script, $image, $stylesheet, $font, $media, $xhr, $popup, $document, $frame), cosmetic filters (##, CSS selectors, entity matching), procedural filters (:has, :has-text, :matches-css, :upward, :xpath, :matches-path, :watch-attr), action operators (:remove, :style, :remove-attr), HTML filters (##^), response-header filtering (##^responseheader), scriptlet injection (##+js()), and pre-parsing directives (!#include, !#if). Trigger whenever the user mentions uBO syntax, ad blocking rules, element hiding, procedural selectors, scriptlet injection, or a uBO-compatible filter list.

★ 94
luestr
luestr/skills

write-tampermonkey-scripts

引导 AI 代理规划、编写、调试、测试和维护 Tampermonkey 用户脚本。当用户请求用户脚本、浏览器页面自动化、DOM 增强、Tampermonkey 元数据、GM_* API、@match、@grant、@run-at、@connect、跨源请求、SPA 页面集成或脚本注入任务时使用此技能,即使用户没有明确提及 Tampermonkey。

★ 94
luestr
luestr/skills

write-tampermonkey-scripts

Guide an AI agent through planning, writing, debugging, testing, and maintaining Tampermonkey userscripts. Use this skill whenever a user asks for a userscript, browser-page automation, DOM enhancement, Tampermonkey metadata, GM_* API, @match, @grant, @run-at, @connect, cross-origin request, SPA page integration, or script injection task, even when Tampermonkey is not named explicitly.

★ 94
luestr
luestr/skills

write-adguard-filters

编写 AdGuard 自定义过滤规则时使用此技能。涵盖基本规则语法、所有修饰符($domain/$third-party/$important/$redirect/$replace/$removeparam/$cookie/$csp 等)、外观规则(元素隐藏/CSS/Extended CSS 选择器)、HTML 过滤、JavaScript/脚本片段规则、非基本规则修饰符、预处理器指令和调试技巧。当用户提及 AdGuard 过滤规则、广告拦截规则语法、过滤器列表编写、ABP 语法兼容、元素隐藏规则、Extended CSS 选择器(:has/:contains/:matches-css 等)时触发。即使用户只是在编写或调试任何类型的广告过滤规则,也应使用此技能。

★ 94
luestr
luestr/skills

write-adguard-filters

Complete AdGuard filtering rules syntax reference. Use this skill when writing AdGuard custom filters. Covers basic rule syntax, all modifiers ($domain/$third-party/$important/$redirect/$replace/$removeparam/$cookie/$csp etc.), cosmetic rules (element hiding/CSS/Extended CSS selectors), HTML filtering, JavaScript/scriptlet rules, non-basic rule modifiers, preprocessor directives, and debugging. Trigger when user mentions AdGuard filtering rules, ad blocking rule syntax, filter list authoring, ABP syntax compatibility, element hiding rules, Extended CSS selectors (:has/:contains/:matches-css etc.). Use this skill even when the user is just writing or debugging any type of ad filtering rules.

★ 94