/diagnosing-bugs 技能

它的作用

diagnosing-bugs 对疑难 bug 或性能回归运行六阶段诊断：构建复现、最小化、假设排序、插桩、用回归测试修复、清理。

在 tight 反馈循环存在——一条具名命令，已运行过一次，在 this bug 时变红，修复后变绿。拿到 bug 报告的编码智能体默认行为是读代码然后猜；这个技能阻止了这一点。如果没有能变红的命令，就没有第二阶段。这一道闸门就是这个技能存在的意义。它之后的一切——二分、假设检验、插桩——一旦信号存在，就都是机械性的。

何时使用

输入 /diagnosing-bugs，或当任务合适时智能体会自行调用它——它由模型自动调用，在「诊断」/「调试这个」或关于某物损坏、抛错、失败或变慢的报告上触发。

在难啃的上面使用它：第一眼看不透的 bug、间歇性偶发、在两个已知良好状态之间悄悄溜进来的回归。它按设计就很重，对你想一条消息得到答案的问题来说是错误的工具。

紧密循环就是技能

第 1 阶段得到不成比例的投入，因为它是唯一难的阶段。技能给出构建循环的方式阶梯，大致按偏好排序：

1. 在能触达 bug 的接缝处有一个失败的测试。
2. 针对运行中开发服务器的 curl 或 HTTP 脚本。
3. 带 fixture 输入的 CLI 调用，与已知正确的快照做 diff。
4. 一个对 DOM、控制台或网络进行断言的 headless 浏览器脚本。
5. 重放捕获——保存的请求、载荷或事件日志，隔离地跑过代码路径。
6. 一个一次性的驱动装置：系统的最小子集，一次函数调用。
7. 针对「时好时坏的输出」的属性测试或模糊测试循环。
8. 一个可以交给 git bisect run.
9. 一个差分循环——相同输入，旧版本对新版本。
10. A human-in-the-loop bash 脚本，最后的手段。该技能自带 scripts/hitl-loop.template.sh 为此：智能体运行脚本，你在终端里跟着提示走，你的回答以可解析的输出返回。

A 循环不是目标。 紧密 是：快（秒级）、确定性（每次运行相同结论）、精准（断言你的确切症状，而不是「没崩溃」），并且智能体可无人值守地运行。30 秒的偶发循环几乎不比没有好。对于只偶尔出现的 bug，目标不是干净的复现，而是 更高的复现率 ——循环触发、并行化、加压力、注入休眠，直到偶发率足够高到可以调试。

当它确实无法构建时，它被指示停下来说出情况、列出尝试过的东西，并向你要 环境 访问权、一个捕获的产物，或添加临时探针的许可。它无论如何都不应该继续猜测。

阶段之间的门控

阶段是门控，不是检查清单。每个阶段在某个具体条件成立之前拒绝打开。

第 5 阶段有一个值得了解的逃生门。回归测试在修复之前写，但只有 正确的接缝 为它存在——测试在调用点真实出现的 bug 模式。当唯一可用的接缝太浅时，技能被要求说出这一点，而不是写一个给出虚假信心的测试。这个缺失本身就是发现，正是它把事后复盘导向 improve-codebase-architecture.

常见问题

它在我只想要直接答案的快速问题上触发了。 这是该技能被报告最多的问题，而且真实存在。尤其在 GPT-5.6-Sol 上，用户报告它会在对问题的普通描述上触发：「模型转而触发了相当正式的 diagnosing-bugs 技能。然后它继续构造复现场景——常常构建价值有限的模拟场景——然后才给我回应或建议。这导致相当大的回复延迟。」四个人分别报告了同样的形态，在 issue #578。被接受的修复方案是先从更轻量的方式开始，只在问题确实需要时才升级到更重的方案，但这一改动尚未落地。该技能是按 Claude Code 的调用行为校准的； model 以更低的激活阈值过度触发它。在它毕业之前，实用的修复是说出你想要什么（「直接回答，别诊断」）或在你 运行框架.

我能让它指向代码库并问性能问题在哪里吗？ 不。它诊断一个你已能命名的故障。它的性能分支用于有症状的回归——建立基线测量，然后二分，先测量后修复——而不是主动扫描。用于主动版的技能曾被 被提议并关闭；目前还没有针对它的技能。

它在写下修复之前会停下来问我吗？ 不。只有第 3 阶段有一个人工检查点——排序后的假设列表在任何测试之前展示给你，如果你离开，它会按自己的排序继续。插桩和修复之间没有门控，所以智能体可以在你同意它的根因之前就开始写代码。 Issue #124 要求那个门控，且仍然开放。如果你想要它，调用技能时就说出来。

我已经运行过 /triage 在这个 bug 报告上。这是同一个工作再次出现吗？ 部分，而且两个技能都不承认。正如一位读者所说：「triage 的第 3 步本质上是 diagnosing-bugs 第 1-2 阶段的一个浅层、有界的实例，但两个文件都没有提到对方。」Triage 做一次有界的「这真的是 bug 吗，表面是什么」扫描；这个技能做彻底的版本。先跑 triage 并不浪费——它的验证常常给你第 1 阶段的大部分原材料——但要预期在这里正经重做一遍，而且不要指望有交叉引用告诉你这一点。

它粘贴的复现输出会泄露密钥吗？ 可能。技能要求智能体粘贴调用及其输出，并请求 HAR 文件、日志转储、核心转储等产物。这些都不会按指令被清理。 Issue #674 恰好提出这一点——凭证、Token、Cookie 和个人数据搭车进入对话、issue 或 PR——并提议一个脱敏护栏。它开放且未实现。目前请把脱敏当作你的职责，特别是输出去任何公开场合之前。

我的安全扫描器把这个技能标记为高风险。 Snyk 标记了它，而标记是误报。它是套装里唯一发布可执行 shell 脚本的技能（hitl-loop.template.sh）以及运行它和 curl 一个开发服务器的说明。已发布 .sh 加上运行说明再加上出站 HTTP，足以触发静态扫描器。脚本本身大约 30 行 read -r -p 暂停等待人工输入的提示词。扫描器评估的是能力表面，不是已证实的漏洞利用。

发生了什么 /diagnose? 改名为 /diagnosing-bugs 在 v1.0.0 中。旧名字已不存在。你任何串联了 /diagnose ——包装技能、已保存的提示词——需要更新。

做到以下就算成功

• 它先给你看一条命令和它的红色输出，然后才提出任何理论。如果理论先到，说明技能没有在运行。
• 它复现的失败正是你报告的那个，不是它路上发现的近似物。
• 它先缩小复现，再开始猜测，并能告诉你为什么每个剩余部分是承重的。
• 你被展示一个 3–5 个假设的排序列表，每个都带有你可以证伪的预测，在任何假设被测试之前。
• 它添加的每条调试日志都带一个像 [DEBUG-a4f2]，而当它宣布完成时，对那个标签的 grep 返回空。
• 提交或 PR 消息点名哪个假设是对的。
• 当它无法用测试锁定 bug 时，它直白地说出来，而不是写一个浅薄的。

在流程中的位置

diagnosing-bugs 是一个随时可调用的独立技能。东西坏了时你切入它，修复和回归测试就位后你退出；它不持有状态，也无需事先配置。 ask-matt 把「有东西坏了」路由到这里。

两个邻居很重要。 improve-codebase-architecture 取 handoff 当真正的发现是代码没有接缝锁定 bug 时——推荐在修复落地之后做出，那时有更多信息。 triage 在它上游，处理来自他人的原始报告 bug，做同样前两个阶段的浅版本。