bug-pattern-diagnosis

SKILL.md

---
name: bug-pattern-diagnosis
description: 根据用户描述的 bug 现象（症状）匹配已沉淀的 bug 案例库，快速判断这是哪类问题、根因在哪、如何排查。每次成功诊断后会把新案例沉淀到案例库，持续积累经验。适用于用户报告"奇怪的报错 / 间歇性失败 / 某些环境才复现 / 日志很诡异"的场景。
---

# Bug Pattern Diagnosis （Bug 症状诊断与经验沉淀）

## Skill 职责

这个 Skill 的作用是**像医生看病一样做 bug 诊断**：

1. **收集症状**：让用户描述 bug 的表现（报错信息、复现率、环境、日志特征等）
2. **回忆过往**：去 `experience/` 目录下翻阅以前遇到过的类似 bug，**作为经验记忆参考**
3. **独立诊断**：结合当前上下文自主排查，过往案例**只作为思路启发和假设来源**，绝不直接复用结论
4. **沉淀新经验**：每次成功定位新 bug 后，把它作为新的 `BUGxx.md` 写进案例库，供下次**参考**

**核心价值**：让过往踩坑的经验**启发**下次排查的方向，但不替代独立思考。相似症状不一定是同一个 bug，看起来一样的日志背后可能是完全不同的根因。

## 铁律：经验是参考，不是答案

> **这是本 Skill 最核心的使用原则。**

案例库里的 `BUGxx.md` 是**老医生的病历本**，不是**处方模板**。拿到新患者：

- ✅ **可以做的**：从病历本获取"这类症状通常值得怀疑什么"、"以前用什么方法查出过"、"有哪些容易踩的坑"
- ❌ **不能做的**：看到症状类似就直接抄根因、抄修复方案、抄代码改动

### 为什么不能直接引用

1. **症状可以相似，根因可能完全不同**：同样是"NPE + 间歇性 + 多副本"，可能是本次的 header 漏传，也可能是 Redis 连接池偶发失败、也可能是 GC stop-the-world 期间的竞态，更可能是**几种问题叠加**。
2. **项目环境差异巨大**：同样的代码结构在不同版本、不同配置、不同依赖下行为可能迥异。
3. **AI 误判代价高**：直接按案例照抄会让用户基于错误前提改代码，排查路径被带偏，真正的 bug 反而被掩盖。
4. **经验的价值在于"启发思考"而非"给答案"**：好医生看病历是为了拓展思路，不是为了复制粘贴。

### 正确的使用姿势

| 场景 | 错误做法 | 正确做法 |
|---|---|---|
| 症状匹配度高 | "这是 BUG01，改 `invokeRemoteDeviceOpt` 加 `x-token-payload`" | "你描述的现象让我想起 BUG01 的一个特征——副本间日志不对称。建议你**先验证**：跨副本日志是否真的有'一个有栈一个没栈'？如果是，再顺着这个方向查" |
| 部分特征命中 | "虽然不完全一样，但按 BUG01 的方案应该能修" | "BUG01 里**有个排查技巧可能适用**——连续请求 100 次看成功率是不是约 `1/N`。先用这个验证一下是不是副本间状态不一致的问题" |
| 案例里有具体代码 | 把 BUG01 的修复代码贴给用户让他照抄 | "BUG01 的修复思路是补齐 header 透传，但具体到你的项目，要先确认：(1) 你的接收端实际依赖哪些 header？(2) 序列化方式是否和入口一致？这些答完才能写代码" |

## 案例库结构

```
bug-pattern-diagnosis/
├── SKILL.md                    ← 本文件（职责、流程、匹配规则）
└── experience/                 ← 案例库
    ├── BUG01.md                ← 每个案例一个文档
    ├── BUG02.md
    └── ...
```

每个 `BUGxx.md` 都按固定结构写，方便快速检索：
1. **案例摘要**（一句话）
2. **症状 / 特征速查**（像病例的"阳性体征"，用于匹配）
3. **详细说明**（病理机制 / 根因链路）
4. **排查方法论**（诊断流程 / 关键技术）
5. **修复方案**（根治 + 兜底 + 加固）
6. **预防清单**（Checklist 防止复发）
7. **同类 bug 的 Playbook**（遇到相似现象如何按步骤排查）

## 触发时机

用户描述下列类型的问题时，优先启用本 Skill：

- "某个接口**有时候**报错，有时候又正常"
- "线上复现了但本地/测试环境复现不了"
- "日志里的报错看起来很奇怪 / 对不上代码 / 栈指向不明"
- "多个 pod / 多实例 / 多副本 / 多机器之间行为不一致"
- "明明带了 xxx，服务端还提示 xxx 缺失"
- "偶尔超时 / 偶尔 500 / 偶尔权限不足"
- 任何形如"**交叉产生 / 间歇性 / 不确定性**"的描述

