debugger

debugger skill 概览

debugger skill 是做什么用的

debugger skill 是一套结构化的调试流程，用来比泛泛一句“哪里出问题了？”更快定位根因。它适合处理这类情况：代码抛错、行为异常、改动后出现回归，或者只在某些环境里失败。它不会一上来就直接给修复方案，而是强调真实调试里更关键的顺序：复现、隔离、分析、修复、验证。

谁适合安装这个 debugger skill

这个 debugger skill 很适合开发者、AI coding agents，以及希望把 Debugging 变成可复用流程、而不是临时排障的技术团队。尤其适用于你经常只能从 stack trace、日志、零散 bug 描述，或不确定的复现步骤开始排查的场景。它的重点不是提供某个框架的深度专精，而是帮助你在不同项目里建立更稳定的调试纪律。

它帮你完成的核心任务

它真正解决的，并不是“解释一条错误信息”这么简单。更关键的是把一个模糊的失败现象，整理成一条清晰的调查路径：最近改了什么、怎么稳定复现、该从哪里缩小范围、要收集哪些证据、最后怎么验证修复是否真的有效。对那些总在靠猜、或者反复只修表象不修根因的团队来说，这个 debugger 安装包的价值会更明显。

为什么这个 debugger skill 值得装

它真正有区别的地方，在于“可执行”的工作流形态。仓库里包含：

• SKILL.md 中的分阶段调试流程
• references/checklist.md、references/errors.md 和 references/patterns.md 里的快速参考调试资料
• scripts/debug_report.py 这个可直接使用的调试报告生成器

这套组合让 debugger skill 比单纯的 prompt 模板更适合在线上事故式、实时排查式的工作。它不只是给你一句提示词，而是同时提供了流程、检查清单、常见失败类型，以及可交接的输出物。

它不打算替代什么

这不是某种语言专用 debugger、不是 IDE extension，也不是 tracing platform。它不能替代运行时工具、profiler，或者框架官方文档。如果你的核心需求是交互式单步调试、内存检查，或协议级 tracing，那就应该直接用对应工具，把这份 debugger 指南当作外层的推理和排查框架。

如何使用 debugger skill

安装位置与仓库路径

这个 skill 位于 zhaono1/agent-playbook 仓库中的 skills/debugger。如果你使用支持 GitHub 源的 skill loader，可以直接从仓库安装并指定 debugger skill。常见方式如下：

npx skills add https://github.com/zhaono1/agent-playbook --skill debugger

如果你的安装方式不同，关键点是要让 agent 能加载 skills/debugger 目录，从而访问 SKILL.md 以及配套的 references/ 和 scripts/ 文件。

建议先读这些文件

如果想尽快上手，建议按这个顺序阅读：

1. skills/debugger/SKILL.md
2. skills/debugger/references/checklist.md
3. skills/debugger/references/patterns.md
4. skills/debugger/references/errors.md
5. skills/debugger/scripts/debug_report.py

这个顺序基本对应真实的 debugger 使用路径：先理解流程，再看排查启发式方法，然后看错误分类，最后再看文档化支持工具。

debugger skill 在实际使用中是怎么触发的

这个仓库的设计目标，是在用户报告以下问题时启用：

• 某个 error 或 exception
• 行为不符合预期
• “debug this”
• “why isn’t this working?”

实际使用中，debugger skill 最适合在你明确把请求定义为“调试任务”，并且同时提供证据时触发。比如：

“Use the debugger skill. This API returns 500 only in staging. Expected 200. Started after yesterday’s deploy. Here is the stack trace, the endpoint, and the last 3 commits.”

这个提示会比一句“fix this bug”强得多。

debugger skill 需要什么输入

想把 debugger 用好，输入必须尽量具体。你能提供的越多越好，包括：

• 精确的错误文本
• stack trace
• 预期行为 vs 实际行为
• 可复现步骤
• 最近的代码或配置变更
• 环境信息
• 相关日志
• 已缩小范围的文件或组件

