debugger

debugger skill 概览

debugger skill 能做什么

debugger skill 为 AI agent 提供了一套结构化的问题诊断方式，不是上来就靠猜。它专门面向 debugging 场景，比如代码报错、stack trace、崩溃、异常行为、偶发性故障，以及偏生产环境的故障排查——在这些情况下，找出根因往往比快速打个补丁更重要。

谁适合安装 debugger skill

这个 debugger skill 最适合：

• 想要可复用、可重复的 debugging 流程的开发者
• 用 AI 来排查 bug，而不只是写代码的团队
• 能提供日志、错误信息、复现步骤或代码上下文的用户
• 希望得到基于假设和证据的分析，而不是泛泛的“试试重装”建议的人

如果你的核心需求是从零生成全新代码，那它并不是最合适的选择。它更擅长处理“已有东西，但现在坏了”的情况。

它真正解决的任务是什么

大多数用户并不缺“debugging 小技巧”，他们真正需要 AI 帮忙回答的是：

• 到底哪里坏了
• 故障最可能从哪里开始
• 有哪些证据支持这个结论
• 下一步该测什么
• 怎样修复，且不会掩盖真正的问题

debugger skill 的价值在于，它会推动 agent 按顺序做事：先理解问题，再收集证据，形成假设，验证假设，定位根因，最后修复并验证。

为什么这个 debugger 不同于普通 prompt

普通 prompt 往往只能产出比较浅层的排查清单，或者一个带猜测成分的修复方案。这个用于 Debugging 的 debugger 更强的地方在于，它会引导 agent：

• 主动索取缺失的证据
• 区分症状和原因
• 给可能的解释排优先级
• 提出有针对性的测试
• 在提出修复方案后继续验证

这种结构能减少无效来回，尤其适合原因很多、现场又比较乱的问题。

安装前最值得关注的点

这个 skill 很轻量：仓库主要就是一个 SKILL.md，里面写清了 debugging 流程和适用场景。没有额外脚本、参考资料或 rules 目录需要先学。这让接入门槛很低，但也意味着输出质量会非常依赖你提供的上下文质量。

真正阻碍采用它的，通常不是安装复杂，而是输入太弱：没有复现步骤、没有日志、没有环境信息，也没有说明“预期行为应该是什么”。

如何使用 debugger skill

如何安装 debugger skill

如果你的 agent 环境支持从 GitHub 安装 Skills，可以从包含 awesome_agent_skills/debugger 的仓库路径安装 debugger skill。常见命令如下：

npx skills add Shubhamsaboo/awesome-llm-apps --skill debugger

如果你的环境使用的是别的 skill loader，就把它指向仓库中的 debugger skill 目录：
awesome_agent_skills/debugger

仓库里优先看什么

先看：

• SKILL.md

这个文件基本包含了所有关键的运行逻辑：

• 什么情况下该用这个 skill
• debugging 的处理流程
• agent 应该索取哪些证据
• 从诊断到验证的预期顺序

因为没有其他配套文件，所以快速读一遍 SKILL.md，就足以理解这个 skill 的思路。

什么情况下该调用 debugger，而不是用通用 coding agent

当你已经有明确的故障信号时，就该用 debugger usage，例如：

• 出现 exception 或 stack trace
• 某个测试开始失败
• 程序崩溃或卡死
• 性能变差，并怀疑是回归问题
• deploy、依赖升级或配置变更后行为发生变化
• 遇到需要逐步缩小范围的偶发 bug

不要把它作为功能设计或大范围重构时的首选工具。它是为故障隔离优化的。

debugger 最低需要哪些输入

想让 debugger guide 产出真正有用的结果，至少提供：

• 预期行为
• 实际行为
• 精确的错误信息或故障现象
• 复现步骤
• 相关代码片段或文件路径
• 环境信息：OS、runtime、framework 版本、配置差异
• 最近变更：deploy、依赖升级、feature flag、schema 变化

如果这些都没有，skill 仍然能帮忙，但 agent 大部分时间都会花在追问澄清信息上。

