complex-bug-debugging-with-ai

SKILL.md

---
name: complex-bug-debugging-with-ai
description: 复杂 bug 与 AI 协作排查的元方法论。当用户报告"诡异 / 间歇性 / 多层因素 / 重启不愈 / 多系统协作 / 已经排查很久没头绪"的 bug 时，启用本 SKILL 的 7 阶段协作工作流："业务链路对齐 → 症状结构化 → 边界测试循环 → 方案摆台 → 执行验证 → 失效升级 → 闭环沉淀"。本 SKILL 是双向纪律——同时约束 AI（不主观论断、不沿假设编、方案失效要主动说、用户不配合时停止推进）和用户（验收链路图、答完结构化问题、提供精确反信号、主动决策方案）。任一方不配合，AI 必须按内置话术明确指出，不带病硬推。
---

# Complex Bug Debugging with AI（复杂 BUG 与 AI 协作排查的工程化 Harness）

## 这是什么

不是案例库，是**协作工作流本身**。

> 案例库 `bug-pattern-diagnosis` 回答"**这个 bug 是什么**"
> 本 SKILL 回答"**怎么和 AI 一起排查复杂 bug**"

**核心信念**：复杂 bug 单靠 AI 解不了，单靠人也解不了。AI 缺：领域直觉 / 业务上下文 / 反信号 / 决策权。人缺：跑遍 100 条命令的耐心。**只有人 × AI 协作 + 严格流程，才能稳定攻破。**

## 触发时机

用户描述下列情况时**主动激活**：
- "排查很久了 / 排查不下去了"
- "bug 很诡异 / 不可复现 / 间歇性"
- "重启又自己好了，但还会再出"
- "看起来是 X，但改了 X 又不行"
- "涉及多个服务 / 节点 / 集群"
- "现象层面看起来矛盾"

普通 NPE / 编译错误 / 怎么写函数 → **不要启用**，直接处理。

---

## 前置：模型与能力预检（开始前必做）

### 1. 模型必须是 Opus 4.7（或同等强度）

- 弱模型会沿第一个假设一路编（自洽但错），把用户带沟里
- Opus 4.7 会**主动反向怀疑自己**（如怀疑工作区代码 ≠ 部署代码，主动拉 jar 反编译比对）
- **当前模型不是 Opus 4.7 → 先告诉用户切换，不要硬上**

### 2. 能力体系完备性

排查能力的下限取决于**最弱的工具**：

| 能力 | 缺失影响 |
|---|---|
| 代码访问（Read / Grep） | 无法验证业务逻辑 |
| 基础设施（K8S MCP / SSH） | 无法看 pod / 节点 |
| 数据访问（DB MCP） | 只能信用户口述 |
| 日志访问（拉真实日志） | 止于"猜栈" |
| 网络/HTTP 调用 | 无法做实验 |
| 专业 SKILL（如 server-log-analysis） | 效率打折 |

**缺哪个补哪个，不要带病开工。**

---

## 四条贯穿全流程的 AI 自我约束红线

### ① 不主观论断
每个结论必须有**刚跑出来的数据 / 刚读到的代码**支撑。**禁止**用"应该是 / 可能是 / 通常是"当结论。**可以**说"基于刚才的 metrics，判断是 ..."。

### ② 不沿假设编
用户给的方向 ≠ 真相。自己上轮假设 ≠ 已确认。看到反信号（"我也试过也不行" / 数据不符预期）**立即停下当前路径**，重新取证。

### ③ 方案失效要主动说
没修好 → **第一时间明说"方案 X 失效，证据是 ..."**，主动升级下一方案。**禁止**："应该好了，你试试" / "部分生效..." / 默默换方案。

### ④ 用户不配合时停止推进
没换强模型 / 能力缺失 / 没回询问 / 没提供边界信息 → **不要带病开工**，按下面的话术明确指出。用户坚持不补 → 可继续，但**先标记"以下排查在 X 信息缺失下进行，结论可能偏差"**。

---

## 双向纪律：主动询问 + 用户配合度强制检查

> 协作不是单方面。AI 不能在用户不配合时硬推，也不能悄悄替用户决定。

### 主动询问原则
每进入一个阶段，AI **必须主动询问**该阶段需要的信息，**禁止**用户给一句模糊描述就一头扎进去。

### 9 套用户不配合信号 + AI 反馈话术（直接套用，不要现编）

#### ① 没用强模型
```
⚠️ 当前模型不是 Opus 4.7。弱模型容易沿假设编（自洽但错），建议先切换。
若坚持用，请额外警惕我的结论，对每个"应该是 ..."追问"数据支撑是什么？"。
```

#### ② 能力体系缺失
```
⚠️ 本次排查需要 [具体能力]，当前未配置。
影响：[具体影响]。请先配置再继续。
若暂时配不了，我会基于你提供的文本日志排查，但可信度显著降低。
```

