Skill: hgvgfgvh/complex-bug-debugging-with-ai (version 1.0.0)

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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)