一、基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 正式名称 | diagnosing-bugs | 合集仓库子目录名（见下方说明） |
| 所属合集仓库 | mattpocock/skills（Matt Pocock 个人维护的 Agent Skills 公开仓库） | GitHub |
| 作者/维护者 | Matt Pocock（Total TypeScript 创始人，AI 工程教育者，个人 Newsletter 约 6 万订阅者） | 仓库 README |
| 来源链接 | https://github.com/mattpocock/skills/tree/main/skills/engineering/diagnosing-bugs | — |
| 许可证 | MIT | GitHub API |
| 所属仓库整体 Stars/Forks | 174,035 / 14,934（注：该数字属整个合集，不代表本技能自身热度，仅供了解仓库整体规模） | GitHub API |
| 该技能自身活跃度 | GitHub 全站代码搜索中，路径命中 “diagnosing-bugs” 的仓库/文件共 760 个；作者本人在仓库 README 正文与 X（Twitter）分别专门点名介绍此技能 | GitHub Code Search API + WebFetch |
| 最新版本 | v1.1.0（2026-07-08 发布，该版本为全仓库统一发版） | GitHub Releases API |
| 安装方式 | npx skills@latest add mattpocock/skills 或 Claude Code 插件市场一条命令安装（见第十章） |
官方 README |
二、功能介绍与亮点
diagnosing-bugs 是一套针对疑难 bug 与性能衰退的六阶段诊断纪律：建反馈回路 → 复现并最小化 → 提出假设 → 插桩验证 → 修复并补回归测试 → 清理与复盘。
核心能力：
- 反馈回路优先：作者明确“这才是这个技能的核心，其余步骤都只是机械执行”——要求先构造一个对该 bug 能变红、且确定性、快速、可无人值守运行的检测命令，列举了失败测试、curl 脚本、CLI 对拍、无头浏览器、流量重放、二分回归等十种具体构造方式，而不是空泛地说“先复现问题”
- 非确定性 bug 的专门处理：把目标从“干净复现”改为“提高复现率”，给出循环触发、并行压测、注入延迟等具体手段，避免对偶发问题束手无策
- 强制先排序假设再验证：要求一次性列出 3–5 条可证伪假设并向用户展示，防止对第一个“看起来合理”的猜测下锚
- 修复阶段绑定回归测试：只有存在“正确接缝”时才补测试，接缝不合适时明确记录“这本身就是一个发现”，避免虚假的安全感
- 作者在仓库 README 正文中将其与
/tdd并列，专门用一段话介绍“为调试构建的这个技能，把最佳调试实践封装进一个简单的循环”
三、适用场景
固定分类：工程效率与代码质量
适用于：疑难 bug 排查（尤其是复现困难或间歇性故障）、性能衰退定位、生产环境故障应急响应、以及希望把个人调试经验沉淀成可复用纪律的工程师。受益人群：独立开发者、需要在 AI 协助下调试却常常被“改一下试试”式瞎猜拖慢进度的工程师、负责线上故障排查的团队。
四、跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 官方 README 提供 Claude Code 插件市场安装路径，技能本身按 SKILL.md 规范编写，且未设置 disable-model-invocation，可被模型按描述自动触发 |
| Codex | 原生支持 | 官方 README 明确说明 “skills.sh 安装器已经把这些技能装进 Codex 等遵循 Agent-Skills 标准的运行时” |
| OpenClaw | 未验证 | 已抓取材料未提及 OpenClaw 专门支持 |
| Hermes Agent | 未验证 | 同上 |
五、推荐理由
AI 辅助调试最容易滑向“改一处试试、不行再改一处”的瞎猜循环，浪费时间还可能引入新 bug。diagnosing-bugs 把“先造一个能变红的紧凑反馈回路”立为铁律，逼着排查从可验证的信号出发而不是直觉，并把非确定性 bug、假设排序、回归测试补全都纳入同一套纪律。相比接管全流程的框架，它是一个可以单独拿走、不改变你现有工作方式的小工具，契合初中级用户“想要立刻能用、不想被绑架”的诉求。
六、评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 单个子技能维度：GitHub 代码搜索命中 760 处，作者本人在 README 正文与 X 平台分别专门介绍，另有 ≥2 篇独立博客专门分析该技能的方法论（合集仓库整体 stars 属整个合集，不代表本技能自身热度，故本项不以其为依据） |
| 可用性 | 9 | 一条命令安装（skills.sh 或 Claude Code 插件），文档完整含具体操作清单，2026-07-08 刚统一发版，无付费依赖；且不强制要求先运行 /setup-matt-pocock-skills，可独立开箱使用 |
| 安全性 | 9 | 见下方安全检查清单 |
| 综合评分 | 8.7 | 三项均值 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令执行及权限范围 | 极小——SKILL.md 主体为自然语言指令；仅在“最后手段”场景引用一个人机协同脚本模板 scripts/hitl-loop.template.sh，已逐行审阅，内容为纯本地交互式问答（展示提示、等待用户按键、记录回答），不含网络请求或危险操作 |
| ② 运行时联网外发数据 | 无——技能本身不发起任何网络请求 |
| ③ API Key/凭据要求及存储方式 | 无需任何凭据 |
| ④ 可疑指令/Prompt Injection 迹象 | 未发现——已逐字审阅 SKILL.md 全文及引用脚本，均为正常工程指令 |
| ⑤ 作者/组织信誉 | Matt Pocock，真实身份公开，Total TypeScript 创始人，长期从事 TypeScript/AI 工程教育，公开 Newsletter 约 6 万订阅者 |
| ⑥ License 是否明确 | MIT，明确 |
| ⑦ 最近维护时间 | 最新 tag v1.1.0 于 2026-07-08 发布，该子目录最近一次提交为 2026-07-13，维护活跃 |
七、跟同类 Skills 相比的优势
| 维度 | diagnosing-bugs（本推荐） | systematic-debugging（superpowers） |
|---|---|---|
| 核心机制 | 六阶段流程，第一阶段强制先构造“能变红”的紧凑反馈回路，给出十种具体构造手段 | “铁律”式原则——无根因调查不许下手修复，聚焦禁止症状式修复的纪律约束 |
| 非确定性 bug | 专门章节：把目标从“复现”改为“提高复现率”，给出并行压测等具体战术 | 未见针对非确定性/间歇性 bug 的专门处理章节 |
| 假设处理 | 强制一次列出 3–5 条可证伪假设，要求先给用户看再验证 | 强调根因优先，未见强制多假设排序的具体步骤 |
| 触发方式 | 模型可按描述自动触发，也可用户主动要求“diagnose/debug this” | 作为 superpowers 插件的一部分随 14 个技能一同分发 |
| 定位 | 独立、可单拿走的小技能，专注调试这一件事 | 更宏观的“能力增强”套装的一员，与规划、TDD 等技能共享同一套方法论体系 |
两者共享“先找证据再下结论”的调试哲学，但 diagnosing-bugs 把这一原则拆解为更具体、可直接照做的操作清单（十种反馈回路构造法、非确定性 bug 战术），适合想要“拿来就用”而非“理解一套原则再自行落地”的用户；systematic-debugging 则作为更大套件的一部分，胜在与该套件内其他工程纪律（如 TDD、验证流程）天然衔接。
八、用户评价
- Productize.life（技术博客）：“before hypothesizing about a cause, build a clear pass/fail signal first. Once you have a signal that reliably catches the bug, the rest is just narrowing it down”，并评价该技能“gets the order right: tighten the feedback loop first, hypothesize second”，认为其方法论“反映的是真实的调试痛点，而非纸面规则”
- Agentpedia.codes（技术博客）：将
/diagnose与/tdd并列讨论，指出“这些技能不会让模型本身变聪明，而是改变了模型周围的反馈回路，使其在动手改代码前拿到更好的证据、改完后拿到更好的验证”
九、其他补充
该技能与仓库内 /tdd、/improve-codebase-architecture 存在设计上的衔接：调试完成后若发现问题源于架构缺陷（如缺少可测试的接缝），SKILL.md 明确建议移交给 /improve-codebase-architecture 处理。仓库通过作者约 6 万订阅的技术 Newsletter 持续同步更新动态。
十、安装使用方式
方式一：skills.sh 安装器（可编辑，推荐希望二次定制的用户）
npx skills@latest add mattpocock/skills安装时按提示勾选 diagnosing-bugs 及目标 agent 即可，无需额外设置步骤（不同于同仓库的 grill-with-docs，本技能不强制要求先运行 /setup-matt-pocock-skills）。
方式二：Claude Code 插件（只读、随作者更新自动同步）
/plugin marketplace add mattpocock/skills
/plugin install mattpocock-skills@mattpocock触发方式：技能未设置 disable-model-invocation，当用户提出“diagnose”/“debug this”或描述报错、崩溃、变慢等场景时，模型可按描述自动识别调用；也可直接要求“用 diagnosing-bugs 排查这个 bug”显式触发。
十一、注意事项
- 目前由 Matt Pocock 个人维护，尚无多维护者的治理结构，需自行评估长期维护的连续性风险
- OpenClaw、Hermes Agent 的兼容性未在已抓取材料中得到证实，标记为“未验证”
- “最后手段”场景下引用的人机协同脚本模板需要用户本地复制、编辑后手动运行，不会被 agent 自动执行
- 若单独拷贝本技能文件而不通过官方安装器，仓库 README 中提到的
/improve-codebase-architecture移交建议需要额外安装该技能才能生效