debugging-and-error-recovery

指导系统化的根因调试。在测试失败、构建中断、行为与预期不符，或遇到任何意外错误时使用。当需要系统化地查找并修复根因而非猜测时使用。

提供方:addyosmani/agent-skills调用次数:6.2k收藏:★ 315更新:2026/08/28

技能说明addyosmani/agent-skills

指导系统化的根因调试。在测试失败、构建中断、行为与预期不符，或遇到任何意外错误时使用。当需要系统化地查找并修复根因而非猜测时使用。

本技能提供一套系统化的根因调试方法。当测试失败、构建中断、运行行为与预期不符或出现意外错误时，引导你按照结构化流程定位并修复问题根因，避免靠猜测浪费时间。它通过"停止-保留-诊断-修复-防护-恢复"的流程，帮助你在出错时保持清晰思路。

本技能供 Agent 在调试场景下自动引用，无需手动安装。当遇到上述使用场景时，Agent 将按以下六个步骤依次执行：

停止行动（Stop-the-Line）：遇到意外情况时，立即停止添加新功能或修改代码，保留错误输出、日志和复现步骤作为证据，再进入诊断流程。

Triage 检查清单（按顺序执行，不可跳步）：

复现（Reproduce）：确认失败是否可稳定复现。若无法复现，需根据时序、环境或状态依赖收集更多上下文。运行测试可用（以下为 npm 示例，可替换为仓库自身测试命令）：
```
npm test -- --grep "test name"
npm test -- --verbose
npm test -- --testPathPattern="specific-file" --runInBand
```
定位（Localize）：判断失败发生在哪一层——UI/前端、API/后端、数据库、构建工具、外部服务还是测试本身。对回归 bug 可使用 git bisect 定位引入问题的提交：
```
git bisect start
git bisect bad
git bisect good <known-good-sha>
git bisect run npm test -- --grep "failing test"
```
最小化（Reduce）：移除无关代码、简化输入，构造最小复现用例，让根因暴露。
修复根因（Fix the Root Cause）：修复根本问题而非表面症状。
防止复发（Guard Against Recurrence）：为具体失败编写回归测试，确保修复有效且不会再次被破坏。
端到端验证（Verify End-to-End）：运行完整测试套件和构建命令，确认无回归：
```
npm test
npm run build
```