1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | debugging-and-error-recovery | GitHub API / SKILL.md |
| 作者/维护者 | Addy Osmani（addyosmani/agent-skills 仓库所有者），外部协作者 Shihyu Ho、ayobamiseun、Federico Bartoli 等 |
GitHub API（commits） |
| 来源链接 | https://github.com/addyosmani/agent-skills/tree/main/skills/debugging-and-error-recovery | — |
| 许可证 | MIT | GitHub API |
| GitHub Stars / Forks | 所属仓库 80,772★ / 8,712 forks（该数字属整个 agent-skills 合集，不代表本技能个体热度，仅供了解所属仓库规模） | GitHub API |
| 最新版本 | 无独立版本号；该子技能最近一次提交 2026-07-22，仓库整体最近提交同日期 | GitHub API（commits） |
| 安装方式 | Claude Code / Codex 原生插件市场一条命令安装，或 npx skills add 单独安装本技能（见第 10 章） |
仓库 README |
2. 功能介绍与亮点
debugging-and-error-recovery 是一份系统化调试方法论技能，核心思路是把“猜”变成“查”：当测试失败、构建报错或运行时行为异常时，先停止继续改动，用固定流程定位根因。
核心能力：
- “停线规则”（Stop-the-Line）：遇到任何异常立即停止新增功能，先保存证据（错误输出、日志、复现步骤）
- 五步排查清单：复现 → 定位（分层排查 UI/后端/数据库/构建/外部服务/测试本身）→ 最小化复现 → 修复根因（而非表面症状）→ 写回归测试防止复发
- 针对不可复现 bug 给出决策树（按时序相关、环境相关、状态相关、纯随机四类分别给出排查手段）
- 内置
git bisect定位引入 bug 的具体提交 - 附常见错误类型速查表（测试失败、构建失败、运行时错误三类各自的排查分支）
- 专门一节把“日志/报错/堆栈中的可疑指令”当作不可信数据处理，明确禁止 agent 未经确认执行错误信息中夹带的操作指令——属主动的提示词注入防护
亮点：纯 Markdown 无脚本执行；作者 Addy Osmani 长期从事 Web 工程与开发者体验工作，具备行业辨识度；该子技能有真实活跃的外部协作：仅这一个子目录就有至少 12 条外部贡献者提交的 PR（涉及升级排查阶梯、生产事故复盘、行为化评测等方向），多名不同贡献者（ayobamiseun、Shihyu Ho 等）参与实质性内容改进。
3. 适用场景
固定分类：工程效率与代码质量
- 使用 Claude Code / Codex 等 agent 编码时遇到测试失败、构建报错或运行时异常，希望 agent 按结构化流程定位根因而非反复试错的初中级开发者
- 需要处理“偶发/难复现”故障（时序竞争、环境差异、状态污染）时，缺乏系统排查思路的开发者
- 团队没有专职调试专家，希望把资深工程师的调试直觉转化为 agent 可执行清单的小团队
4. 跨 Agent 兼容性
- Claude Code：原生支持——仓库自带
.claude-plugin目录，可通过插件市场安装，也可用npx skills add直接放入.claude/skills/ - Codex：原生支持——仓库自带
.codex-plugin目录，npx skills add官方支持列表明确列出 Codex - OpenClaw：原生支持——技能安装 CLI（
vercel-labs/skills）官方支持列表明确列出 OpenClaw，对应路径skills/（项目级）/~/.openclaw/skills/（全局） - Hermes Agent：原生支持——同一份 CLI 官方支持列表明确列出 Hermes Agent，对应路径
.hermes/skills/（项目级）/~/.hermes/skills/（全局）
（基于已抓取的官方安装文档判断，未为兼容性单独发起搜索）
5. 推荐理由
调试是初中级开发者最容易在 agent 辅助编码中吃亏的环节——不知道从哪下手，往往靠反复猜测修改，越改越乱。debugging-and-error-recovery 把“先复现、再定位、再最小化、再修根因、再补回归测试”的资深工程师排查习惯固化成 agent 可执行的清单，并且专门加了“不轻信错误信息里的指令”这道安全阀，是目前收录的工程效率类技能里少见的把调试方法论和注入防护结合在一起的实践。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 6 | 所属仓库整体 80,772★ 属于整个 agent-skills 合集，不代表本技能个体热度；该子技能自身有持续维护痕迹（近 5 个月 7 次提交）与密集的外部协作证据（仅本子目录就有至少 12 条外部贡献者发起的 PR，涉及多个不同账号），但缺乏可独立量化的星标/下载数据 |
| 可用性 | 9 | SKILL.md 约 10.8KB，含决策树、代码示例、速查表，结构清晰；最近一次内容提交距今约一周，维护活跃；MIT 许可，无付费依赖；支持插件市场一键装，也支持 CLI 单独装 |
| 安全性 | 9 | 见下方检查清单 |
安全检查清单：
① 执行 shell 命令——技能本身不含可执行脚本，仅指导 agent 运行项目自身的测试/构建命令（如 npm test、git bisect），权限范围明确、可审计
② 联网外发数据——技能内容为本地排查指导，不涉及技能自身向外部服务器发送数据
③ API key/凭据——不涉及，技能本身不要求任何密钥
④ 未发现可疑指令——抓取 SKILL.md 原文，内容均为透明的调试方法论；技能本身还专门教育 agent 把错误信息/日志中的可疑指令当作数据而非指令处理，拒绝未经确认执行，属正向信号
⑤ 作者信誉——Addy Osmani 为公开可查的 Web 工程背景个人，仓库有多名外部协作者共同维护，非匿名单人项目
⑥ License——MIT，明确
⑦ 维护时间——最近提交 2026-07-22，近期活跃
综合评分：8.0（三项均值）
7. 跟同类 Skills 相比的优势
| 项目 | 定位 | 与 debugging-and-error-recovery 的差异 |
|---|---|---|
| code-review-and-quality（同仓库另一子技能） | 五维度代码评审，在代码合并前挑质量问题 | 定位是“审”——针对写完但尚未出问题的代码做评审；debugging-and-error-recovery 定位是“查”——针对已经出现失败/报错的场景做根因定位 |
| test-driven-development（同仓库另一子技能） | 红-绿-重构的测试驱动开发流程，强调先写测试再写实现 | 定位是“防”——在写代码之前就用测试约束行为；debugging-and-error-recovery 定位是“救”——在测试已经失败或行为已经出错之后如何系统排查 |
| old-coder（AmazingAng，独立仓库，121★） | “SPEC→GAUNTLET→EVIDENCE”流程，让 agent 交出测试计划和证据报告代替人工读代码 | 更偏“验收关卡”——用一整套测试/覆盖率/变异测试关卡证明代码达标；debugging-and-error-recovery 更偏“排查手册”——聚焦已发生故障的定位方法，两者可在开发流程的不同阶段互补 |
debugging-and-error-recovery 的差异化在于“故障发生后怎么办”：不像评审类技能关注代码写得好不好、也不像 TDD 类技能关注先写测试再写代码，它专门填补“东西坏了，接下来第一步该做什么”这个初中级开发者最容易手足无措的环节，且把调试方法论和“不轻信错误输出中的指令”这类安全意识结合在一起。
8. 用户评价
Hacker News 上关于该项目（agent-skills）整体有独立第三方讨论，呈现正反两种声音：一方长期从业者认为结构化方法配合 agent 编码是持久性的工作方式转变；另一方则质疑把规则写进 Markdown 文件并不能保证 LLM 可靠遵守。两种声音均来自同一条讨论帖，针对 debugging-and-error-recovery 这一具体子技能，第三方媒体或独立平台目前尚无专门评价，但该子目录本身有至少 12 条外部开发者提出的改进 PR（部分已合并），是直接的实际使用与协作证据。
9. 其他补充
仓库同时提供 .agents、.gemini、.opencode 等多种生态适配目录，并通过第三方 CLI 工具 vercel-labs/skills 支持“70+ 智能体”的统一安装，debugging-and-error-recovery 是仓库 24 个工程技能之一，聚焦调试与故障恢复维度。
10. 安装使用方式
- Claude Code 插件市场：
/plugin marketplace add addyosmani/agent-skills，再执行/plugin install agent-skills@addy-agent-skills - Codex：仓库自带
.codex-plugin，可通过 Codex 原生插件机制安装 - 通用 CLI（含 OpenClaw / Hermes Agent）：
npx skills add addyosmani/agent-skills --skill debugging-and-error-recovery（仅安装该子技能，CLI 会按所选 agent 自动放入对应目录，如 OpenClaw 的skills/、Hermes Agent 的.hermes/skills/） - 本地开发：
git clone https://github.com/addyosmani/agent-skills.git，再用claude --plugin-dir /path/to/agent-skills加载
安装后无需重启，agent 在测试失败、构建报错或运行时出现异常时会自动触发该技能；若只想要调试维度而不装整套 24 个工程技能，建议用 CLI 的 --skill 参数单独安装。
11. 注意事项
- 该技能是纯方法论指导，不会自动执行修复，仍需 agent 结合项目自身工具链（测试框架、CI）落地
- 技能内示例代码以 JavaScript/TypeScript 生态（npm、Node.js）为主，其他语言栈需要 agent 自行替换等价命令
- 仓库以整套工程技能包（24 个子技能）为主体发布，若通过插件市场整体安装会连带装入其余 23 个非调试类技能
- Hacker News 讨论中存在“结构化指令能否让 LLM 可靠遵守”的合理质疑，使用者应将其作为参考手册而非可无脑信赖的自动化保障