debugging-and-error-recovery

debugging-and-error-recovery 快速入门

把 AI 从”瞎试代码”变成”科学调试员”,系统化解决 Bug。

这是什么?解决什么问题?

调试 Bug 是程序员每天的必修课,但绝大多数人是这么做的:报错 → 凭直觉改一行 → 重启 → 还是报错 → 再改 → … 这种”瞎试”模式效率极低,常常引入新 Bug。

debugging-and-error-recovery 是 Google Chrome 团队(Addy Osmani 出品)的 Skill,它把调试过程拆成五个标准步骤:

1. 复现(Reproduce):稳定重现 Bug
2. 定位(Isolate):把问题缩小到最小范围
3. 简化(Simplify):剥掉无关代码
4. 修复(Fix):最小改动解决问题
5. 防护(Prevent):加测试、加监控、防复发

每步都有具体的子规则,比如”止损规则”:如果 Bug 影响生产环境,第一步不是 debug,而是止损(回滚、限流、关闭功能)。“安全回退”:任何修复都要确保能干净回退,不留副作用。

这个 Skill 来自 Google Chrome 工程总监 Addy Osmani 的个人仓库,是工程方法论类最权威的 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 上报。

常见踩坑

1. 不先止损就 debug:生产环境出问题时,先去回滚/限流,debug 完再上。Skill 的”止损规则”就是这个意思。
2. 同时改多处:很多 Bug 是多个因素叠加,你同时改 3 处,不知道哪处生效。Skill 强制每次只改一处。
3. 不复现就修:无法稳定复现的 Bug 永远修不好。Skill 强调”先复现再说”。
4. 不写测试就声称修复:没有测试,你怎么知道下次不会复发?Skill 强制写 regression test。
5. 没看监控数据:日志、APM 工具(Sentry、Datadog)是调试的朋友,不要只靠 print。
6. 甩锅给环境:很多人说”我本地没问题啊”,但生产配置、本地配置、依赖版本都可能不同。

初级用法

• 日常 Bug 调试:任何 Bug 都按 5 步法走,不要跳步。
• 学习调试技巧:Skill 内置很多通用调试启发法(检查最近变更、检查边界条件、检查并发)。
• 紧急事故响应:线上事故先按”止损规则”行动,再排查根因。

高级玩法

• 事故复盘模板:每次事故后,用 Skill 的 Postmortem 模板写复盘报告。
• 性能问题排查:5 步法同样适用于性能问题(慢请求、内存泄漏)。
• 跨团队 Bug 协调:用 Skill 的诊断报告作为沟通模板,减少推诿。

小技巧

• 调试前先把假设列出来(“我猜是 X”)。验证每个假设,直到找到根因。这种方法比”乱试”快得多。
• 复杂 Bug 不要怕二分法:每次排除一半的可能性,5-7 次就能锁定。
• 写修复 PR 时,说明”为什么这么改”,而不是只贴代码。未来的你会感谢现在的你。
• 重大事故复盘不要责怪个人,关注”为什么系统允许这个 Bug 发生”,改进流程而不是惩罚人。
• 用 Skill 时,告诉 AI “假设你不能在生产环境调试,只能看日志”,它会引导你更结构化思考。

进阶实践

debugging-and-error-recovery 是「工程方法论」类 Skill，进阶不在于「用几周」，而在于把五步分诊内化到日常与事故场景。建议这样迭代：

先把五步跑成”肌肉记忆”

• 复现（Reproduce）：写出可粘贴给他人的最短复现步骤 + 期望 vs 实际；无法稳定复现的 Bug 先补日志/tracing，不要跳步
• 定位（Isolate）：用 git bisect、feature flag、Error Boundary 把范围切到”最近改了什么”或”哪个模块”
• 简化（Simplify）：把复现精简到 <50 行的最小 demo，很多 Bug 会在这一步自己现身
• 修复（Fix）：一次只改一处，改动同时写 regression test
• 防护（Prevent）：Sentry 上报、CI 断言、告警阈值、Runbook 三件套

把「止损规则」写进 Runbook

• 生产环境出问题 → 先回滚 / 限流 / 关功能开关，再排查根因，别为了”想弄明白”让故障继续放血
• 每次修复必须保证可干净 revert：改配置留旧值、改 schema 走 expand-contract、改 API 保留旧字段一个版本

引入 Postmortem 复盘习惯

• 参考 Google SRE Book 的无责复盘模板：时间线、影响面、根因（不止一个）、行动项、经验教训
• 每个行动项必须有 owner + due date，进 backlog 跟踪，避免”复盘完就散会”
• 复盘不评判个人，只评判系统与流程 —— 关注”为什么这个 Bug 能溜进生产”，而不是”谁写的这行代码”

把 Skill 嵌进你的 Agent 工作流

• Claude Code / Cursor：把仓库 clone 到本地，把 debugging-and-error-recovery/SKILL.md 加入项目 CLAUDE.md 或 .cursor/rules/，触发词命中即自动加载
• 与 systematic-debugging、writing-plans、requesting-code-review 三个 Skill 组合：Bug 定位 → 修复计划 → 提交自检，形成闭环
• 事故场景可选走 .gemini/commands/ 里的 slash-command，直接以命令启动分诊流程

长期沉淀

• 每次事故复盘产物归档到团队 wiki，按「症状类别 × 根因类别」建立可检索的事故知识库
• 把典型 Bug（并发、边界、幂等、内存泄漏）沉淀成本团队的调试 checklist，作为新人 onboarding 材料

参考链接

• 仓库
• Addy Osmani 博客
• Google SRE Book（事故复盘章节）
• Debugging 经典书《Debugging by David Agans》
• Chrome DevTools 调试指南