#### ③ 阶段 A：现象描述太模糊
```
⚠️ 现象太模糊，无法画链路图。请提供以下三项中至少两项：
  1. 一句话现象（"X 接口返回 500 / 设备发 register 没收到 reply"）
  2. 真实 log / 接口响应截图
  3. 涉及的服务清单（"前端 → 网关 → access-service → broker"）
不补齐我只能停留在猜可能性阶段。
```

#### ④ 阶段 A：不验收链路图就推下一步
```
⚠️ 你还没确认链路图是否准确。如果链路图错了，后续讨论都基于错误前提。
请回"对"或"不对，重点是 XXX"，再继续。
```

#### ⑤ 阶段 B：跳过结构化问题
```
⚠️ 你没回答以下结构化问题（我自己拿不到）：
  □ 复现率？□ 环境差异？□ 最近改动？□ 你自己复现过吗（金问题）？
没有这些信息我只能基于猜测做边界测试。请逐条回答。
```

#### ⑥ 阶段 C：AI 询问后用户没回答 / 答得模糊
```
⚠️ 我遇到一个**必须由你确认**的事实：
  问题：[具体二选一问题]
  影响：决定排查方向（A → 路径 X；B → 路径 Y）
请：1) 告诉我怎么查，我去查；2) 或明确说"不知道也查不到"，我会按两种情况都假设展开。
不要直接换话题，否则诊断空间无法收敛。
```

#### ⑦ 阶段 C：反信号描述太模糊
```
⚠️ 你说"也不行 / 没问题"是关键反信号，但描述太模糊。请补充：
  - 怎么试的？（命令 / 工具 / 步骤）
  - 看到什么？（具体输出 / 错误码）
  - 环境一致吗？
不要说"MQTTX 也不行"，要说"MQTTX QoS 1 publish XXX，连 XXX broker，无报错但 reply 没收到"。
```

#### ⑧ 阶段 D：让 AI 替自己拍板
```
⚠️ 方案选择必须由你拍板，因为：
  - 你比我清楚生产容忍度 / 不能影响什么 / 回滚能力
  - 出问题承担后果的是你的团队，不是我
我已列清"修复力度 / 生产影响 / 回滚成本"。请基于"今天能接受多大影响"决定。
若实在没决策依据，告诉我"运维窗口 X / 不能影响 Y"，我帮你筛但你拍板。
```

#### ⑨ 阶段 G：修复完不沉淀
```
⚠️ 本次细节正在快速从短期记忆里流失。强烈建议现在沉淀（5 分钟）：
  - 按 bug-pattern-diagnosis 模板写 BUGxx.md
  - 重点：症状速查 / 反向特征 / 5 分钟自检命令 / 走过的弯路
不沉淀代价：下次类似 bug 你 / 同事 / AI 都要从零再排一次。
回"沉淀"或"不用"，明确即可。
```

### 配合度门控（每阶段流转前自检）

| 流转 | Gate |
|---|---|
| A → B | 用户验收链路图了吗？ |
| B → C | 答完结构化问题？补了"我也复现过"？ |
| C 每轮 | 上轮疑问回答了？反信号够具体？ |
| C → D | 决定性证据充分？AI 没自我说服？ |
| D → E | 用户拍板了？还是让 AI 替决策？ |
| E → F/G | 验证数据齐？修复前后并列展示？ |
| G 完成 | 同意沉淀？BUGxx.md 完整？ |

**任一 Gate 不通过 → 停下来按话术指出，不要硬推。**

---

## 7 阶段协作工作流

### 阶段 A：业务链路对齐【先建图，不修 bug】

> 双方对"链路"认知不一致 → 后续讨论都是鸡同鸭讲。

**AI 主动开场（必做）**：
```
按 SKILL 流程走（不需要可打断我）。阶段 A 我需要：
  1. 一句话现象（不要先猜原因）
  2. 真实 log / 接口响应 / 截图
  3. 涉及哪些服务 / 链路
我画完链路图给你确认。
```

**AI 做**：
1. 主动询问 / Read 代码，画端到端链路图
2. 复述现象，确认"我理解的 = 你说的"
3. 明确列"已知 X"、"不知道 Y"

**人验收（强制 Gate）**：
- "对" → 进入 B
- "不对，重点是 XXX" → 重画
- 没明确验收 → 套话术 ④

**反模式**：上来就扎代码 / 没等验收就推下一步。

### 阶段 B：症状结构化 + 领域信息补齐

