# 治疑难 Bug：调试审查设计三连拆，Matt 工程套件的「下半场」 ## 概述 本期是 Skills 生态系列第 3 轮，做开发者效率类横向评测。8 月 28 日的上半场拆了 tw93/check（审查纪律）与 browser-testing-with-devtools（测试可视化），本期补上另一半：调试、审查、设计三个环节，全部选自当前生态统治级套件 `mattpocock/skills`——`diagnosing-bugs`（498.4K 安装，总榜第 61）、`code-review`（439.6K，第 73）、`codebase-design`（506.0K，第 59）。三者此前均未被深拆过。核心发现：这套 Skill 的共同哲学不是教模型技巧，而是把资深工程师的「纪律」编译成一个个带完成判据的检查点——反馈回路必须能变红、假设必须可证伪、双轴结论不许合并排名。本期基于三个 Skill 的仓库原文逐段讲解（数据抓取于 2026-08-30）。 ## 为什么是这三个：一张「四大失败模式」地图 Matt Pocock（Total TypeScript 创始人）在仓库 README 里把他的 Skill 套件锚定在四个常见失败模式上，本期的三个主角恰好占满其中两格： - **#3 The Code Doesn't Work** → 解药是 `/tdd` 和 `/diagnosing-bugs`（tdd 已在此前「72万安装tdd」一文拆过，本期不重复） - **#4 We Built A Ball Of Mud** → 解药是 `/improve-codebase-architecture`（已有专文）和 `codebase-design`（本期首拆） README 引 Ousterhout《A Philosophy of Software Design》的话给这一格定调：「最好的模块是深的——大量功能藏在简单接口后面」，并引 Kent Beck：「每一天都投资于系统的设计」。这不是情怀引用，而是直接进了 Skill 正文的设计词汇。 榜单位置上（skills.sh 全时段榜，8 月 30 日抓取）：这三个 Skill 单看排名在 59–73 位，属于「腰部」，但它们背后的仓库在总榜前 12 名里占了 8 席，安装总量 2.8M+。换句话说，这是**被头部光环挡住的执行层**：grill 系列负责对齐需求，而本期三件套负责对齐之后把活干对。 ## 评测对比表 | Skill | 功能完整度(25%) | 设计质量(25%) | 实战效果(20%) | 上手难度(15%) | 社区活跃度(15%) | 加权 | |-------|------|------|------|------|------|------| | diagnosing-bugs | ★★★★★ | ★★★★★ | ★★★★★ | ★★★★ | ★★★★ | **4.7** | | code-review | ★★★★ | ★★★★★ | ★★★★ | ★★★ | ★★★★ | **4.1** | | codebase-design（初评） | ★★★★ | ★★★★ | ★★★★ | ★★★★ | ★★★★ | **4.0** | codebase-design 标注「初评」：本期抓到了它的目录结构（SKILL.md、DEEPENING.md、DESIGN-IT-TWICE.md、agents/ 子目录）与套件文档描述，未取到 SKILL.md 全文，评分按仓库结构与套件交叉印证推断，置信度低于前两个。 ## 主拆解一：diagnosing-bugs —— 把「调试方法论」写成六道闸门 这是本期含金量最高的一个。它的 frontmatter 只有寥寥数行，但 description 是触发词设计的范本： > Diagnosis loop for hard bugs and performance regressions. **Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.** 注意它没有写「帮助调试代码的工具」这种能力描述，而是把**用户真实会说的话**直接写进触发条件——"debug this"、broken、throwing、failing、slow 五个口语词。model-invoked Skill 的触发靠 description 与当前任务的语义匹配，把触发词写成用户口吻，比写成功能说明书命中率高得多。 ### Redact：调试之前先脱敏 正文第一个章节不是任何调试步骤，而是安全前置：所有命令输出、抓包工件先脱敏，密钥位置写 ``，回路建立在环境变量上而不是展示内容里，抓包文件里的认证头只引用有信号的那几行。把「脱敏」放在 Phase 1 之前，等于宣告：**排障过程中模型会大量展示系统内部信息，这是泄露高发区**。这一点绝大多数调试类 Skill 根本没意识到。 ### Phase 1：反馈回路——「This is the skill」 正文原话毫不掩饰倾斜： > **This is the skill.** Everything else is mechanical. If you have a tight pass/fail signal for the bug — one that goes red on _this_ bug — you will find the cause... If you don't have one, no amount of staring at code will save you. 接下来是全篇最实用的部分：**十种构建反馈回路的手段，按优先级排好序**——失败测试 → curl 脚本 → CLI 固件差分 → 无头浏览器 → 回放捕获的 trace → 一次性 harness → 属性/fuzz 循环 → 二分 harness → 新旧版本差分 → 最后手段 HITL bash 脚本。模型最容易犯的错是在前三种都可用时直接跳去读代码，这张有序清单等于把「试什么、按什么顺序试」预编译好了。 然后是三个进阶规则，每个都直击实战痛点： - **收紧回路**：「一个 30 秒的 flaky 回路几乎等于没有回路；一个 2 秒的确定性回路才叫紧——那是调试超能力」。方向三个：更快、信号更锐（断言具体症状而非「没崩」）、更确定（钉死时间、种子、文件系统、网络）。 - **非确定性 bug**：目标不是干净复现，而是**提高复现率**——循环触发 100 次、加压、收窄时间窗。「50% flake 的 bug 可调试；1% 不可调试——不断提高复现率直到可调试」。 - **真的建不出回路时**：明确停下来，列出试过什么，向用户要环境访问权、脱敏工件或生产端埋点许可。**没有回路不许进入假设阶段**。 Phase 1 的完成判据写得像验收标准：你必须能说出**一条命令**——且已经跑过至少一次——它满足红能力（能抓到这个特定 bug）、确定性、秒级、可无人值守四条。最狠的是这句反拖延条款： > If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** ### Phase 2–4：最小化、可证伪、单变量 Phase 2 要求把复现场景削减到「每个残留元素都是承重的（load-bearing）」——删掉任何一个回路就变绿为止。Phase 3 是反锚定设计：**测试任何假设之前先产出 3–5 条排过序的可证伪假设**，每条必须带预测格式「如果 X 是原因，那么做 Y 会让 bug 消失/恶化」，写不出预测的假设「是一种 vibe，丢弃或打磨它」。排序结果先给用户过目——用户一句「我们刚改了 #3 的部署」能瞬间重排，这是「廉价检查点、大额时间节省」，且用户不在线就继续、不阻塞。 Phase 4 的工具偏好排序是「一个断点胜过十条日志」，明令禁止「全量打日志再 grep」；每条调试日志必须带唯一前缀如 `[DEBUG-a4f2]`，收尾时一个 grep 全部清除——「不带标签的日志活下来，带标签的死掉」。性能问题单独分岔：先建基线测量再二分，「先测量，后修复」，因为性能回归靠看日志通常是错的。 ### Phase 5–6：缝（seam）与复盘 Phase 5 有个高级设计：回归测试要先写，**但只在存在「正确的缝」时**——即测试能在真实调用点复现 bug 模式的位置。如果唯一可用的缝太浅（单调用者测试复现不了多调用者链），在那里写回归测试只会带来虚假信心。而「**如果正确的缝不存在，这本身就是发现**」——是代码库架构在阻止 bug 被锁定，记下来交给下一步。Phase 6 的收尾清单里最有传承意识的一条：**把被证实的正确假设写进 commit/PR message**，「让下一个调试的人学到」。若复盘答案是架构问题，则在修复落定**之后**移交给 `/improve-codebase-architecture`——顺序不能反，因为此时你比开工时信息多得多。 短板也要说：六阶段对小 bug 显得重（开场留了「仅在明确说明理由时跳过阶段」的活口）；HITL 回路引用的 `scripts/hitl-loop.template.sh` 模板依赖套件配套文件，单独摘装会缺件；全文无中文。 ## 主拆解二：code-review —— 双轴分离，禁止合并排名 同仓库的 code-review（439.6K）回答另一个问题：审查一段 diff 时，「写得规不规范」和「做没做对事」是两回事。它的解法是把两轴**拆成两个并行子代理**，各自报告、并排呈现： > Both axes run as parallel sub-agents so they don't pollute each other's context... A change can pass one axis and fail the other. 三个值得抄的工程细节： **其一，失败前移。** 第一步钉住对比基点后，立刻用 `git rev-parse` 验证引用可解析、diff 非空——「坏的引用或空 diff 应该在这里失败，而不是在两个并行子代理里」。多代理架构里，前置校验是省 token 的第一道闸。 **其二，规范基线的优先级规则。** Standards 轴 = 仓库自带的编码规范 + 一套固定的 Fowler 代码异味基线（《Refactoring》第 3 章的 12 条：Mysterious Name、Duplicated Code、Feature Envy、Data Clumps、Primitive Obsession 等），并用两条规则捆住它：**仓库规范永远覆盖基线**（仓库认可的写法，基线闭嘴）；**基线永远是判断题不是违规题**（只能说「可能的 Feature Envy」，不能说「违反」）；工具已经强制的（linter、类型检查）一律跳过。这三条把「AI 审查满嘴车轱辘话」的老问题按死在了提示词层。 **其三，子代理提示词自包含。** 因子代理看不到主上下文，异味基线必须**全文粘贴**进 Standards 子代理的提示词——「子代理没有其他途径拿到它」；两份报告都限 400 词以内。汇总时明令**不许合并、不许跨轴排名**：「不要选出一个跨轴总冠军——那正是这次分离要阻止的重排」。Spec 轴找不到规格就明说「no spec available」，不硬编。 短板：它强依赖套件的 `setup-matt-pocock-skills` 配置（issue tracker 文档缺失时会被要求先跑配置），单独安装体验打折；没有严重度分级，输出全靠读者自行排序。 ## 主拆解三：codebase-design —— 套件的「词汇层」（初评） codebase-design 是三者中最抽象的：README 给它的定位是「设计深模块的共享纪律与词汇：小接口后面藏大量行为，落在干净的缝上，可穿过接口测试」。从目录结构看，它比一般 Skill 多了两个专题文件——`DEEPENING.md`（深挖模块）与 `DESIGN-IT-TWICE.md`（同一问题设计两套方案再挑），外加一个 `agents/` 子目录。「design it twice」正是 Ousterhout 书中的经典练习：强制并行生成两条真正不同的路线，避免第一条思路锚定。我们此前拆解 improve-codebase-architecture 时已观察到它的咬合方式：架构审查 Skill 选中候选后，深挖阶段会调用 codebase-design 的这套纪律与并行子代理。按套件的调用铁律（user-invoked 可调 model-invoked，反之不行），它是典型的**被上层 Skill 复用的纪律层**——单独装有用，装在套件里才发挥全部威力。等它独立登上热榜或仓库文档进一步公开后值得补一次全文拆。 ## diagnosing-bugs 六阶段工作流 ```mermaid flowchart TD A["用户: debug this / 报错 / 变慢"] --> R["Redact 前置脱敏
密钥→REDACTED 凭证走环境变量"] R --> P1["Phase 1 反馈回路（本体）
十种回路按序尝试并收紧
快/信号锐/确定性"] P1 --> C1{"一条已跑通的命令
能对准症状变红?"} C1 -- 否 --> STOP["停下索要环境或工件
禁止无回路空想假设"] C1 -- 是 --> P2["Phase 2 复现+最小化
删到每个元素都承重"] P2 --> P3["Phase 3 先出3-5条可证伪假设
排序给用户过目再测"] P3 --> P4["Phase 4 单变量探针
日志带 DEBUG-xxxx 前缀"] P4 --> P5["Phase 5 先写回归测试再修
无正确的缝=架构发现"] P5 --> P6["Phase 6 清理+复盘
正确假设写进 commit
架构病灶移交架构审查"] ``` ## 安装命令 ```bash # 方式一：Claude Code 官方插件市场（托管更新，推荐） claude plugins install mattpocock-skills # 方式二：skills.sh 安装器（文件落盘可自行修改，Codex 等其他 Agent 也适用） npx skills@latest add mattpocock/skills # 装完每个仓库跑一次（code-review 依赖它生成的 issue tracker 配置） # 在会话中执行：/setup-matt-pocock-skills ``` 注意：插件方式与 skills.sh 方式二选一，两者都装会导致每个 Skill 出现两份。 ## 推荐排行榜 - **最值得立即安装**：diagnosing-bugs —— 唯一一个「今天就能用在生产事故上」的，十种反馈回路清单本身值回票价 - **最适合抄提示词写法**：code-review —— 失败前移、基线优先级规则、400 词子代理合同，三个模式都能平移到你自己的多代理 Skill - **最适合进阶学习者**：codebase-design —— 想理解「深模块」「design it twice」这套词汇的先读它的两个专题文件 - **组合技最强**：三件套 + tdd + improve-codebase-architecture 全家桶 —— 调试发现的架构病灶最终流转到架构审查，形成修复闭环 ## 本期结论 把三个 Skill 放回一张桌子上看，主线异常清晰：**它们卖的不是技巧，是纪律的编译产物**。diagnosing-bugs 把「先建反馈回路再谈假设」写成带验收标准的闸门；code-review 把「规范与需求分开评、结论不许互相稀释」写成双子代理架构；codebase-design 把 Ousterhout 的模块设计观做成可复用词汇层。共同的技术手法有三个——每个阶段配完成判据（completion criterion）、关键结论先给用户过目的廉价检查点、以及无处不在的反上下文污染工程（子代理隔离、字数上限、日志前缀、禁止跨轴合并）。对想写自己 Skill 的人，本期可带走的一句话是：**把你所在领域的「老师傅口头禅」翻译成可验证的完成判据，你的 Skill 就有了骨架**。 ## 参考来源 1. [The Agent Skills Directory — skills.sh](https://www.skills.sh) — 全时段安装榜数据（2026-08-30 抓取）：diagnosing-bugs 498.4K、codebase-design 506.0K、code-review 439.6K 等 2. [mattpocock/skills 仓库主页](https://github.com/mattpocock/skills) — README「四大失败模式」框架、安装方式、Skill 全清单 3. [diagnosing-bugs SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnosing-bugs/SKILL.md) — 六阶段调试纪律原文 4. [code-review SKILL.md](https://github.com/mattpocock/skills/blob/main/skills/engineering/code-review/SKILL.md) — 双轴审查、Fowler 异味基线、子代理提示词原文 5. [codebase-design 目录](https://github.com/mattpocock/skills/tree/main/skills/engineering/codebase-design) — DEEPENING.md / DESIGN-IT-TWICE.md / agents/ 目录结构 > [!tip] 51学通信知识星球 > **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。 > **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。 > **当前规模**：5200 篇主题 / 990 个回答，198 元/年。 > **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。 > **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。