调试Skill（debug）：用科学方法把“猜Bug”变成“追证据”的对话式调试伙伴
- 它是谁：调试Skill（英文名 debug，技能ID 11735）是一个可被用户主动调用的 AI 调试技能，通过自然对话、假设验证和根本原因分析来系统排查 Bug。
- 它怎么干活：不是直接甩出改法，而是先确认症状、做初步调查、给 Bug 分类，再生成竞争性假设，逐条找证据，最后提出最小修复并跑测试验证。
- 它的独特之处：内置“调查视角”体系（错误追踪、代码路径、依赖、状态、环境），复杂问题还可切到“团队模式”，让多个调查代理互相挑战假设。
- 它的底线：只报告验证过的观察，没有检查就明说“我还没看 X”，任何修改前都要先征得你的同意。
- 适合谁：被偶发 Bug、跨层 Bug、错误堆栈看半天没头绪折磨的开发者，以及希望把调试过程变得可追溯的团队。
该技能叫什么？如何下载安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 调试Skill |
| 技能英文名 | debug |
| 技能ID | 11735 |
| 技能定位 | 通过对话进行调查与根本原因分析的专家调试伙伴 |
| 是否可主动调用 | 是（user-invocable: true） |
| 参数提示 | 描述 bug、错误消息或意外行为 |
它解决什么问题
日常开发中的调试往往是这样的：看到一个报错，凭直觉改一处，再跑一遍，不行再改一处。这种“改代码试错”的方式在简单 Bug 上很快，但在下面几类问题上会快速失效：
- 错误信息指向的位置不是真正的出错位置（错误传播被掩盖）；
- 本地复现不了，线上偶发；
- 一次改动跨越前端、后端、数据库多层，说不清是哪一层的问题；
- 改了三天，每次都觉得“应该就是这个”，但都没修好。
调试Skill 的价值就在于把调试变成一件“有方法论”的事：先分类、再假设、再找证据、再修复验证，并且把整个证据链留痕。它不会替你在黑暗里乱猜，而是明确告诉你“这条假设被反驳了，原因是……”。
一键安装的思路与步骤
该技能遵循通用的 AI 技能装载机制，具体的安装入口、命令、下载地址与是否收费，请以官方说明为准。通用流程可以这样理解：
- 安装前提：你使用的 AI 编程环境支持技能（Skill）机制，并且该技能要求的工具集（任务委托、文件读写、代码搜索、命令执行等）可用。若想使用“团队模式”，还需要在设置中启用实验性代理团队开关
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS。 - 获取技能：通过官方技能市场、技能目录或团队内部技能仓库找到“调试Skill / debug / 技能ID 11735”，执行安装或启用操作；具体命令与入口以官方说明为准。
- 放入项目上下文：技能的约束要求它在行动前先阅读项目的
CLAUDE.md（架构、约定、优先级），如果存在CONSTITUTION.md和docs/specs/下的规范文档，也一并纳入。所以提前把这些文件准备好，会让调试结果明显更贴合你的项目。 - 验证是否生效：在会话中主动调用该技能，并给出一句 Bug 描述（对应参数提示“描述bug、错误消息或意外行为”）。如果它先复述症状、做初步调查、再用“您想让我……”的提议句式征求你的方向，就说明已经生效。
- 一个小提醒：如果调用后它直接开始大段猜测、或者一次给出多个未经证实的结论，说明上下文没准备好或者技能未正确加载，建议检查项目文档与安装状态。
该技能的主要功能和特点
- 对话式诊断，而不是一次性输出：全程以对话推进，先给你 1-2 句简要摘要，你想深入哪块再展开，符合“渐进式披露”的原则，不会一上来就淹没你。
- Bug 类型分类决策：根据描述自动归类——错误消息/堆栈跟踪、逻辑错误、集成失败、定时/异步问题、间歇性不稳定、性能下降、环境特定问题，不同类别匹配不同的调查路径和报告口径（例如“第 X 行的条件没有处理情况 Y”“API 期望 X 但我们发送 Y”“A 和 B 之间存在竞态”）。
- 多视角并行调查：内置五类调查视角——错误追踪、代码路径、依赖、状态、环境，复杂问题可把调查任务委托给不同的调查代理，再汇总结果。
- 假设管理与反驳机制：每个假设都要求附带支持证据，并允许被标记为“已反驳”并写明反驳原因，避免错误理论一路带偏。
- 标准模式与团队模式双档位：标准模式是一步一步共同解决，适合大多数 Bug；团队模式下多个调查代理测试竞争假设并互相挑战，适合难以捉摸的复杂问题。技能会自动根据“是否出现 3 个以上合理假设、是否跨多层系统、是否偶发或环境依赖、是否有矛盾证据、是否多次调试未果”来推荐档位。
- 修复必须最小化 + 必须验证：只提出最小改动，展示相关差异，等你批准后才应用，应用后运行测试并如实报告 PASS 还是 FAIL。
- 诚实约束：不允许伪造发现，不允许“解释自己还没找到的东西”，没检查过就直说“我还没有查看 X”。
- 结构化输出：最终结论按 DebugResult 结构呈现，包含根本原因（位置、一句话解释、证据列表）、修复（描述、差异、测试结果）和调查（测试过的假设、使用的视角、证据链）。
和普通调试方式比强在哪：普通工具给你的是“信息”（日志、断点、堆栈），这个技能给你的是“推理过程 + 证据链 + 可复现的修复验证”，并且整个过程你随时可以打断和纠偏。
如何使用该技能？
第 1 步：描述 Bug
调用技能时，直接用自然语言把症状说清楚，最好包含错误信息原文、复现步骤和发生环境。例如：
我们的订单结算接口在并发下单时偶尔返回 500，错误信息是
TypeError: Cannot read properties of undefined (reading 'price')，本地单线程测试复现不了，生产环境大约每 200 单出现 1 次。
第 2 步：接受初步调查与会话邀请
技能会先做一轮初步检查（例如查看代码仓库状态、寻找明显错误），然后给你一段摘要，并问你是否要深入某个方向、或者补充“问题是什么时候开始的”。这一步别急着说“你直接改”，多给一点上下文（最近有没有改过这块、有没有版本升级），命中率会更高。
第 3 步：选择执行模式
当初步调查完成后，技能会通过提问让你选择“标准”或“团队模式”，并给出推荐。大多数情况下选标准；如果它提示存在 3 个以上合理假设、或者问题跨前后端与数据库、或者是偶发问题，那么团队模式更值得一试。
第 4 步：跟随假设与证据
标准模式下，它会列出几条理论并标注哪条最可能、依据是什么，例如“理论 1 最可能，因为我看到结算服务里 price 字段来自一个可能为空的缓存对象”。你可以说“先查第一条”，也可以提出自己的怀疑方向。
第 5 步：确认根本原因
找到后，它会给出精确到“文件:行号”的定位、只展示相关代码片段，并用一句话解释问题。比如：
找到了。在
order/settle.ts:88，从缓存取出的商品快照在高并发下可能尚未写入完成，直接读取price就会取到 undefined。
第 6 步：批准最小修复并验证
它会展示拟修改的差异并说明为什么这样改能修好，问你是否应用。你确认后它应用改动、运行测试，并如实告诉你测试是通过还是失败。
第 7 步：收尾与后续建议
默认快速收尾（“完成！还有其他事吗？”），你如果要求详细总结，它会输出完整的调查过程。它也可能不催促地建议：“要不要为这个场景补一个测试用例？”或者“要不要检查一下这种写法在别处是否也存在？”
输出示例（结构化结果的样子）
- 根本原因：位置 =
order/settle.ts:88；解释 = 高并发下读取了未完成写入的缓存快照；证据 = 实际阅读的代码行、运行测试看到的失败用例、日志时间戳。 - 修复：描述 = 增加空值兜底并改为读取已落库数据；差异 = 实际代码改动；测试结果 = PASS。
- 调查：测试过的假设（含被反驳的及其原因）、使用的视角、从“症状 → 证据 → 根本原因”的证据链叙述。
同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 调试Skill（debug） | 对话式方法化调试伙伴 | Bug 分类、多视角调查、假设反驳、最小修复与测试验证、结构化证据链 | 需支持技能机制的 AI 编程环境；建议准备项目文档；团队模式需开启实验开关 | 偶发 Bug、跨层 Bug、多次调试未果的疑难问题 | 优势：过程透明、有证据链、可追溯；不足：依赖上下文质量，简单 Bug 上略显“重” |
| 传统断点调试器（如浏览器开发者工具、gdb、pdb） | 运行时观察工具 | 断点、单步、变量查看、调用栈 | 需要熟悉工具操作与调试技巧 | 本地可稳定复现的逻辑错误 | 优势：精确、实时；不足：偶发与线上问题难复现，不产出根因解释 |
日志与版本二分排查（日志分析 + git bisect） |
手动排查方法 | 定位引入问题的提交、关联时间线 | 需要良好日志与规范提交历史 | 回归类问题、版本升级后出现的故障 | 优势：能锁定“哪次改动引入”；不足：耗时长，需人工串联证据 |
| 错误监控平台（如 Sentry 类工具） | 线上错误聚合与告警 | 异常聚合、堆栈采集、影响面统计 | 需接入 SDK 与配置 | 线上错误发现与趋势监控 | 优势：覆盖面广、告警及时；不足：告诉你“哪里炸了”，不告诉你“为什么炸”以及怎么改 |
可以看到，调试Skill 并不替代调试器和监控平台，它补的是“从现象到根因推理”这一段最容易卡住人的环节。
该技能的典型应用场景与实际体验情况
场景一：线上偶发 500，本地死活复现不了
角色：后端开发。痛点是本地单线程跑一切正常，线上压测才偶发报错。使用方式：把错误信息、发生频率、环境差异一次性描述清楚，选择团队模式，让“状态”视角与“环境”视角分头调查并发与配置差异。实际体验：这类问题的关键往往在竞态与配置差异上，多视角并行确实比单人线性排查更容易撞出线索；需要注意的是，你必须提供足够的复现条件（频率、并发量、部署差异），否则调查代理只能泛泛而谈。
场景二：报错位置指向 A 文件，真凶在 B 文件
角色：全栈开发。痛点是被堆栈跟踪误导，改了三处无关代码。使用方式：选择标准模式，让技能沿“错误追踪 + 代码路径”两个视角跟踪错误传播链。实际体验：这是该技能最能体现价值的地方——它会明确告诉你“第 X 行的条件没有处理情况 Y”，并把证据链摆出来；注意不要在中途打断说“你先直接改这里”，那会破坏它的假设验证流程。
场景三：集成失败，说不清是谁的问题
角色：负责对接第三方接口的开发。痛点是对方说“我们没问题”，自己也不确定请求体哪里错了。使用方式：交给“依赖”视角，核对 API 合同、版本与请求/响应结构。实际体验：输出通常是“API 期望 X 但我们发送 Y”这种一句话结论，沟通成本显著下降；建议把接口文档或规范放进 docs/specs/，命中率更高。
场景四：性能突然下降，找不到瓶颈
角色：维护老系统的工程师。痛点是接口从 200ms 变成 2s，代码没大改。使用方式：归类为“性能下降”，围绕资源泄漏、算法复杂度、阻塞操作展开。实际体验：它能给出“瓶颈在 X 导致 Y”的方向性结论，但性能问题常有多个叠加因素，建议配合真实压测数据一起看。
整体上手难度：低。你只要会描述 Bug，剩下的由技能引导。真正的门槛在于“你有没有把项目约定写进 CLAUDE.md”——写得好，它像熟悉项目的老同事；没写，它需要多问几轮。
该技能能为用户带来的价值
- 把调试从“经验驱动”变成“方法驱动”：分类 → 假设 → 证据 → 反驳 → 最小修复 → 测试验证，这套流程一旦跑顺，团队里新人的排查水平会被拉齐。
- 显著降低“无效改动”的次数：任何修改前都要先提议、再等你批准，避免了“边猜边改”把代码越改越乱的风险。
- 让结论可追溯：DebugResult 结构把位置、证据、差异、测试结果固化下来，复盘和代码评审时能直接引用，不用再靠记忆复述“当时怎么查的”。
- 降低复杂问题的单人成本：团队模式让多个调查视角并行，把原本需要几个人一起盯的疑难 Bug，收敛成一次有组织的调查。
- 减少沟通摩擦：面向第三方或跨团队时，“API 期望 X 但我们发送 Y”这种带证据的一句话结论，比“我们这边没问题”有用得多。
- 长期价值：它鼓励把项目架构、约定、规范文档沉淀下来，这本身就是团队工程能力的提升。
常见问题 FAQ
Q1：这个技能怎么安装？会不会很麻烦？
A：它遵循通用的 AI 技能装载机制，在支持技能机制的环境中找到“调试Skill / debug / 技能ID 11735”启用即可，具体命令、入口与是否收费以官方说明为准。安装后建议先在项目里准备好 CLAUDE.md，有规范文档就放到 docs/specs/，这样它第一次上手就能贴着你的项目风格干活。
Q2：它会不问我就直接改我的代码吗？
A：不会。按照技能约束，它只提出方案并用“您想让我……？”的方式征求你的决定，展示拟修改的差异，等你批准后才应用改动。而且它要求只报告“实际读过、跑过、追过”的内容，没检查过的地方会明说“我还没有查看 X”。
Q3：标准模式和团队模式怎么选？
A：默认选标准，一步一步共同解决，大多数 Bug 够用。如果是偶发问题、跨前后端与数据库、或者你已经调试多次仍未解决，技能会主动推荐团队模式，让多个调查代理测试竞争假设并互相挑战。注意团队模式需要在设置中启用 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS。如果你只是想快速定位一个明显的小错误，没必要开团队模式——它更严谨，但也更“重”。
Q4：它和直接用 AI 编程助手聊 Bug 有什么区别？
A：普通对话往往是“你说症状、它给方案”，中间推理过程是不透明的。这个技能强制走完分类、假设、证据、反驳、验证的流程，并且最终输出结构化的根本原因与证据链。区别在“能不能验证”——它要求修复后必须跑测试并如实报告结果，而不是给完建议就结束。
Q5：适合谁用？会不会不适合新手？
A：新手反而更值得用。它会把调查思路一步步展示出来，等于有人在旁边示范“专业调试是怎么想的”。资深工程师则更适合拿它处理那些“凭经验也说不清”的疑难问题。唯一不太适合的场景是那种一眼就能看出来的拼写错误——这时候完整流程多少有点大材小用。