## 核心流程

### Step 1：读取案例库索引

读取 `experience/` 目录下**所有** `BUG*.md` 文件的"**症状 / 特征速查**"章节（每个文件的前 30-50 行通常就够），不要一开始读完整文件。

### Step 2：症状结构化

从用户描述里提取**关键特征**，至少覆盖以下维度：

| 维度 | 例子 |
|---|---|
| 错误信号 | NPE / 500 / 403 / 超时 / 数据错 / 死锁 |
| 复现率 | 100% / 50% / 偶发 / 特定条件 |
| 环境差异 | 本地不复现？测试复现？生产复现？ |
| 多实例特征 | 单副本 / 多副本？副本数是几？ |
| 日志分布 | 集中在一个实例 / 分散在多个实例 / 一个有栈一个没栈 |
| 触发条件 | 特定用户 / 特定参数 / 特定时段 |
| 最近改动 | 发版？配置变更？扩容缩容？依赖升级？ |

### Step 3：案例回忆（不是匹配结论）

把结构化特征和案例库逐个**比对相似度**，但**不要**据此下结论。无论相似度多高，案例都只是**"值得参考的既往经验"**，不是"确定的答案"。

相似度处理原则：

- **症状高度吻合**（3 个以上关键特征命中）→ 把案例作为"**优先怀疑方向**"，但要先引导用户**独立验证**关键特征是否真的成立
- **症状部分吻合**（1-2 个特征命中）→ 把案例作为"**可能的思路来源**"，提醒用户该案例的一两个排查技巧可能适用
- **没有匹配**（0 个命中）→ 走通用方法论，从零排查

### Step 4：给出排查建议（不是诊断结论）

**不要**以"这是 BUGxx"的口吻下定论。要以"过往有类似案例，以下是**可能的方向和验证方法**"的口吻交流。

推荐的响应结构：

- 🧭 **当前症状的结构化复述**（确认你没理解错）
- 💭 **经验参考**：提到 1-2 个相关案例（简单说"这让我想到之前排查过的 BUGxx 有类似特征 X"），但**不贴根因、不贴修复代码**
- 🔬 **独立验证建议**：列出 2-3 个能快速验证假设的 quick check（连续请求统计成功率 / 跨副本日志对照 / 某个 header 抓包等）
- 🎯 **当前项目的具体排查路径**：基于用户的项目结构、代码特点给出**定制化**的下一步行动，而不是案例里的通用步骤
- ⚠️ **明确不确定性**：说清"这只是基于相似症状的猜测，最终根因需要用户配合验证才能确认"

### Step 4 的反面教材（禁止输出）

```
❌ "根据你描述的症状，这是 BUG01（多副本间歇性 NPE）。
    根因是 invokeRemoteDeviceOpt 漏传 x-token-payload。
    按以下代码改动即可：[直接贴 BUG01 里的代码]"
```

### Step 4 的正面范例

```
✅ "你的描述有几个特征值得注意：
   1) 间歇性失败，成功率似乎接近 50%
   2) 日志似乎是 token 相关但客户端明明带了 token

   这让我想起过去排查的 BUG01，那个案例里类似症状的背后是
   '多副本内部调用漏传身份 header'。但你的项目未必是同一个
   问题，**我建议先验证几个关键假设**：

   Q1: 你的服务副本数是几？成功率是否约等于 1/N？
   Q2: 能否同时 tail 所有副本日志，看失败请求是否同时在
       多个副本留痕、且日志详尽程度不对称？

   你先做这两个验证，结果告诉我之后，我们再决定排查路径。"
```

### Step 5：沉淀新案例（可选）

当出现以下情况时，**主动询问用户**是否把本次排查固化成新案例：

- 案例库里完全没有匹配项，但本次成功定位了 bug
- 已有案例能匹配部分症状，但有显著新变种
- 排查过程中总结出了新的诊断方法论

用户同意后，按"**案例文档结构**"（下方模板）创建 `BUGxx.md`（编号按当前最大编号 +1）。

## 通用方法论（匹配不到已有案例时使用）

按以下顺序排查陌生 bug：

### 1. 定量化现象

- 成功率？连续请求 100 次统计
- 复现条件？能否用最小用例稳定复现
- 故障时间分布？集中在某个时段/某个用户/某台机器

### 2. 检查部署拓扑

- 副本数多少？成功率是否约等于 `1/N` 或 `(N-1)/N`？
- 单副本能否复现？不能 → 强烈指向副本间行为不一致
- 有无灰度/金丝雀？新老版本是否混部？

