复杂 bug 与 AI 协作排查的元方法论。当用户报告"诡异 / 间歇性 / 多层因素 / 重启不愈 / 多系统协作 / 已经排查很久没头绪"的 bug 时,启用本 SKILL 的 7 阶段协作工作流:"业务链路对齐 → 症状结构化 → 边界测试循环 → 方案摆台 → 执行验证 → 失效升级 → 闭环沉淀"。本...
---
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 必须按话术指出,让用户决定补齐还是放弃——不要带病硬推。**
don't have the plugin yet? install it then click "run inline in claude" again.