\r \r

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

\r

Skill 职责\r

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

1. 收集症状：让用户描述 bug 的表现（报错信息、复现率、环境、日志特征等）\r
2. 回忆过往：去 experience/ 目录下翻阅以前遇到过的类似 bug，作为经验记忆参考\r
3. 独立诊断：结合当前上下文自主排查，过往案例只作为思路启发和假设来源，绝不直接复用结论\r
4. 沉淀新经验：每次成功定位新 bug 后，把它作为新的 BUGxx.md 写进案例库，供下次参考\r \r 核心价值：让过往踩坑的经验启发下次排查的方向，但不替代独立思考。相似症状不一定是同一个 bug，看起来一样的日志背后可能是完全不同的根因。\r \r

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

\r

这是本 Skill 最核心的使用原则。\r \r 案例库里的 BUGxx.md 是老医生的病历本，不是处方模板。拿到新患者：\r \r

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

为什么不能直接引用\r

\r

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

正确的使用姿势\r

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

案例库结构\r

\r

bug-pattern-diagnosis/\r
├── SKILL.md                    ← 本文件（职责、流程、匹配规则）\r
└── experience/                 ← 案例库\r
    ├── BUG01.md                ← 每个案例一个文档\r
    ├── BUG02.md\r
    └── ...\r
```\r
\r
每个 `BUGxx.md` 都按固定结构写，方便快速检索：\r
1. **案例摘要**（一句话）\r
2. **症状 / 特征速查**（像病例的"阳性体征"，用于匹配）\r
3. **详细说明**（病理机制 / 根因链路）\r
4. **排查方法论**（诊断流程 / 关键技术）\r
5. **修复方案**（根治 + 兜底 + 加固）\r
6. **预防清单**（Checklist 防止复发）\r
7. **同类 bug 的 Playbook**（遇到相似现象如何按步骤排查）\r
\r
## 触发时机\r
\r
用户描述下列类型的问题时，优先启用本 Skill：\r
\r
- "某个接口**有时候**报错，有时候又正常"\r
- "线上复现了但本地/测试环境复现不了"\r
- "日志里的报错看起来很奇怪 / 对不上代码 / 栈指向不明"\r
- "多个 pod / 多实例 / 多副本 / 多机器之间行为不一致"\r
- "明明带了 xxx，服务端还提示 xxx 缺失"\r
- "偶尔超时 / 偶尔 500 / 偶尔权限不足"\r
- 任何形如"**交叉产生 / 间歇性 / 不确定性**"的描述\r
\r
## 核心流程\r
\r
### Step 1：读取案例库索引\r
\r
读取 `experience/` 目录下**所有** `BUG*.md` 文件的"**症状 / 特征速查**"章节（每个文件的前 30-50 行通常就够），不要一开始读完整文件。\r
\r
### Step 2：症状结构化\r
\r
从用户描述里提取**关键特征**，至少覆盖以下维度：\r
\r
| 维度 | 例子 |\r
|---|---|\r
| 错误信号 | NPE / 500 / 403 / 超时 / 数据错 / 死锁 |\r
| 复现率 | 100% / 50% / 偶发 / 特定条件 |\r
| 环境差异 | 本地不复现？测试复现？生产复现？ |\r
| 多实例特征 | 单副本 / 多副本？副本数是几？ |\r
| 日志分布 | 集中在一个实例 / 分散在多个实例 / 一个有栈一个没栈 |\r
| 触发条件 | 特定用户 / 特定参数 / 特定时段 |\r
| 最近改动 | 发版？配置变更？扩容缩容？依赖升级？ |\r
\r
### Step 3：案例回忆（不是匹配结论）\r
\r
把结构化特征和案例库逐个**比对相似度**，但**不要**据此下结论。无论相似度多高，案例都只是**"值得参考的既往经验"**，不是"确定的答案"。\r
\r
相似度处理原则：\r
\r
- **症状高度吻合**（3 个以上关键特征命中）→ 把案例作为"**优先怀疑方向**"，但要先引导用户**独立验证**关键特征是否真的成立\r
- **症状部分吻合**（1-2 个特征命中）→ 把案例作为"**可能的思路来源**"，提醒用户该案例的一两个排查技巧可能适用\r
- **没有匹配**（0 个命中）→ 走通用方法论，从零排查\r
\r
### Step 4：给出排查建议（不是诊断结论）\r
\r
**不要**以"这是 BUGxx"的口吻下定论。要以"过往有类似案例，以下是**可能的方向和验证方法**"的口吻交流。\r
\r
推荐的响应结构：\r
\r
- 🧭 **当前症状的结构化复述**（确认你没理解错）\r
- 💭 **经验参考**：提到 1-2 个相关案例（简单说"这让我想到之前排查过的 BUGxx 有类似特征 X"），但**不贴根因、不贴修复代码**\r
- 🔬 **独立验证建议**：列出 2-3 个能快速验证假设的 quick check（连续请求统计成功率 / 跨副本日志对照 / 某个 header 抓包等）\r
- 🎯 **当前项目的具体排查路径**：基于用户的项目结构、代码特点给出**定制化**的下一步行动，而不是案例里的通用步骤\r
- ⚠️ **明确不确定性**：说清"这只是基于相似症状的猜测，最终根因需要用户配合验证才能确认"\r
\r
### Step 4 的反面教材（禁止输出）\r
\r
```\r
❌ "根据你描述的症状，这是 BUG01（多副本间歇性 NPE）。\r
    根因是 invokeRemoteDeviceOpt 漏传 x-token-payload。\r
    按以下代码改动即可：[直接贴 BUG01 里的代码]"\r
