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 | 应成功 | 失败 ❌ | ✗ 异常点 |

1. 自检"实际 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 必须按话术指出，让用户决定补齐还是放弃——不要带病硬推。