diagnosing-bugs

Files (3)

• SKILL.md
• openai.yaml · agents/
• hitl-loop.template.sh · scripts/

SKILL.md (first lines)

# 诊断 Bug

给硬 bug 用的纪律。只有在明确说得通时才跳过阶段。

探索代码库时，阅读 `CONTEXT.md`（若存在）以获得相关模块的清晰心智模型，并检查你正在触碰的区域里的 ADR。

## 脱敏

本 skill 会让你展示命令、输出和捕获的产物。**先脱敏每一个秘密** — 用 `<REDACTED>` 替换。针对环境变量构建循环，这样凭证留在环境里，而不是出现在你展示的内容中。捕获的产物会带 auth 头：只引用携带信号的那些行。

若脱敏后的输出不足以诊断这个 bug，说出来并询问用户。

## 阶段 1 — 构建反馈循环

**这就是本 skill。** 其余都是机械步骤。若你对这个 bug 有一个 **紧** 的通过/失败信号 — 会在 _这个_ bug 上变红的信号 — 你就会找到原因；二分、假设检验和插桩都只是在消费它。若你没有，再怎么盯代码也救不了你。

在这里花不成比例的力气。**要凶。要有创造力。拒绝放弃。**

### 构造循环的方式 — 大致按这个顺序尝试

1. **失败测试**，在能到达该 bug 的任何 seam 上 — 单元、集成、e2e。
2. **Curl / HTTP 脚本**，打向正在运行的开发服务器。
3. **CLI 调用**，带 fixture 输入，把 stdout 与已知良好快照做 diff。
4. **无头浏览器脚本**（Playwright / Puppeteer）— 驱动 UI，对 DOM/console/network 断言。
5. **重放捕获的 trace。** 把真实的网络请求 / payload / 事件日志存到磁盘；在隔离中把它重放过代码路径。
6. **一次性 harness。** 拉起系统的最小子集（一个服务、mocked 依赖），用一次函数调用走这条 bug 代码路径。
7. **Property / fuzz 循环。** 若 bug 是「有时输出不对」，跑 1000 个随机输入并寻找失败模式。
8. **二分 harness。** 若 bug 出现在两个已知状态之间（commit、数据集、版本），自动化「在状态 X 启动、检查、重复」，以便你可以 `git bisect run` 它。
9. **差分循环。** 把同一输入跑过旧版本 vs 新版本（或两套配置）并 diff 输出。
10. **HITL bash 脚本。** 最后手段。若必须有人点击，用 `scripts/hitl-loop.template.sh` 驱动 _他们_，让循环仍然有结构。捕获的输出反馈给你。

建对反馈循环，这个 bug 就修了 90%。

### 收紧循环

把循环当产品对待。一旦你有了 _一个_ 循环，就去 **收紧** 它：

- 我能让它更快吗？（缓存准备、跳过无关初始化、收窄测试范围。）
- 我能让信号更锐利吗？（对具体症状断言，而不是「没崩」。）
- 我能让它更确定吗？（钉死时间、给 RNG 设种子、隔离文件系统、冻结网络。）

一个 30 秒的不稳定循环几乎不比没有循环好；一个 2 秒的确定性循环才紧 — 调试超能力。

### 非确定性 bug

目标不是干净的复现，而是 **更高的复现率**。把触发循环 100 次、并行化、加压、收窄时间窗口、注入 sleep。50% 概率复现的 bug 可以调试；1% 不行 — 持续提高复现率直到可调试。

### 当你确实建不出循环

停下来，明确说出来。列出你试过的。向用户要：(a) 能复现它的那个环境的访问权，(b) 一份已脱敏的捕获产物（HAR 文件、日志转储、core dump、带时间戳的屏幕录像），或 (c) 添加临时生产插桩的许可。**没有循环就不要进入假设。**

### 完成标准 — 一个会变红的紧循环

