六阶段 Bug 诊断纪律：diagnosing-bugs 的反馈回路定位法
六阶段 Bug 诊断纪律diagnosing-bugs 的反馈回路定位法【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills导读本篇文章讲解 diagnosing-bugs 技能一套面向疑难 Bug 与性能回退performance regression的六阶段诊断纪律。它的核心主张是在建立能让这个 Bug 变红的紧密反馈回路tight feedback loop之前禁止形成任何理论随后按复现→最小化→假设→插桩→修复→清理逐步推进。读完本文你将掌握如何为任意疑难 Bug 构建可重复、可判定、够快的通过/失败信号如何把一个概率性闪现的 flaky bug 变成可调试的对象以及如何让修复结果以回归测试的形式沉淀进代码库。这套技能解决什么问题README.md 在代码不工作一节中说明了这套技能的定位编码 Agent 最常见的失效模式之一是在没有反馈的情况下飞行flying blind。没有测试、没有浏览器访问、没有运行时信号Agent 只能靠猜。diagnosing-bugs 正是把最佳调试实践包装成分阶段门控的纪律循环防止 Agent 拿到 Bug 报告后的默认行为——读代码、猜原因。技能在前置元数据中声明了触发方式见 SKILL.md 的 frontmatter当用户说 diagnose / debug this或报告某个东西 broken、throwing、failing、slow 时模型可自动唤起。在 agents/openai.yaml 中它被声明为可直接调用的模型唤起型技能显示名为 Diagnosing Bugs。它属于 model-invoked 技能与triage上游做浅层验证、improve-codebase-architecture下游接收没有正确接缝的交接构成邻接关系。其定位是诊断一个已经能描述出症状的具体失败而不是对代码库做全局性能审计。Redact先脱敏再展示技能要求 Agent 展示命令、输出与捕获到的工件因此第一步是脱敏所有密钥一律以REDACTED占位反馈回路应基于环境变量构建让凭据留在环境里而不是出现在展示内容中捕获的工件常携带认证头只引用携带信号的那些行如果脱敏后的输出不足以诊断就明确说出来并向用户索取。这一点与 docs/engineering/diagnosing-bugs.md 的常见问题章节相互印证该技能会要求粘贴命令调用及其输出、索取 HAR 文件、日志转储、core dump而这些都不会被指令自动清洗因此把脱敏当成你自己的责任。Phase 1构建反馈回路本技能的核心SKILL.md 直言This is the skill.Everything else is mechanical.这就是技能本身其余都是机械动作。如果你有一个针对这个 Bug的紧密通过/失败信号那么二分、假设检验、插桩都只是消费这个信号没有它盯着代码看多久都没用。构建回路的十种方式按优先顺序技能按偏好顺序给出了十级阶梯失败测试在触及 Bug 的任意接缝unit / integration / e2e写失败测试Curl / HTTP 脚本打一个运行中的 dev serverCLI 调用 fixture 输入将 stdout 与已知正确的快照做 diff无头浏览器脚本Playwright / Puppeteer驱动 UI 并在 DOM / console / network 上断言重放捕获的 trace把真实的网络请求、payload 或事件日志存盘隔离地重放经过该代码路径一次性 harness拉起系统的最小子集单服务 mock 依赖用一次函数调用走通 Bug 代码路径属性 / 模糊循环针对有时输出错误跑 1000 个随机输入找出失效模式二分 harness若 Bug 出现在两个已知状态之间commit、数据集、版本自动化在状态 X 启动→检查→重复以便交给git bisect run差分循环同一输入分别过旧版本与新版本或两种配置diff 输出HITL bash 脚本最后手段如果必须由人来点击就用 scripts/hitl-loop.template.sh 驱动人让循环仍然结构化捕获输出反馈给 Agent。技能给出的判断是Build the right feedback loop, and the bug is 90% fixed.建对了回路Bug 就修好了 90%。HITL 脚本让人进入循环的模板仓库确实随技能附带了一个可执行脚本 scripts/hitl-loop.template.sh。它是最后手段的落地工具Agent 运行脚本用户在终端按提示操作答案以可解析的KEYVALUE输出回来。脚本提供两个辅助函数step instruction显示指令并等待 Entercapture VAR question显示问题并把回答读入变量。脚本开头的set -euo pipefail保证任何一步出错立即中止。模板默认演示了一个打开应用登录 → 点击 Export 按钮 → 记录是否抛错与错误信息的流程末尾统一打印ERRORED...与ERROR_MSG...供 Agent 解析。使用时只需复制文件、编辑--- edit below ---到--- edit above ---之间的步骤即可。收紧回路把回路当产品打磨有了一个回路还不够要收紧它更快缓存 setup、跳过无关初始化、收窄测试范围信号更尖锐断言具体症状而不是没崩更确定固定时间、播种 RNG、隔离文件系统、冻结网络。技能给的参照系是一个 30 秒且时好时坏的回路几乎比没有强不了多少一个 2 秒且确定性的回路是调试的超能力。非确定性 Bug目标是更高的复现率对只在特定时机出现的 Bug目标不是干净的复现而是更高的复现率把触发循环跑 100 次、并行化、加压力、收窄时间窗口、注入 sleep。50% 概率闪现的 Bug 是可调试的1% 的不是——所以要一直提高复现率直到它可以被调试。实在建不出回路怎么办技能要求停下来明确说出来列出尝试过的方法然后向用户索取(a) 能复现该 Bug 的环境访问权(b) 脱敏的捕获工件HAR 文件、日志转储、core dump、带时间戳的屏幕录制或 (c) 添加临时生产插桩的许可。禁止在没有回路的情况下继续猜假设。完成标准一条紧且能变红的回路Phase 1 结束的标志是回路既紧又能变红你能说出一条命令脚本路径、测试调用、curl它至少已经被你实际运行过一次展示调用与输出脱敏并且满足四项检查能变红它驱动真实的 Bug 代码路径并断言用户的确切症状因此能在这个 Bug 上变红、修好后变绿——不是运行不报错必须能抓住这个具体 Bug确定性每次运行结论一致对 flaky Bug则是有固定且高复现率见上快秒级而非分钟级Agent 可运行可以无人值守运行只有 HITL 场景才经由hitl-loop.template.sh让人介入。SKILL.md 特别警告如果你发现自己在这条命令存在之前就开始读代码构建理论那就停下来——直接跳到假设正是这个技能要阻止的失效模式。没有能变红的命令就没有 Phase 2。Phase 2复现 最小化运行回路看着它随 Bug 出现而变红。三项确认回路产生的是用户描述的失效模式而不是附近碰巧出现的另一个失败——修错 Bug 修错东西失败在多次运行间可复现对非确定性 Bug则是复现率高到足以作为调试对象已捕获精确症状错误消息、错误输出、慢的耗时供后续阶段验证修复是否真正解决它。最小化收缩到仍然变红的最小场景一旦变红就把它收缩到仍然变红的最小场景一次只删一个输入、调用者、配置、数据或步骤每删一次重跑回路只保留对失败承重的部分。为什么要做最小化复现缩小的 Phase 3 的假设空间可怀疑的活动部件更少并成为 Phase 5 干净的回归测试。当剩下的每个元素都是承重的删掉任何一个都会让回路变绿时最小化才算完成。没有复现且没有最小化不得进入下一阶段。Phase 3假设——先列出 3~5 个可证伪假设在测试任何假设之前先生成3~5 个排好序的假设。单一假设会锚定在第一个看起来合理的想法上。每个假设必须可证伪即说出它能做出的预测格式为If is the cause, then will make the bug disappear / will make it worse.如果 X 是原因那么改变 Y 会让 Bug 消失 / 改变 Z 会让它更糟。说不出预测的假设只是感觉要么丢弃要么打磨。排序后的列表要在测试前展示给用户——用户往往有领域知识能瞬间重排我们刚部署了 #3 的改动或者知道哪些假设已被排除。这是便宜的检查点、省时的大杀器用户不在线也不必阻塞用你的排序继续。Phase 4插桩——一次只改一个变量每个探针必须映射到 Phase 3 的某个具体预测一次只改一个变量。工具偏好环境支持就用Debugger / REPL 检查——一个断点胜过十条日志在能区分假设的边界上做定向日志绝不要什么都记下来再 grep。每条调试日志都要带唯一前缀标签如[DEBUG-a4f2]这样收尾清理就只是一次 grep——未标记的日志会活下来标记的会死掉。性能分支对性能回退日志通常是错的。正确做法是先建立基线测量计时 harness、performance.now()、profiler、查询计划再做二分。先测量后修复。Phase 5修复 回归测试回归测试要在修复之前写但仅当存在正确接缝时。正确接缝是指测试在调用点处复现真实的 Bug 模式。如果唯一可用的接缝太浅Bug 需要多个调用者但只有一个单调用者测试单元测试复现不了触发 Bug 的调用链在那个接缝上写回归测试只会带来虚假信心。如果没有正确接缝这本身就是发现。记下来代码库架构正在阻止这个 Bug 被锁死。把这标记给下一阶段。若存在正确接缝流程是把最小化后的复现转成该接缝上的失败测试看着它失败应用修复看着它通过用原始未最小化的场景重跑 Phase 1 的反馈回路。需要留意的是docs 的常见问题明确指出只有 Phase 3 有人的检查点展示排序假设插桩与修复之间没有门控因此 Agent 可能在你的根因获得认可之前就开始写代码。如果你希望加一道门请在调用技能时说明。Phase 6清理——宣布完成前的必做清单原始复现不再复现重跑 Phase 1 回路回归测试通过或接缝缺失已被记录所有[DEBUG-...]插桩已移除grep 该前缀一次性原型已删除或移到明确标注的调试位置最终正确的假设写进了 commit / PR 消息让下一个调试者能学到东西。阶段之间的门控docs 页面 docs/engineering/diagnosing-bugs.md 将这套流程总结为一张门控表——每个阶段都是门不是清单不满足具体条件就不开门门必须为真的条件进入 Phase 2一条已运行并粘贴了输出的命名命令能在这个 Bug 上变红进入 Phase 3复现已复现且已最小化剩下的每个元素都是承重的进入 Phase 4存在 3~5 个排好序、可证伪、各自说明预测的假设并在任何测试前展示给用户进入 Phase 5探针映射到具体预测一次一个变量每条调试日志带[DEBUG-a4f2]风格标签清理只需一次 grep完成原始复现不再复现、插桩已清除、正确的假设写进了 commit 消息与相邻技能的分工上游 triage他人提交的原始 Bug 报告先走 triage。其第 3 步验证主张本质上是本技能 Phase 1~2 的浅层有界版本按报告者的步骤复现 Bug 并报告已确认带代码路径/失败/信息不足。跑过 triage 不会浪费——它的验证结果通常提供了 Phase 1 的大部分原始素材——但这里要完整重做且两个技能都没有互相引用。下游 improve-codebase-architecture当真正发现是代码没有接缝来锁死这个 Bug时本技能在修复完成后信息更充分时向其交接由它扫描代码库并提议加深模块的机会。兄弟技能 tddtdd 定义接缝为测试所在的公共边界要求只在预先约定的接缝上测试本技能 Phase 5 的正确接缝判断与之一致且回归测试遵循 tdd 的 red-green 循环先红后绿、一次一个切片。README.md 的引用一节将其描述为围绕反馈回路的、分阶段门控的纪律循环skills/engineering/README.md 将它归入 model-invoked 工程技能。此外技能开头还提示探索代码库时先读CONTEXT.md如果存在以建立相关模块的心智模型并检查所触区域的 ADRs——这与 CONTEXT.md 维护项目领域词汇表的定位一致。何时该用、何时不该用该技能刻意设计为重工具适合第一眼看不出来的顽固 Bug、间歇性 flake、在两个已知良好状态之间悄悄潜入的回退。它不适合一句话就能回答的问题docs 的常见问题章节也确认它不做这个代码库的瓶颈在哪里这类主动扫描——那需要具体的症状与前后对照。若你想让它直接回答而不要走完整流程最实际的做法是在调用时明确说直接回答不要诊断或在你的 harness 中关闭它的模型自动唤起。【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考