```\r
\r
### Step 4 的正面范例\r
\r
```\r
✅ "你的描述有几个特征值得注意：\r
   1) 间歇性失败，成功率似乎接近 50%\r
   2) 日志似乎是 token 相关但客户端明明带了 token\r
\r
   这让我想起过去排查的 BUG01，那个案例里类似症状的背后是\r
   '多副本内部调用漏传身份 header'。但你的项目未必是同一个\r
   问题，**我建议先验证几个关键假设**：\r
\r
   Q1: 你的服务副本数是几？成功率是否约等于 1/N？\r
   Q2: 能否同时 tail 所有副本日志，看失败请求是否同时在\r
       多个副本留痕、且日志详尽程度不对称？\r
\r
   你先做这两个验证，结果告诉我之后，我们再决定排查路径。"\r
```\r
\r
### Step 5：沉淀新案例（可选）\r
\r
当出现以下情况时，**主动询问用户**是否把本次排查固化成新案例：\r
\r
- 案例库里完全没有匹配项，但本次成功定位了 bug\r
- 已有案例能匹配部分症状，但有显著新变种\r
- 排查过程中总结出了新的诊断方法论\r
\r
用户同意后，按"**案例文档结构**"（下方模板）创建 `BUGxx.md`（编号按当前最大编号 +1）。\r
\r
## 通用方法论（匹配不到已有案例时使用）\r
\r
按以下顺序排查陌生 bug：\r
\r
### 1. 定量化现象\r
\r
- 成功率？连续请求 100 次统计\r
- 复现条件？能否用最小用例稳定复现\r
- 故障时间分布？集中在某个时段/某个用户/某台机器\r
\r
### 2. 检查部署拓扑\r
\r
- 副本数多少？成功率是否约等于 `1/N` 或 `(N-1)/N`？\r
- 单副本能否复现？不能 → 强烈指向副本间行为不一致\r
- 有无灰度/金丝雀？新老版本是否混部？\r
\r
### 3. 跨实例日志对照\r
\r
- 按 traceId / 时间窗口，把**所有相关实例**的日志拉出来并排看\r
- 留意"同一请求在两个实例留下错位证据"的情况\r
- 留意"不同实例日志详尽程度不一致"（一个有栈一个没栈）\r
\r
### 4. 代码 vs 部署一致性\r
\r
- 部署 jar 里的 `.class` 用 `javap -c -p` 反编译，和本地源码比对\r
- 镜像 tag、git commit hash 要对得上\r
- ConfigMap / 环境变量是否全副本一致\r
\r
### 5. 协议层边界审计\r
\r
如果怀疑上下文传播问题：\r
\r
- 画出"身份/traceId/MDC/ThreadLocal"的完整生命周期\r
- 标注所有"跨线程 / 跨进程 / 跨实例"的边界\r
- 每个边界是否有显式的打包-解包机制\r
- 用 tcpdump / 接收端打印 `getHeaderNames()` 验证实际传递的 header\r
\r
### 6. 对比同类代码\r
\r
- 项目里有没有**做同样事**但**没出 bug** 的代码？\r
- Diff 出差异 → 差异处大概率是 bug 源头\r
\r
## 案例文档结构（创建新 BUG*.md 时的模板）\r
\r
```markdown\r
# BUGxx: \x3C一句话标题，突出最特征性症状>\r
\r
## 案例摘要\r
\r
\x3C一段话，200 字内。点明：现象、复现条件、根因类型、影响范围>\r
\r
## 症状 / 特征速查（用于匹配）\r
\r
> 遇到下列特征同时满足 N 条以上时，高概率是本案例\r
\r
- [ ] 特征 1（具体、可验证）\r
- [ ] 特征 2\r
- [ ] 特征 3\r
- [ ] ...\r
\r
### 关键日志指纹\r
\r
\x3C贴出典型的错误日志片段，让后续可以直接 grep 匹配>\r
\r
### 不会出现的反向特征（排除项）\r
\r
- 如果出现 \x3Cxxx>，则不是本案例\r
\r
## 详细说明 / 根因链路\r
\r
\x3C病理机制。用图/表格/代码引用说明数据流、控制流、状态变化>\r
\r
## 排查方法论\r
\r
### 使用到的技术\r
\r
- \x3C方法 1：例如"跨副本日志对照">\r
- \x3C方法 2：例如"javap 字节码比对"）>\r
- ...\r
\r
### 诊断步骤（按顺序）\r
\r
1. ...\r
2. ...\r
3. ...\r
\r
## 修复方案\r
\r
### 根治\r
\r
\x3C核心修复点、代码示例、影响面评估>\r
\r
### 兜底 / 防御\r
\r
\x3C二线防御措施，防止根治漏掉时仍不崩>\r
\r
### 加固 / 清理\r
\r
\x3C长期性改进，代码规约、同类代码扫描>\r
\r
## 预防清单（Checklist）\r
\r
开发阶段：\r
- [ ] ...\r
\r
部署阶段：\r
- [ ] ...\r
\r
Review 阶段：\r
- [ ] ...\r
\r
## 同类间歇性 bug 的 Playbook\r
\r
遇到类似现象时按此顺序走：\r
\r
1. 定量复现（10 分钟）\r
2. 查拓扑（5 分钟）\r
3. 日志对照（30 分钟）\r
4. ...\r
\r
## 参考资料\r
\r
- 相关文件路径\r
- 相关 PR/commit\r
- 相关 wiki\r
```\r
\r
## 输出风格约束\r
\r
- **先给方向，再给证据链**：告诉用户当前值得怀疑什么、为什么怀疑，而不是直接断言"这是什么 bug"\r
- **永远不用 100% 肯定的口吻下结论**：类似症状不代表同一根因，用"看起来像 / 值得怀疑 / 可能是 / 过往有类似案例"这种语气\r
- **建议永远可执行**：排查建议要给到具体命令、具体 quick check，不要只给抽象理论\r
- **鼓励用户先验证再改代码**：宁可多问几个"请你先看一下 xxx"，也不要基于猜测直接让用户动代码\r
\r
## 禁止事项（Hard Rules）\r
\r
- ❌ **禁止直接引用案例里的修复代码**：不把 `BUGxx.md` 里的代码片段当成"现成答案"贴给用户。案例代码只是"那个项目的修法"，不一定适合当前项目。\r
- ❌ **禁止以"这是 BUGxx"的口吻断言**：最多说"让我想起 BUGxx"、"和 BUGxx 有相似特征"。\r
- ❌ **禁止跳过独立验证**：即使 5 条特征全中，也要先让用户跑 1-2 个 quick check 验证关键假设，再进入修复讨论。\r
- ❌ **禁止把案例的"预防清单 / Playbook"整段复制输出**：这些是**思考素材**，每次要结合当前上下文裁剪改写。\r
\r
## 案例沉淀约束\r
\r
- 不要为了创建新案例而创建——只在真正有新价值时沉淀（全新的症状组合、全新的排查技巧）\r
- 不要照搬通用 bug 分类学术语（OOM、死锁之类），要用**症状描述**组织案例（"同一请求在不同副本日志错位"比"状态一致性 bug"更容易匹配）\r
- 案例库按问题**现象**索引，不是按"技术栈"或"漏洞类型"索引\r
- 每个案例结尾明确标注**适用边界**和**反例**（什么情况不是本案例），帮助下次准确识别\r