阶段 1 完成的条件是循环 **紧** 且 **能变红**：你能说出 **一条命令** — 脚本路径、测试调用、一次 curl — 你已经 **至少跑过一次**（展示调用及其输出，已脱敏），并且它是：

- [ ] **能变红** — 它驱动真正的 bug 代码路径，并对 **用户的确切症状** 断言，因此能在这个 bug 上变红、修好后变绿。不是「跑完不报错」 — 它必须能 _抓住这个特定 bug_。
- [ ] **确定** — 每次运行同一裁决（不稳定 bug：按上文，钉死的高复现率）。
- [ ] **快** — 秒级，不是分钟级。
- [ ] **Agent 可跑** — 你可以无人值守地跑它；人在环里只通过 `scripts/hitl-loop.template.sh`。

若你发现自己在这条命令存在之前就读代码去建理论，**停 — 直接跳到假设，正是本 skill 要防止的失败。** 没有能变红的命令，就没有阶段 2。

## 阶段 2 — 复现 + 最小化

跑循环。看它变红 — bug 出现。

确认：

- [ ] 循环产生的是 **用户** 描述的失败模式 — 不是碰巧在附近的另一种失败。错的 bug = 错的修复。
- [ ] 失败可在多次运行中复现（或者，对非确定性 bug，以足够高的、能对着调试的复现率复现）。
- [ ] 你已捕获确切症状（错误信息、错误输出、缓慢时序），以便后续阶段能验证修复确实针对它。

### 最小化

一旦变红，把复现缩到 **仍然会变红的最小场景**。一次砍掉一项输入、调用方、配置、数据和步骤，每次砍完再跑循环 — 只留下对失败承重的东西。

何必费这个劲：最小复现会缩小阶段 3 的假设空间（更少可疑的活动部件），并成为阶段 5 里干净的回归测试。

完成条件是 **每一个留下的元素都承重** — 去掉其中任何一个都会让循环变绿。

在你已经复现 **并且** 最小化之前，不要继续。

## 阶段 3 — 提出假设

在测试其中任何一个之前，生成 **3–5 个已排序的假设**。只生成单一假设会锚定在第一个说得通的想法上。

每个假设必须 **可证伪**：陈述它做出的预测。

> 格式："If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

若你陈述不出预测，这个假设就是感觉 — 丢掉或磨锋利它。

**在测试之前把排序列表展示给用户。** 他们常常有能立刻重排的领域知识（「我们刚部署了一项改到 #3」），或知道他们已经排除过的假设。便宜的检查点，省下大量时间。不要卡在这里 — 若用户 AFK，按你的排序继续。

## 阶段 4 — 插桩

每次探测都必须映射到阶段 3 的某个具体预测。**一次只改一个变量。**

工具偏好：

1. 若环境支持，**调试器 / REPL 检查**。一个断点胜过十条日志。
2. 在能区分假设的边界上打 **定向日志**。
3. 永远不要「全打日志再 grep」。

**给每条调试日志打标签**，用唯一前缀，例如 `[DEBUG-a4f2]`。收尾清理变成一次 grep。没打标签的日志会活下来；打了标签的会死掉。

**性能分支。** 对性能回归，日志通常是错的。取而代之：建立基线测量（计时 harness、`performance.now()`、profiler、查询计划），然后二分。先测量，后修复。

## 阶段 5 — 修复 + 回归测试

在修复 **之前** 写回归测试 — 但仅当存在 **正确的 seam**。

正确的 seam 是测试在调用点实际发生时行使 **真正 bug 模式** 的地方。若唯一可用的 seam 太浅（bug 需要多个调用方时却只有单调用方测试；单元测试无法复现触发该 bug 的链条），那里的回归测试会给虚假信心。

**若不存在正确的 seam，那本身就是发现。** 记下来。代码库架构正在阻止这个 bug 被锁死。把这一点标给下一阶段。

若存在正确的 seam：

1. 把最小化后的复现变成该 seam 上的失败测试。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn