debugging-and-error-recovery
五步分诊：复现、定位、简化、修复、防护。止损规则、安全回退。
评分明细
适用场景
debugging-and-error-recovery 快速入门
把 AI 从”瞎试代码”变成”科学调试员”,系统化解决 Bug。
这是什么?解决什么问题?
调试 Bug 是程序员每天的必修课,但绝大多数人是这么做的:报错 → 凭直觉改一行 → 重启 → 还是报错 → 再改 → … 这种”瞎试”模式效率极低,常常引入新 Bug。
debugging-and-error-recovery 是 Google Chrome 团队(Addy Osmani 出品)的 Skill,它把调试过程拆成五个标准步骤:
- 复现(Reproduce):稳定重现 Bug
- 定位(Isolate):把问题缩小到最小范围
- 简化(Simplify):剥掉无关代码
- 修复(Fix):最小改动解决问题
- 防护(Prevent):加测试、加监控、防复发
每步都有具体的子规则,比如”止损规则”:如果 Bug 影响生产环境,第一步不是 debug,而是止损(回滚、限流、关闭功能)。“安全回退”:任何修复都要确保能干净回退,不留副作用。
这个 Skill 来自 Google Chrome 工程总监 Addy Osmani’s 个人仓库,GitHub 37k+ stars,是工程方法论类最权威的 Skill 之一。
准备工作
- 一个支持 Agent Skill 的 AI 客户端
- 任意编程语言环境
- 一个你正在调试的 Bug(或者随便找一个开源 issue 练习)
- 基本的日志/调试工具使用经验
3 步快速上手
第 1 步:克隆 Addy Osmani 的 agent-skills 仓库
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills
ls skills/debugging-and-error-recovery/
你会看到 SKILL.md、调试 checklist、根因分析方法。
第 2 步:加载 Skill
claude --skill debugging-and-error-recovery
第 3 步:让 AI 帮你调一个真实 Bug
描述你遇到的 Bug:
“我们的 React 应用在用户登录后,页面偶尔会白屏。控制台没报错,Network 也都 200。已经发生 3 次了,无法稳定复现。”
AI 会按 5 步法引导你:
[STEP 1: 复现]
- 何时发生?特定浏览器?特定网络?特定操作序列?
- 有 stack trace 吗?开启 Sentry?
- 上线后变更过什么?Git bisect?
[STEP 2: 定位]
- "白屏"通常意味着根组件抛错。打开 React DevTools 看 component tree。
- 加 Error Boundary 捕获错误。
- 检查 useEffect 清理函数是否正确。
[STEP 3: 简化]
- 注释掉最近的代码,看是否还复现。
- 创建最小复现 demo。
[STEP 4: 修复]
- 不要一次性改多处。先解决最可疑的一处。
- 加防御性检查。
[STEP 5: 防护]
- 加 Error Boundary。
- 加单元测试覆盖这个分支。
- 加 Sentry 上报。
常见踩坑
- 不先止损就 debug:生产环境出问题时,先去回滚/限流,debug 完再上。Skill 的”止损规则”就是这个意思。
- 同时改多处:很多 Bug 是多个因素叠加,你同时改 3 处,不知道哪处生效。Skill 强制每次只改一处。
- 不复现就修:无法稳定复现的 Bug 永远修不好。Skill 强调”先复现再说”。
- 不写测试就声称修复:没有测试,你怎么知道下次不会复发?Skill 强制写 regression test。
- 没看监控数据:日志、APM 工具(Sentry、Datadog)是调试的朋友,不要只靠 print。
- 甩锅给环境:很多人说”我本地没问题啊”,但生产配置、本地配置、依赖版本都可能不同。
初级用法
- 日常 Bug 调试:任何 Bug 都按 5 步法走,不要跳步。
- 学习调试技巧:Skill 内置很多通用调试启发法(检查最近变更、检查边界条件、检查并发)。
- 紧急事故响应:线上事故先按”止损规则”行动,再排查根因。
高级玩法
- 事故复盘模板:每次事故后,用 Skill 的 Postmortem 模板写复盘报告。
- 性能问题排查:5 步法同样适用于性能问题(慢请求、内存泄漏)。
- 跨团队 Bug 协调:用 Skill 的诊断报告作为沟通模板,减少推诿。
小技巧
- 调试前先把假设列出来(“我猜是 X”)。验证每个假设,直到找到根因。这种方法比”乱试”快得多。
- 复杂 Bug 不要怕二分法:每次排除一半的可能性,5-7 次就能锁定。
- 写修复 PR 时,说明”为什么这么改”,而不是只贴代码。未来的你会感谢现在的你。
- 重大事故复盘不要责怪个人,关注”为什么系统允许这个 Bug 发生”,改进流程而不是惩罚人。
- 用 Skill 时,告诉 AI “假设你不能在生产环境调试,只能看日志”,它会引导你更结构化思考。
常见问题 FAQ
Q1: 这个 Skill 跟 debugging-and-error-recovery 有什么关系?必须装吗?
A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。
Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?
A: debugging-and-error-recovery 来自 Google,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。
Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?
A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。
Q4: 怎么验证 Skill 装对了?
A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。
Q5: 这个 Skill 有许可证吗?能商用吗?
A: 取决于 debugging-and-error-recovery 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。
进阶学习建议
如果想进一步用好 debugging-and-error-recovery,建议按以下路径学习:
第 1 周:熟练使用
- 完成 3 步快速上手,跑通第一个任务
- 试 2-3 个不同场景的真实任务
- 记录”哪些 prompt 有效、哪些没用”——形成自己的 prompt 笔记
第 2 周:理解机制
- 阅读 Skill 的官方文档(README、SKILL.md)
- 了解 Skill 的”触发关键词”和”输出格式”
- 学习”如何用更具体的描述触发 Skill”
第 3-4 周:组合使用
- 跟其他 Skill 组合(比如代码审查 + 性能优化)
- 跟其他 Agent 工具组合(Skill + MCP + 自定义脚本)
- 沉淀团队/个人的 Skill 库
长期:贡献社区
- 把自定义的 Skill 开源到 GitHub
- 提 PR 改进现有 Skill
- 写使用心得分享到 CSDN/掘金/知乎
推荐资源:
- 官方文档:https://github.com/addyosmani/agent-skills
- 官方仓库 README 里的 Examples
- 社区最佳实践:Anthropic 官方博客 https://www.anthropic.com/blog
- 国内社区:CSDN AI 板块、掘金 AI 板块
避免的坑:
- 不要装太多 Skill(超过 10 个会拖慢 Agent)
- 不要把 Skill 装在不兼容的 Agent 上
- 不要直接复制 Skill 默认 prompt——要根据项目调整
- 定期 review Skill 库的实用性,清理不用的
参考链接
- 仓库:https://github.com/addyosmani/agent-skills
- Addy Osmani 博客:https://addyosmani.com/
- Google SRE Book(事故复盘章节):https://sre.google/sre-book/postmortem-culture/
- Debugging 经典书《Debugging by David Agans》:https://www.amazon.com/Debugging-Dominates-Development-Agans/dp/0814474578
- Chrome DevTools 调试指南:https://developer.chrome.com/docs/devtools/
本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。
debugging-and-error-recovery Skill 多维度简评
类别：工程方法 来源：addyosmani/agent-skills 定位：系统化调试——5 Whys 根因分析、错误模式识别、自动化恢复。
一、核心定位与价值
debugging-and-error-recovery 是 addyosmani/agent-skills 项目中的一个技能（Skill），该项目由 Google Chrome 工程总监 Addy Osmani 维护，旨在将生产级工程流程编码为 AI 编码代理可遵循的结构化工作流。该仓库在 GitHub 上拥有超过 59,000 个 Star。
核心价值：为 AI 编码代理提供系统化的调试方法论——当遇到错误时，不是简单地修补症状，而是通过结构化的根因分析（如 5 Whys 方法）、错误模式分类和自动化恢复策略来彻底解决问题。
二、核心能力清单
| 能力 | 说明 |
|---|---|
| 5 Whys 根因分析 | 通过连续追问”为什么”追溯问题的根本原因，而非停留在表面症状 |
| 错误模式分类 | 将错误归类为已知模式（如竞态条件、空指针、资源泄漏等），加速诊断 |
| 恢复策略 | 针对不同错误类型提供自动化恢复方案，包括回滚、重试、降级等 |
| 日志聚合分析 | 聚合分散的日志信息，构建完整的事件时间线 |
| Stack Trace 解析 | 自动解析堆栈跟踪，定位代码中的精确出错位置 |
三、工作原理
SKILL.md 结构
该 Skill 的核心是一个 SKILL.md 文件，包含 YAML 前置元数据和 Markdown 指令正文。根据 Agent Skills 开放规范，Skill 通过渐进式加载（Progressive Disclosure）机制工作：
- 元数据层（始终加载）：name 和 description 字段，约 100 词
- 指令层（触发时加载）：SKILL.md 正文，定义具体工作流
- 资源层（按需加载）：scripts/、references/ 等辅助文件
典型工作流
1. 收集错误信息 → 日志、stack trace、复现步骤
2. 分类错误模式 → 匹配已知的错误类型
3. 执行 5 Whys → 追溯根本原因
4. 制定恢复策略 → 选择最合适的修复方案
5. 验证修复 → 确认问题彻底解决
四、安装与配置
# 方式 1：通过 npx（推荐）
npx skills add addyosmani/agent-skills --skill debugging-and-error-recovery
# 方式 2：git clone
git clone https://github.com/addyosmani/agent-skills
cp -r skills/debugging-and-error-recovery ~/.claude/skills/
支持平台：Claude Code、Cursor、Gemini CLI、OpenCode、Codex 等。
五、适用场景
- 疑难 Bug 排查：当问题难以复现或根因不明确时
- 生产环境事故响应：快速定位问题、制定恢复方案
- 代码审查：在 PR 阶段预防性地识别潜在错误模式
- 技术债务清理：系统性地分析和修复历史遗留问题
六、注意事项
- 该 Skill 是声明式指令文件，而非可执行代码。其效果取决于所运行的 Agent 平台。
- 5 Whys 方法对于简单问题可能过度使用，应根据实际情况灵活应用。
- 本文基于官方文档和公开资料整理，未经过 MagicNetWorld 实测。
参考资料
- addyosmani/agent-skills 官方仓库 — GitHub 仓库
- Agent Skills 开放规范 — 官方规范网站
- Anthropic Skills 文档 — Claude Code 官方文档
- Superpowers 工程方法论 — obra/superpowers 仓库
- Agent Skills 设计原则 - Zread 深度解析 — 技术分析文章
快速安装
git clone https://github.com/addyosmani/agent-skills.git
cd agent-skills
ls skills/debugging-and-error-recovery/