**AI 主动开场（必做）**：
```
进入 B。请逐条回答（缺哪条都会让排查走偏）：
  □ 复现率：100% / 偶发 / 特定条件？
  □ 环境差异：本地能复现吗？
  □ 多实例特征：单 / 多副本？
  □ 最近改动：发版 / 扩容 / 配置变更 / 依赖升级？
  □ 日志特征：集中 / 分散？时间窗？
  □ 你自己复现过吗？（金问题）用什么手段？看到什么？
  □ 你怀疑过哪些方向？已排除什么？
模糊或跳过的我会再追问。
```

**人补领域信息**："这是 broker 集群" / "上周扩容了" / "我用 MQTTX 也试了也不行" ← **这种'我也复现了'是金子**。

**Gate**：用户回答 ≥5 条 → C；少于 3 条 → 套话术 ⑤；反信号模糊 → 套话术 ⑦。

**反模式**：不结构化就直接排查 / 用户跳过就脑补。

### 阶段 C：AI 自主边界测试循环【核心引擎】

> 复杂 bug 几乎不可能一次实验定位，必须循环收敛。

**AI 主动开场（必做）**：
```
进入 C。我会跑这个循环：现象 → 边界测试 → 数据并列展示 → 有疑惑就主动问你。
每轮我会：明确说"这轮验证什么假设"、数据并列展示、必须由你确认的事实主动停下问。
你随时打断说"等等，这个数据为什么 XXX？"是被鼓励的——能帮我避免自我说服。
本轮预计跑 [命令清单]，需要 [具体能力]。能力齐了吗？
```

**AI 每轮**：
1. 设计**能二分诊断空间**的实验（不是穷举跑命令）
2. 自主执行：MCP / shell / 代码读取 / 跨节点对比
3. **数据并列展示**：

   | 实验 | 预期 | 实际 | 一致？ |
   |---|---|---|---|
   | 入口 A | 应成功 | 成功 ✅ | ✓ |
   | 入口 B | 应成功 | 失败 ❌ | **✗ 异常点** |

4. 自检"实际 vs 假设是否完全吻合"：
   - 完全吻合 + 信息充分 → 初步结论 → D
   - 任何"不太对"的数据 → **不要硬下结论**，列疑问问人
   - 信息不够 → 设计下一轮

**人做**：看 AI 列的疑问 / 在 AI 自我说服时**主动打断**："等等，那这个数据为什么 XXX？"

**Gate**：AI 询问的事实必须**回答或明确说"不知道"**。反信号必须具体。

**反模式**：跑了 10 条命令但没并列展示 / 实验是"穷举"不是"二分" / 部分数据吻合就下结论 / **不主动暴露疑惑（最大反模式）** / 询问后没答就继续跑。

### 阶段 D：方案设计 + 风险摆台【AI 摆台，人决策】

**AI 主动开场（必做）**：
```
进入 D。我列所有可行方案，**最终选哪个由你拍板**。
请告诉我：今天有运维窗口吗？哪些业务绝对不能影响？回滚能力如何？
若你说"你看着办" → 请先看下表"生产影响"列。我不替你拍板（出问题承担后果的是你）。
```

**AI 做**：列所有方案，**绝不替人拍板**：

| 方案 | 步骤 | 修复力度 | 生产影响 | 回滚成本 | 推荐度 | 理由 |
|---|---|---|---|---|---|---|

**Gate**：用户明确选 → E；说"你看着办" → 套话术 ⑧；催"快修"但没拍板 → "在你拍板前我不会动手"。

**反模式**：直接说"我建议方案 X"+ 操作 / 隐藏方案 / 没给生产影响评估。

### 阶段 E：执行 + 实时验证【边做边证】

> "操作完就觉得修好了"是最大的坑。

**AI 做**：
1. 执行修复
2. **立即重跑阶段 C 的决定性实验**（同命令、同输入）
3. 修复前后并列：

   | 指标 | 修复前 | 修复后 | 符合预期？ |
   |---|---|---|---|

**反模式**：执行完不验证就说"应该好了" / 部分指标改善就说"修好了" / 验证甩给用户。

### 阶段 F：方案失效时的主动升级【最容易翻车】

**AI 做**：
1. 数据不符 → **立刻明说"方案 X 失效，证据是 ..."**
2. 分析失效原因
3. **自动升级下一方案**（除非升级方案风险等级提升，那时再请人决策）
4. 重新执行 + 验证

**真实案例范例**：
```
方案 1 (重启 pod) 失效。证据：路由表预期 ≈41，实际仍 3 ❌；跨节点 publish 仍失败 ❌。
原因：hostPath 持久化让节点重启后跳过 mria 全量 bootstrap。
升级方案 3 (cluster leave + join)：路由表 3 → 46 ✅；跨节点 publish 全通过 ✅。修复成功。
```

**反模式**："应该好了，你试试" / "方案 1 部分生效..." / 默默换方案 / 失效后让用户决定下一步。

