debugging-and-error-recovery

name	debugging-and-error-recovery
description	Five-step triage for any failure. Use when tests fail, builds break, or behavior is unexpected.

调试与错误恢复

概述

本技能提供一套结构化的五步调试流程，确保任何故障都能被系统性地定位、修复并防止复发。核心原则：先复现，再定位，后修复。

何时使用

• 测试失败且原因不明
• 构建/部署流程中断
• 运行时行为与预期不符
• 性能退化或资源泄漏
• 线上告警或用户报障
• 不适用于：代码审查阶段的风格讨论、需求澄清

核心流程

步骤 1：复现（REPRODUCE）

• 获取一致的复现步骤，确保问题不是偶发
• 记录触发条件、输入数据、环境版本
• 如果无法在本地复现，检查环境差异（配置、依赖版本、数据状态）
• 线上问题：优先保留现场（日志、dump、快照），再尝试复现

步骤 2：定位（LOCALIZE）

• 通过二分法缩小范围：注释代码块、回退版本、二分 Git 历史
• 使用日志、断点、Profiler 等工具定位根因
• 区分症状和原因——不要停在表面
• 提出假设 → 设计实验 → 验证/排除

步骤 3：简化（REDUCE）

• 剥离无关代码，构造最小复现用例
• 最小用例有助于：确认根因、编写测试、加速修复
• 简化过程中可能发现真正的根因

步骤 4：修复（FIX）

• 修改前确保理解现有逻辑的设计意图
• 最小化改动范围——只改必要部分
• 修复后通过复现步骤验证问题已解决
• 检查是否还有同类问题（同一模式的其他位置）

步骤 5：防护（GUARD）

• 添加回归测试，覆盖本次修复的场景
• 考虑是否需要增强类型系统、断言或静态检查
• 更新文档或注释（如果原有文档已过时）
• 复盘：流程中哪个环节可以早期拦截此问题？

常见错误归因

合理化	现实
"这只是偶发，不用管"	如果无法稳定复现，说明没找到根因
"先改一下试试"	没有假设的修改是碰运气，引入新 bug 的风险很高
"加个日志再看看"	日志是手段不是终点，应该有明确要验证的假设
"这段代码之前能用的"	环境、数据、依赖都可能变化，过去能跑不等于现在没问题

红色警告

• ❌ 跳过复现直接修代码
• ❌ 同时改多个变量——无法判断哪个改动起了作用
• ❌ 改了代码但不跑测试
• ❌ 修复后没有添加回归测试
• ❌ 将线上问题归因为"巧合"或"玄学"

验证清单

• 有稳定的复现步骤，并能手动验证
• 已通过二分/日志等手段定位到根因（而非表层症状）
• 构造了最小复现用例（至少对复杂问题）
• 改动最小化，只修复根因
• 修复后复现用例通过
• 已添加回归测试，CI 通过
• 检查了代码库中是否有同类问题
• 复盘记录已更新（可选但推荐）