六阶段 Bug 诊断循环用「紧致反馈回路」驯服顽固 Bug 与性能回归 —— mattpocock-skills 的 diagnosing-bugs 技能实战指南【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读diagnosing-bugs是本仓库mattpocock-skills内置的一套模型自动触发的六阶段 Bug 诊断技能面向那些一眼看不透的顽固缺陷、偶发 flake 和夹在两个已知正常状态之间的性能回归。它的核心主张只有一条在获得一个紧致的反馈回路之前禁止任何理论推断——先构建一个能针对当前 Bug 变红、修复后变绿的单一命令后续的二等分、假设检验、插桩全部只是机械地消耗这个信号。读完本文你将掌握这套技能的触发时机、十条反馈回路构建阶梯、六个阶段之间的门禁规则、hitl-loop.template.sh人机协作脚本的完整用法以及它与triage、improve-codebase-architecture等相邻技能的分工边界。一、技能定位它做什么不做什么diagnosing-bugs对一个顽固 Bug 或性能回归执行六阶段诊断构建复现build a repro→ 最小化minimise→ 假设排序rank hypotheses→ 插桩instrument→ 带回归测试的修复fix with a regression test→ 清理clean up。它最重要的设计决策是禁止先入为主在存在一个紧致反馈回路之前它不会让 Agent 形成任何理论。所谓紧致回路指的是一个具名的命令且已经实际运行过至少一次它能在这个Bug 上变红、并在修复后变绿。默认情况下拿到 Bug 报告的编码 Agent 的行为是读代码、猜原因而本技能恰恰要阻断这种行为——如果不存在一个能变红的命令就没有 Phase 2。这一个门禁就是技能存在的全部意义一旦信号存在其后的二等分bisection、假设检验、插桩都只是机械工作。何时使用含适用场景速查表用户输入/diagnosing-bugs或者任务匹配时 Agent 自动触发。它是**模型触发model-invoked**的技能会响应diagnose / debug this或某东西坏了、抛异常、失败了、变慢了这类报告。对应的元数据可以在 agents/openai.yaml 中看到interface: display_name: Diagnosing Bugs short_description: Diagnose hard bugs and regressions以及 SKILL.md 的 frontmatter--- name: diagnosing-bugs description: Diagnosis loop for hard bugs and performance regressions. Use when the user says diagnose/debug this, or reports something broken/throwing/failing/slow. ---应该在难题上使用它一眼看不透的 Bug、偶发 flake、夹在两个已知正常状态之间的回归。它天生偏重对于一条消息就能回答的问题属于杀鸡用牛刀。原文档给出了清晰的情境路由表你的处境该去哪里一个你能描述出具体症状的缺陷本技能一个慢端点或已知 before-and-after 的时序回归本技能它有性能分支先测基线再二分这个代码库的瓶颈在哪里没有具体症状不是本技能。它诊断一个已知的失败不做审计别人发来的原始 Bug 报告尚未确认或整理先用 triage回答设计问题的临时代码而非追踪缺陷prototype用测试先行构建一个有规划的行为tdd没有合适的缝seam来锁定 Bugimprove-codebase-architecture本技能会主动向它交接二、紧致回路The Tight Loop才是技能本身Phase 1 得到了不成比例的投入因为它是唯一困难的阶段。技能给出了一条构建回路的阶梯按偏好程度大致排列失败的测试在能触达 Bug 的任何缝unit / integration / e2e上写一个。Curl / HTTP 脚本对着一个运行中的 dev server 打请求。CLI 调用带 fixture 输入将 stdout 与已知正确的快照做 diff。无头浏览器脚本Playwright / Puppeteer驱动 UI对 DOM / console / network 断言。重放捕获的痕迹把真实的网络请求 / payload / 事件日志存盘在隔离环境中沿代码路径重放。一次性 harness拉起系统的最小子集单个服务、mock 依赖用一次函数调用触发 Bug 代码路径。属性 / 模糊测试循环如果 Bug 是有时输出错误跑 1000 个随机输入寻找失败模式。二等分 harness如果 Bug 出现在两个已知状态commit、数据集、版本之间把在状态 X 启动、检查、重复自动化交给git bisect run。差分循环同一输入分别跑旧版本 vs 新版本或两套配置diff 输出。人机协作 bash 脚本最后手段。仓库为此配套了 scripts/hitl-loop.template.sh——Agent 运行脚本你在终端里按提示操作你的回答以可解析的输出回流给 Agent。有一个回路不是目标紧致才是。紧致意味着快fast秒级而不是分钟级确定性deterministic每次运行结论一致锐利sharp断言的是你的确切症状而不是没崩溃可无人值守运行agent-runnableAgent 可以无人看管地反复运行它人只有在 HITL 脚本场景才介入。一个 30 秒的 flaky 回路比没有好不了多少一个 2 秒的确定性回路才是调试超能力。对于只在某些时候出现的 Bug目标不是干净的复现而是更高的复现率循环触发、并行化、加压、注入 sleep直到 flake 率达到足够高、可以对着调试为止。原文档的量化经验是50% 的 flake 可调试1% 不可调试所以要不断抬升复现率直到可调试。当确实无法构建回路时技能被指示停下并明说列出尝试过什么然后向用户索取——(a) 能复现该问题的环境访问权(b) 脱敏后的捕获工件HAR 文件、日志转储、core dump、带时间戳的屏幕录制或 (c) 添加临时生产插桩的许可。它不应在没有任何回路的情况下继续提出假设。这一点在 SKILL.md 中被反复强调如果你发现自己正在读代码、在没有这个命令之前就构建理论——停下来直接跳到假设正是这个技能要防止的失败。没有能变红的命令就没有 Phase 2。补丁 1.2.3 新增Redact 脱敏规则技能要求 Agent 展示命令、输出和捕获工件因此 CHANGELOG 记录的 1.2.3 版本在 SKILL.md 中加入了Redact章节使其成为每次展示前的第一个动作对每个敏感内容写REDACTED占位构建回路时面向环境变量让凭据留在环境里而不是出现在展示内容中捕获的工件携带 auth 头只引用承载信号的那几行。如果脱敏后的输出不足以诊断 Bug技能应当明说并询问用户而不是冒险泄露凭据。三、阶段之间的门禁门gates不是清单六个阶段被设计成门禁而非勾选清单每一扇门只有某个具体条件为真才打开门必须为真的条件进入 Phase 2存在一个具名命令已经运行过并把输出粘出来能针对这个Bug 变红进入 Phase 3复现已达成且已最小化剩下的每个元素都是承重的load-bearing进入 Phase 4存在 3–5 条排序后的、可证伪的假设每条都陈述其预测并且在测试任何一条之前展示给你进入 Phase 5探针probes映射到具体预测一次只改变一个变量每条调试日志带[DEBUG-a4f2]风格标签以便一次 grep 清理完成原始复现不再复现插桩已移除且被证实正确的假设被写进提交信息值得特别说明 Phase 5 的逃生舱escape hatch回归测试在修复之前写但仅当存在正确的缝correct seam——即测试所锻炼的是 Bug 在调用点真正发生的模式。如果唯一可用的缝太浅Bug 需要多个调用者却只能写单调用者测试或单元测试无法复现触发 Bug 的那条链那里的回归测试只会带来虚假信心。这种情况下技能被指示明说没有正确的缝而不是写一个浅测试。这个缺失本身就是发现——正是它把事后复盘路由到improve-codebase-architecture。四、六阶段实战分解Phase 1构建反馈回路——这就是技能本身SKILL.md 的开场白毫不含糊This is the skill.Everything else is mechanical.这就是技能本身其余都是机械工作。如果你拥有针对这个Bug 的紧致 pass/fail 信号你就能找到原因二等分、假设检验、插桩都在消费它。如果没有盯代码盯多久都没用。因此激进、有创造力、拒绝放弃把不成比例的精力花在这里。Phase 1 的完成标准回路是紧致且能变红的——你能指出一个命令脚本路径、测试调用、一条 curl它已经至少运行过一次展示调用与脱敏后的输出并且满足四张勾选表☐能变红red-capable驱动真实的 Bug 代码路径并断言用户的确切症状能在本 Bug 上变红、修复后变绿。不是运行不报错它必须能抓住这个具体的 Bug。☐确定性deterministic每次运行结论一致flaky Bug 则钉住高复现率。☐快fast秒级不是分钟级。☐可无人值守agent-runnable人可以只通过hitl-loop.template.sh介入。Phase 2复现 最小化运行回路看着它变红。三张确认表☐ 回路产生的是用户描述的失败模式而不是旁边恰好发生的一个不同失败。错的 Bug 错的修复。☐ 失败跨多次运行可复现非确定性 Bug 则复现率足够高能对着调试。☐ 已捕获确切的症状错误消息、错误输出、慢时序供后续阶段验证修复确实命中。然后最小化把复现缩小到仍会变红的最小场景。每次只切掉一个输入、调用者、配置、数据或步骤每切一刀重跑回路只保留对失败承重的部分。收益有二最小化复现缩小了 Phase 3 的假设空间剩下值得怀疑的部件更少并在 Phase 5 变成干净的回归测试。完成标志剩下的每个元素都是承重的——移除其中任何一个都会让回路变绿。Phase 3假设排序在测试任何一条之前先生成3–5 条排序假设。单一假设生成会锚定在第一个貌似合理的想法上。每条假设必须可证伪陈述它所预测的后果。格式如果 是原因那么 改变 Y 会让 Bug 消失 / 改变 Z 会让它更糟。如果陈述不出预测这条假设就是感觉vibe丢弃或打磨它。在测试前把排序清单展示给用户——他们往往有领域知识可以瞬间重排我们刚部署了 #3 相关的改动或知道已被排除的假设。这是廉价检查点、省时利器。但不要阻塞用户不在场AFK就按自己的排序继续。Phase 4插桩每条探针必须映射到 Phase 3 的某个具体预测一次只改变一个变量。工具偏好调试器 / REPL 检查环境支持的话 定向日志 绝不全量打日志再 grep。给每条调试日志打唯一前缀标签如[DEBUG-a4f2]清理时一次 grep 就能删光未标记的日志存活已标记的日志消亡。性能分支perf branch对性能回归日志通常是错的工具。替代方案是先建立基线测量计时 harness、performance.now()、profiler、查询计划再做二等分。先测量后修复。Phase 5修复 回归测试回归测试先于修复编写但仅当存在正确的缝。正确的缝 测试锻炼的是 Bug 在调用点真实发生的模式。如果唯一可用的缝太浅回归测试在那里只会带来虚假信心。如果没有正确的缝这本身就是发现——记下来代码库架构正在阻止这个 Bug 被锁定为下一阶段标记此问题。有正确缝时的操作序列把最小化复现变成该缝上的失败测试看它失败应用修复看它通过用原始未最小化的场景重跑 Phase 1 反馈回路。Phase 6清理声明完成前的必做项☐ 原始复现不再复现重跑 Phase 1 回路☐ 回归测试通过或无缝的缺席已被记录☐ 所有[DEBUG-...]插桩已移除grep 前缀确认☐ 一次性原型已删除或移到明确标记的调试位置☐ 被证实正确的假设写进 commit / PR 信息让下一位调试者学到东西五、人机协作回路hitl-loop.template.sh 源码级讲解当回路必须由人类手动点击、登录、观察时技能用仓库自带的 scripts/hitl-loop.template.sh 把人结构化地驱动起来而不是让人类变成随机噪声源。该脚本约 30 行只有两个辅助函数#!/usr/bin/env bash # Human-in-the-loop reproduction loop. # Copy this file, edit the steps below, and run it. # The agent runs the script; the user follows prompts in their terminal. # # Usage: # bash hitl-loop.template.sh # # Two helpers: # step instruction → show instruction, wait for Enter # capture VAR question → show question, read response into VAR # # At the end, captured values are printed as KEYVALUE for the agent to parse. set -euo pipefail step() { printf \n %s\n $1 read -r -p [Enter when done] _ } capture() { local var$1 question$2 answer printf \n %s\n $question read -r -p answer printf -v $var %s $answer } # --- edit below --------------------------------------------------------- step Open the app at http://localhost:3000 and sign in. capture ERRORED Click the Export button. Did it throw an error? (y/n) capture ERROR_MSG Paste the error message (or none): # --- edit above --------------------------------------------------------- printf \n--- Captured ---\n printf ERRORED%s\n $ERRORED printf ERROR_MSG%s\n $ERROR_MSG要点step显示一条操作指令并等待回车用于请登录请点击某处这类无需回传的动作capture提问并把回答读入变量用于回传关键观测是否报错、错误文本等脚本末尾以KEYVALUE格式打印捕获结果Agent 直接解析这段可解析输出1.2.3 补丁明确capture会把值回显到终端供 Agent 读取所以观测交给 capture登录之类的动作留在 step避免把凭据流经 Agent 上下文使用方式是复制脚本、按注释编辑# --- edit below与# --- edit above之间的步骤然后bash hitl-loop.template.sh运行。脚本同样遵守脱敏原则既然展示命令、输出和捕获工件是技能的要求那么先脱敏一切秘密把[DEBUG-a4f2]风格的干净观测留在线索里。如果脱敏后的输出不足以诊断明说并询问用户。六、常见问题边界、误触发与已知缺口它在我只想要直接答案的快速问题上触发了。这是该技能被反馈最多的真实问题尤其在激活阈值较低的模型上模型把一段问题描述误判成诊断请求先煞有介事地构建复现往往价值有限再回答造成明显延迟。仓库中记录到四人反馈了同形状的问题。官方认可的修正是先轻后重问题确实需要时才升级到重流程但该改动尚未落地——技能的校准是针对 Claude Code 的调用行为做的低阈值模型会过度触发。在它演进之前实用解是明确说直接回答即可不要诊断或在你的 harness 里为它关闭模型自动触发。能让它对着一个代码库指出性能问题在哪吗不能。它诊断的是你能具名的一个失败。它的性能分支针对的是有症状的回归建立基线测量然后二等分先测量后修复而非主动扫描。针对主动版本的技能曾被提议并关闭目前仓库中没有对应技能。它在写修复之前会停下来问我吗不会。只有 Phase 3 有人工检查点排序假设清单在任何一条被测试前展示给你如果你不在场它就按自己的排序继续。插桩与修复之间没有门禁因此 Agent 可能在你就根因达成一致前就开始写代码。该门禁在仓库中被请求至今仍是 open issue。如果你想要在调用技能时说明即可。我已经对这份 Bug 报告跑过/triage了这是重复劳动吗部分重复且两个技能都不承认这一点。Triage 的验证步骤本质上是 diagnosing-bugs Phase 1–2 的浅层受限版本但两个文件互不提及对方。Triage 做有界的这到底是不是 Bug、表面在哪的检查本技能做彻底版。先跑 triage 并非浪费它的验证往往给你 Phase 1 的大部分原材料但在这里你会被要求重做一遍规范流程且不会有任何交叉引用提醒你。它粘出的复现输出会泄露秘密吗有可能。技能要求 Agent 粘贴调用及其输出并要求 HAR 文件、日志转储、core dump 等工件而没有任何指令做清洗。仓库中有 issue 专门提出此问题凭据、token、cookie 与个人数据搭车进入聊天、issue 或 PR并提议红色actionredaction护栏仍是 open 且未实现。把脱敏当成你自己的责任尤其是在输出流向任何公开场合之前——这正是 1.2.3 在 SKILL.md 开头加入 Redact 章节的原因。我的安全扫描器把该技能标为高风险。Snyk 会标记它且这是误报。它是整套技能中唯一附带可执行 shell 脚本hitl-loop.template.sh、带运行它和curl 一个 dev server指令的技能——附带 .sh 运行指令 出站 HTTP足以触发静态扫描器。脚本本身只是约 30 行read -r -p的等待人工输入的提示。扫描器评级的是能力表面capability surface而非已证实的利用。/diagnose去哪了v1.0.0 更名为/diagnosing-bugs旧名已不存在CHANGELOG 中记录为 breaking change。任何链接/diagnose的东西wrapper 技能、保存的 prompt都需要更新。七、它生效的判断标准Its working if在提出任何理论之前先向你展示一条命令及其红色输出。如果理论先出现说明技能没有在运行。它复现的失败正是你报告的失败而不是它顺路发现的邻近失败。它在猜测之前先缩小复现并能说出每个保留片段为什么承重。在任何一条被测试之前你被展示 3–5 条排序假设每条都带你能证伪的预测。它添加的每条调试日志都带[DEBUG-a4f2]标签声明完成时对该标签的 grep 结果为空。commit / PR 信息点明了哪条假设是对的。当它无法用测试锁定 Bug 时它明说而不是写一个浅测试。八、它在技能体系中的位置diagnosing-bugs是一个随时可取的独立技能reach-for-it-anytime standalone东西坏了就切入修复和回归测试就位就切出它不持有状态也不需要任何前置设置。在 ask-matt 的路由中Somethings broken有东西坏了被路由到这里——它是主流程之外的一条 on-ramp与/triage外部报告堆积并列。两个邻居值得注意improve-codebase-architecture当真正的发现是代码没有缝来锁定 Bug时接收本技能的交接handoff推荐在修复落地之后、信息更多时做出。triage位于其上游处理来自他人的原始 Bug 报告做前两个阶段的更浅版本。二者文本互不提及对方但功能上是互补关系——triage 验证这是不是真的 Bug、表面在哪diagnosing-bugs 追根因。对应文档参见 docs/engineering/triage.md。技能本身与配套脚本、元数据的完整实现位于 skills/engineering/diagnosing-bugs/含SKILL.md、scripts/hitl-loop.template.sh、agents/openai.yaml工程类技能的完整清单与说明见 skills/engineering/README.md。整个仓库以 Claude Code 与 Codex 双 harness 为目标agents/openai.yaml提供 Codex 侧的 UI 元数据disable-model-invocation/policy.allow_implicit_invocation则控制各自 harness 的隐式触发开关。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考