这个 skill 的流程本来就建立在“先收集证据”上，所以如果缺少复现步骤，或者没有实际输出，通常会比缺少实现细节更明显地拉低结果质量。

把模糊请求改写成高质量的 debugger 提示

弱提示：
“Why does this fail?”

更强的提示：
“Use the debugger skill to diagnose this failure. After upgrading dependencies, npm test fails in auth.spec.ts with TypeError: Cannot read properties of undefined. Expected tests to pass. Actual behavior: 6 failures on CI, 0 locally. Recent changes: lockfile update and config edit. Please help reproduce, isolate likely causes, rank hypotheses, and suggest the smallest safe fix.”

为什么这样的写法更有效：

• 明确说明了调试目标
• 给出了预期行为和实际行为
• 包含环境不一致的信息
• 包含最近改动
• 要求先调查再补丁，而不是直接改代码

推荐的 debugger 工作流

一个适合真实场景的 debugger 使用流程可以是：

1. 先精确复现问题。
2. 记录预期行为和实际行为。
3. 用 git log --oneline -10 检查最近变更。
4. 收集日志或 traces。
5. 通过最小复现或二分缩小范围。
6. 把失败归类到某种错误类型。
7. 形成若干根因假设。
8. 测试最小且最可能正确的修复。
9. 用回归覆盖验证结果。

这基本就是这个 skill 编码进去的思路；但当 agent 太早开始给修复方案时，显式按这个流程推进会更稳。

把参考文件当成决策辅助，而不只是附录

这些支持文件都不长，但对输出质量影响很大：

• references/checklist.md 用来保证排查过程不跑偏：复现、隔离、根因、修复、回归覆盖。
• references/patterns.md 在问题范围大、噪音多时尤其有用；它会提示你使用二分、定向日志、最小复现收敛等方法。
• references/errors.md 有助于归类常见失败，比如 null access、race conditions、config mismatches，以及 data shape drift。

当第一次 debugger 输出还比较泛时，就应该把这些文件拉进来用。它们更适合用来“磨尖调查路径”，而不是学习语法。

生成可复用的调试报告

如果你希望把调查过程沉淀成可交付的文档，可以使用：

python skills/debugger/scripts/debug_report.py --name "Checkout timeout in staging" --owner payments

它会生成一个 markdown 报告模板，包含 summary、environment、repro steps、logs、root cause、fix、regression tests 和 follow-ups 等栏目。对团队调试来说，这是仓库里最实用的部分之一，因为它能把原本一次性的排查过程，转成可评审、可交接的记录。

debugger skill 最适合哪些 Debugging 场景

这个 debugger skill 在以下场景最有价值：

• bug 可以复现，但原因并不明显
• 有日志，但噪音很大
• 故障是在某次变更之后出现的
• 问题跨越代码、配置和环境边界
• 你需要在改代码前，先走一遍有纪律的 triage 流程

相对来说，如果只是肉眼一看就能发现的小语法错误，或者必须依赖专有运维上下文、而 agent 无法访问的领域型事故，它的价值就没那么高。

提升 debugger 使用效果的实用技巧

可以明确要求这个 skill 把内容分成：

• facts
• hypotheses
• next checks
• proposed fix
• verification steps

这种结构能避免过早下结论。你还可以要求它按概率排序可能原因，并说明什么证据能够推翻每一个假设。这样一来，debugger skill 就不只是“聪明地猜”，而会更像一个真正的调查搭档。

debugger skill 常见问题

这个 debugger skill 比普通 prompt 更好吗

通常是的，尤其当问题本身包含多个步骤时。泛用 prompt 往往会从症状直接跳到猜测性的修复。debugger skill 更适合需要系统性缩小范围、收集证据和做验证的情况。不过如果 bug 非常简单、在一个代码片段里就完全可见，那普通 prompt 也可能已经够用。

debugger 安装后对新手友好吗

友好，因为它的核心流程简单、具体，而且容易照着执行。新手会从分阶段流程和 checklist 中明显受益。需要注意的是，这个 skill 默认你至少能提供一些证据，比如日志、stack trace 或复现步骤。没有这些信息时，任何 debugger 指南都会更容易退化成“猜”。