把模糊的 bug 描述改写成高质量 debugger prompt

弱 prompt：

My app is not working. Can you debug it?

更好的 prompt：

Use the debugger skill. Expected behavior: POST /checkout returns 200. Actual behavior: returns 500 for carts with discount codes. Started after upgrading stripe from 12.x to 13.x. Repro: apply code SAVE10, submit payment. Error log: TypeError: cannot read properties of undefined (reading 'amount_total') in payments/checkout.ts:84. Environment: Node 20, Next.js 14, production only. Please rank likely causes, identify the most probable root cause, and suggest the smallest safe fix plus validation steps.

更强的版本给了 agent 足够多的证据去推理，而不是让它靠猜。

一套实用且有效的 debugger 工作流

一个可靠的 debugger usage 流程通常是：

1. 先说清楚预期行为和实际行为。
2. 提供应复现步骤和故障证据。
3. 让 agent 按概率列出假设。
4. 让它为前 2–3 个假设给出最快、最有区分度的测试。
5. 把这些测试的结果反馈回去。
6. 只有在根因范围被明显缩小时，再要求修复方案。
7. 最后让它补充验证步骤和回归检查。

这正好符合该 skill 的核心设计，通常也比一开始就直接要补丁更容易做出正确判断。

debugger skill 通常会向你要什么

这个 skill 的流程核心就是收集以下信息：

• stack trace 和错误信息
• 日志
• 环境与配置细节
• 会触发问题的输入数据
• 故障发生前、发生中、发生后的系统状态

如果你能在一开始就把这些提供出来，整个交互会快很多，也会更具体。

如何用 debugger 处理偶发性问题

面对 flaky 或非确定性 bug，告诉 agent：

• 问题出现的频率
• 是否和负载、时序、并发或某类数据集相关
• 哪些因素已经被排除
• 问题是仅本地出现、仅生产出现，还是环境相关

然后让它给出：

• 按类别分组的候选原因
• instrumentation 思路
• 类似二分搜索的缩小范围方案
• 为了区分假设，最少需要增加哪些日志

这类场景下，debugger skill 往往比“一次性给我修好”的 prompt 更有价值。

如何用 debugger 分析 stack trace 和日志

分享 stack trace 时，不要只贴最后一行 exception。最好包含：

• 最顶部的错误行
• 你自己代码附近的相关 frames
• 触发问题的输入或请求
• 如果涉及多个系统，附上时间戳
• 故障前紧邻出现的相关 warning

你可以要求这个 skill 解释：

• 症状出现在哪一层
• 上游最可能是什么条件触发了它
• 哪个 frame 最值得优先处理
• 目前还缺哪些证据

怎样在不丢失诊断过程的前提下请求修复

一个常见错误是太早要求 agent 直接打补丁。更好的表达方式是：

Use the debugger skill. First identify the most likely root cause and the evidence for it. Then propose the smallest fix. Finally give me validation steps and one regression test to add.

这种提法能让工作流保持“证据优先”，同时又持续朝解决问题推进。

debugger skill 常见问题

debugger skill 对新手友好吗？

友好，前提是你能提供具体证据。新手通常会从中受益，因为这个 skill 会把排查过程拆成更易理解的步骤。但它不是魔法：如果你说不清最近改了什么、问题怎么复现、报错内容是什么，输出质量就会明显下降。

debugger 最擅长处理什么问题？

debugger 最强的场景包括：

• runtime error
• 测试失败
• 崩溃
• 某次变更后的回归问题
• 可疑日志
• 生产事故分诊
• “本地正常、线上不正常” 这类排查

对于“你能帮我审查整个架构吗？”这种比较泛的问题，它就没那么合适。

debugger 和普通 prompting 有什么不同？

普通 prompting 很容易从症状直接跳到修复。debugger skill 则专门围绕证据收集、假设排序、根因分析和验证来设计。这样通常能减少拍脑袋式回答，也更容易给出靠谱的下一步建议。