### 3. 跨实例日志对照

- 按 traceId / 时间窗口，把**所有相关实例**的日志拉出来并排看
- 留意"同一请求在两个实例留下错位证据"的情况
- 留意"不同实例日志详尽程度不一致"（一个有栈一个没栈）

### 4. 代码 vs 部署一致性

- 部署 jar 里的 `.class` 用 `javap -c -p` 反编译，和本地源码比对
- 镜像 tag、git commit hash 要对得上
- ConfigMap / 环境变量是否全副本一致

### 5. 协议层边界审计

如果怀疑上下文传播问题：

- 画出"身份/traceId/MDC/ThreadLocal"的完整生命周期
- 标注所有"跨线程 / 跨进程 / 跨实例"的边界
- 每个边界是否有显式的打包-解包机制
- 用 tcpdump / 接收端打印 `getHeaderNames()` 验证实际传递的 header

### 6. 对比同类代码

- 项目里有没有**做同样事**但**没出 bug** 的代码？
- Diff 出差异 → 差异处大概率是 bug 源头

## 案例文档结构（创建新 BUG*.md 时的模板）

```markdown
# BUGxx: <一句话标题，突出最特征性症状>

## 案例摘要

<一段话，200 字内。点明：现象、复现条件、根因类型、影响范围>

## 症状 / 特征速查（用于匹配）

> 遇到下列特征同时满足 N 条以上时，高概率是本案例

- [ ] 特征 1（具体、可验证）
- [ ] 特征 2
- [ ] 特征 3
- [ ] ...

### 关键日志指纹

<贴出典型的错误日志片段，让后续可以直接 grep 匹配>

### 不会出现的反向特征（排除项）

- 如果出现 <xxx>，则不是本案例

## 详细说明 / 根因链路

<病理机制。用图/表格/代码引用说明数据流、控制流、状态变化>

## 排查方法论

### 使用到的技术

- <方法 1：例如"跨副本日志对照">
- <方法 2：例如"javap 字节码比对"）>
- ...

### 诊断步骤（按顺序）

1. ...
2. ...
3. ...

## 修复方案

### 根治

<核心修复点、代码示例、影响面评估>

### 兜底 / 防御

<二线防御措施，防止根治漏掉时仍不崩>

### 加固 / 清理

<长期性改进，代码规约、同类代码扫描>

## 预防清单（Checklist）

开发阶段：
- [ ] ...

部署阶段：
- [ ] ...

Review 阶段：
- [ ] ...

## 同类间歇性 bug 的 Playbook

遇到类似现象时按此顺序走：

1. 定量复现（10 分钟）
2. 查拓扑（5 分钟）
3. 日志对照（30 分钟）
4. ...

## 参考资料

- 相关文件路径
- 相关 PR/commit
- 相关 wiki
```

## 输出风格约束

- **先给方向，再给证据链**：告诉用户当前值得怀疑什么、为什么怀疑，而不是直接断言"这是什么 bug"
- **永远不用 100% 肯定的口吻下结论**：类似症状不代表同一根因，用"看起来像 / 值得怀疑 / 可能是 / 过往有类似案例"这种语气
- **建议永远可执行**：排查建议要给到具体命令、具体 quick check，不要只给抽象理论
- **鼓励用户先验证再改代码**：宁可多问几个"请你先看一下 xxx"，也不要基于猜测直接让用户动代码

## 禁止事项（Hard Rules）

- ❌ **禁止直接引用案例里的修复代码**：不把 `BUGxx.md` 里的代码片段当成"现成答案"贴给用户。案例代码只是"那个项目的修法"，不一定适合当前项目。
- ❌ **禁止以"这是 BUGxx"的口吻断言**：最多说"让我想起 BUGxx"、"和 BUGxx 有相似特征"。
- ❌ **禁止跳过独立验证**：即使 5 条特征全中，也要先让用户跑 1-2 个 quick check 验证关键假设，再进入修复讨论。
- ❌ **禁止把案例的"预防清单 / Playbook"整段复制输出**：这些是**思考素材**，每次要结合当前上下文裁剪改写。

## 案例沉淀约束

- 不要为了创建新案例而创建——只在真正有新价值时沉淀（全新的症状组合、全新的排查技巧）
- 不要照搬通用 bug 分类学术语（OOM、死锁之类），要用**症状描述**组织案例（"同一请求在不同副本日志错位"比"状态一致性 bug"更容易匹配）
- 案例库按问题**现象**索引，不是按"技术栈"或"漏洞类型"索引
- 每个案例结尾明确标注**适用边界**和**反例**（什么情况不是本案例），帮助下次准确识别