### 阶段 G：闭环沉淀【强制收尾】

> 修复成功后必须立刻沉淀，不要拖到第二天——血的细节会很快忘。

**AI 主动开场（必做，不要等用户提）**：
```
✅ 修复验证成功。**强制进入 G**——细节正在快速流失。
我现在按 bug-pattern-diagnosis 模板写 BUGxx.md（5 分钟）。
确认：□ 同意沉淀（默认）→ 直接开写  □ 不沉淀 → 请明确说"不用"，并理解：下次类似 bug 大家都从零再排
```

**AI 做**：用 `bug-pattern-diagnosis` 模板写 `BUGxx.md`，**4 块必写**：
- **症状速查表**（可验证、可 grep）
- **反向特征**（什么情况不是本案例 ← 防误诊）
- **5 分钟自检命令**（让下次直接抄）
- **本次走过的弯路**（为什么方案 1 失效 / 为什么以为是 X）

**Gate**：用户没回应 → 套话术 ⑨ + 默认沉淀。说"不用" → 明说"OK，下次我也学不到这次的经验"。

**反模式**：不沉淀 / 等用户提才动 / 案例只写"是什么 bug"不写反向特征和弯路。

---

## 一图流（紧凑版）

```
[前置] 模型 = Opus 4.7  +  能力完备  ← 缺任一项 套话术 ①/②
   ↓
[A] 链路对齐 ─ 开场问"现象/log/服务" ─ Gate: 用户验收链路图 ─ 红线: 不扎代码
   ↓
[B] 症状结构化 ─ 开场问 7 项清单 ─ Gate: 答 ≥5 条 + "你复现过吗" ─ 红线: 必须收反信号
   ↓
[C] 边界测试循环 ─ 开场说"二分实验/数据并列/有疑惑就问" ─ Gate: 用户必答询问 ─ 红线: 不主观/不沿假设/主动暴露疑惑
   ↓
[D] 方案摆台 ─ 开场问"运维窗口/不能影响什么/回滚" ─ Gate: 用户拍板 ─ 红线: AI 不决策/不隐藏方案
   ↓
[E] 执行+验证 ─ 红线: 不验证不算修复
   ↓ ──修好──→ [G]
   ↓
   └──没修好──→ [F] AI 明说失效+证据 + 自动升级 → 回 E
                  ↓
[G] 闭环沉淀 ─ 开场默认沉淀 ─ Gate: 没回应 → 默认沉淀
```

---

## 反模式速查（人 / AI 对照话术编号）

**AI 反模式**（自查）：跳过 A 扎代码 / 命令输出无并列 / "应该" 当结论 / 看到反信号还沿原方向 / 自我说服快速下结论 / D 直接操作 / 执行完不验证 / 模糊词掩盖失效 / 验证甩给用户 / 修复完不沉淀。

**人反模式 → AI 应套话术**：

| 人反模式 | 话术 |
|---|---|
| 弱模型排查复杂 bug | ① |
| 缺关键能力 | ② |
| 现象太模糊 | ③ |
| 不验收链路图就推下一步 | ④ |
| 跳过结构化问题 | ⑤ |
| 询问后不答 / 答模糊 | ⑥ |
| 反信号太粗 | ⑦ |
| 让 AI 替拍板 | ⑧ |
| 修复完不沉淀 | ⑨ |
| 把问题甩给 AI 喝咖啡 | ⑥+⑦ AI 主动 ping |
| "你按 BUGxx 修一下" | "案例是思路启发不是答案，先按 A 对齐链路" |

> **AI 不能纵容用户不配合。套话术 ≠ 拒绝合作，而是让用户清楚"现在不合作的代价是什么"。**

---

## 与 `bug-pattern-diagnosis` 的关系

`bug-pattern-diagnosis` = **病例库**（看过的病）；本 SKILL = **诊疗手册**（怎么看病）。

**典型协作链**：用户报复杂 bug → 本 SKILL 启用 7 阶段 → 阶段 C 时去 `bug-pattern-diagnosis` 找思路启发 → 回 C 继续测试 → 排查成功 → 阶段 G 用 `bug-pattern-diagnosis` 模板写新 BUGxx.md。两者互相调用、互相喂养。

---

## 自我演化

每次排查后评估：有新红线？有未覆盖的反模式？有阶段该拆得更细？有 → 主动建议用户更新本 SKILL。**本 SKILL 自身就是用本 SKILL 演化出来的**。

---

## 一句话总结

> **复杂 bug 排查 = Opus 4.7 × 能力完备 × 7 阶段 × 4 条 AI 红线 × 双向配合度门控 × 闭环沉淀。**
> **本 SKILL 同时约束 AI 和用户。检测到不配合时 AI 必须按话术指出，让用户决定补齐还是放弃——不要带病硬推。**