安装 debugger 会附带工具或脚本吗？

不会。这个 skill 目录里没有明显提供额外的支持工具。它本质上是 SKILL.md 中的一套指令型工作流，不是什么打包好的 debugger 二进制工具或脚本合集。更准确地说，它是一种面向 AI 辅助 debugging 的推理脚手架。

哪些情况下不该用 debugger？

以下情况建议跳过这个 skill：

• 你需要的是功能开发，而不是问题诊断
• 问题已经完全定位，只差代码生成
• 你无法提供任何有意义的上下文
• 你的真实问题是产品定义不清，而不是软件故障

这些情况下，coding、architecture 或 planning 类 skill 往往更合适。

debugger 能处理性能问题吗？

可以，但前提是你要提供度量数据或明确症状：慢接口、延迟尖峰、CPU 使用率、内存增长、最近变更、复现条件等。这样这个 skill 才能基于证据形成假设，并提出有针对性的测试，而不是给你泛泛的优化建议。

如何把 debugger skill 用得更好

给 debugger 的是证据，不是结论

糟糕的输入：

The database is probably the problem.

更好的输入：

API latency increased from 120ms to 2.4s after adding a join. EXPLAIN ANALYZE shows a sequential scan on orders. CPU is stable, DB IOPS spiked, and the slowdown happens only for accounts with more than 50k rows.

第二种写法让 debugger 能从事实出发推理，而不是直接继承你的先入判断。

每次请求都用“预期 vs 实际”来锚定问题

这是影响最大的改进点。始终说明：

• 本来应该发生什么
• 实际发生了什么
• 你是如何确认的
• 它出现的频率如何

这样可以避免 agent 朝错误目标优化。

要求给出排序后的假设，不要只要一个答案

一个适合 debugger for Debugging 的强 prompt 是：

Rank the top 3 likely causes from most to least probable, explain the evidence for each, and give one test that would eliminate each hypothesis.

这种写法比直接问“哪里有问题？”更容易形成高质量的 debugging 闭环。

尽早提供变更历史

很多 bug 的成因都来自：

• 依赖升级
• 配置变更
• 环境漂移
• deploy
• schema 或 API contract 变化

尽快告诉这个 skill 最近改了什么。很多时候，这比再多贴几段代码更能缩短定位根因的路径。

用有针对性的材料提升 debugger 输出质量

最有用的材料包括：

• 失败的测试输出
• 带上下文的 stack trace
• 故障时间窗口附近的日志
• 精确的请求 payload 或输入数据
• 最近变更的 diff
• 相关配置文件

如果你只能提供一种材料，优先给最小可复现的失败示例。

常见失败模式：太早要求修复

如果第一轮回答显得很泛，不要只说“展开讲讲”。更好的追问是：

What evidence is missing?
What is the fastest test to separate the top two hypotheses?
What would make you change your current diagnosis?

这类问题会迫使排查路径变得更尖锐、更可执行。

常见失败模式：一次性丢太多上下文

把整个仓库都塞进去，通常会降低信噪比。更好的起点是：

• 出问题的文件或函数
• 精确错误
• 复现步骤
• 最近变更
• 一两个相关文件

只有当 agent 明确指出某条依赖路径还缺上下文时，再继续补充。

收到第一次 debugger 响应后，怎样继续迭代

第一轮之后，建议这样推进：

1. 运行它建议的区分性测试
2. 只把测试结果返回给它
3. 让 agent 更新假设排序
4. 再要求最小且安全的修复方案
5. 最后要求验证方法和回归覆盖

这样可以让 debugger guide 始终聚焦，避免每一轮都从头重新分析。

如何从 debugger 拿到更靠谱的修复方案

当你准备进入打补丁阶段时，要求它提供：

• 用一句话总结根因
• 最小代码改动
• 为什么这个改动解决的是原因，而不只是症状
• 可能的副作用
• 验证步骤
• 一个防止再次发生的回归测试

这最后一步，才是真正把一次还不错的诊断，变成实际工作流里可靠的 debugger usage。