这个 debugger skill 可以配合任意语言或技术栈使用吗

大体上可以。这个 debugger skill 是以流程为中心，而不是绑定单一语言。它举的错误示例也更偏通用，而非框架专属。这让它具备较好的可迁移性，但也意味着如果你想得到最佳结果，往往还是要自己补充一些栈相关的上下文。

什么情况下不该使用这个 debugger skill

以下情况建议跳过：

• 你更需要交互式运行时调试，而不是推理层帮助
• 问题完全是运维层面的，而 agent 又无法访问系统
• bug 已经确认只是一个一行 typo
• 你需要仓库中并不包含的厂商或供应商专有知识

在这些场景下，应该优先使用直接工具或领域文档。

它对团队交接和事故后续跟进有帮助吗

有。debug_report.py 是最能体现这个 debugger skill 不只是为一次性对话而设计的部分。它能把一轮调试会话沉淀成可复用报告，记录 owner、repro steps、root cause、fix 和 follow-ups。

如何把 debugger skill 用得更好

给 debugger skill 的是证据，不只是症状

提升 debugger 输出质量最快的方法，就是直接附上原始证据：

• 实际运行的命令
• 完整错误文本
• 触发失败的输入
• 出问题的环境
• 最近的 commit 范围
• 你已经尝试过什么

“Here is the stack trace and the last good commit” 远比“it’s broken after my changes”更有帮助。

尽早强制收敛到最小复现

debugger 使用中的一个常见失败模式，是一开始就排查太大的表面范围。你应该要求这个 skill 帮你构造最小可复现案例。这样往往能更快剥离框架初始化、无关服务或脏状态带来的噪音，让根因更快浮出来。

要求对假设进行排序

当多个原因都说得通时，直接让 debugger skill 按“发生概率”和“验证成本”双重维度排序。这样你会得到更合理的调查顺序。比如：

“List the top 3 root-cause hypotheses, what evidence supports each, and the next cheapest check to confirm or reject them.”

这在 flaky tests、integration failures，以及 config drift 这类问题上尤其有用。

把根因和修复质量分开看

另一个常见问题，是看到某个修复让症状消失，就直接接受它。更好的做法是用这个 debugger 指南继续追问：

• 为什么会发生
• 是什么条件让它得以发生
• 应该补什么 regression test 才能证明它不会再回来

对于 null handling、race conditions、mismatched config 这类反复出现的问题，这一点尤其关键。

用仓库上下文提升第一次输出质量

如果 bug 出在你自己的代码库里，尽量补充这些信息：

• 怀疑的文件
• package 或 service 边界
• deploy 时间点
• 涉及的配置文件
• 问题是否只发生在 local、CI、staging 或 production

当 debugger skill 能把证据和系统边界关联起来时，它的表现会比只靠一段贴出来的 stack trace 推理好很多。

用 references 文件修正泛泛而谈的回答

如果第一轮回答太泛，可以明确要求 agent 使用：

• references/checklist.md 来补齐流程完整性
• references/patterns.md 来选择隔离方法
• references/errors.md 来匹配错误家族

这是提升 debugger 效果的一个很实用的方法，不需要你把整个 prompt 从头重写。

第一轮调试之后继续迭代

好的 debugger 使用方式一定是迭代式的。拿到第一轮输出后：

1. 先执行一个建议检查项
2. 把结果带回来
3. 让 skill 更新假设
4. 然后再改代码

这正是 debugger skill 比静态 debugger 指南更有价值的地方：它能帮助你逐步收敛，而不是一次性生成一大段猜测性的答案。

结束前补上回归证明

仓库里的 checklist 明确包含 regression coverage，而这也确实应该是调试的收尾位置。你可以要求 debugger skill 提出“下次还能抓住这个问题”的最小测试、断言或监控检查。没有验证的修复，通常都不算完整的 Debugging，尤其是在间歇性故障或环境相关故障里更是如此。