performing-systematic-debugging-for-stubborn-problems

使用 Fagan 检查法进行系统化调试

当面对复杂问题或多次尝试修复仍未解决的顽固 Bug 时，此技能会采用经过修改的 Fagan 检查法，以系统化地解决问题。

流程概述

依次遵循以下四个阶段。不要跳过任何阶段，也不要在完成检查之前尝试修复。

阶段 1：初步概述

在分析之前，先清楚地了解问题：

• 用通俗的语言说明问题，避免使用专业术语
• 说明预期行为——应该发生什么
• 说明实际行为——实际发生了什么
• 记录症状——错误消息、日志、可观察到的故障
• 背景信息——问题何时发生、发生频率如何、在什么条件下发生

**输出：**任何人都能理解的清晰问题描述。

阶段 2：系统化检查

以 Fagan 检查法中“阅读者”的角色逐行检查。先识别缺陷，不要尝试修复——此阶段只进行检查。

根据以下缺陷类别进行检查：

1. 逻辑错误

   • 条件逻辑不正确（运算符错误、条件颠倒）
   • 循环条件有误（无限循环、提前终止）
   • 控制流问题（无法到达的代码、错误的执行路径）

2. 边界条件

   • 差一错误
   • 边缘情况（空输入、null 值、最大值）
   • 数组／集合越界

3. 错误处理

   • 未处理的异常
   • 缺少校验
   • 静默失败（捕获错误但未记录）
   • 错误恢复不当

4. 数据流问题

   • 变量作用域问题
   • 数据转换错误
   • 类型不匹配或类型强制转换问题
   • 状态管理问题（数据过时、竞态条件）

5. 集成点

   • API 调用（端点错误、请求格式错误、缺少请求头）
   • 数据库交互（查询错误、事务处理问题）
   • 外部依赖项（版本不匹配、配置问题）
   • 时序问题（async/await 问题、竞态条件）

在此阶段边想边说。对于每段代码：

• 说明代码的预期用途
• 找出意图与实现之间的差异
• 指出假设或不明确之处
• 对复杂部分使用 ultrathink 深入思考

**输出：**按类别整理的缺陷清单，附上行号和具体描述。

阶段 3：根因分析

识别问题后，追溯并找出根本原因，而不只是表面症状。

五个为什么法：

• 反复追问“为什么”（至少 3–5 次），直到找到根本问题
• 在分析中明确写出每个“为什么”
• 示例：
  • 为什么 API 调用失败？→ 因为请求格式错误
  • 为什么请求格式错误？→ 因为数据序列化不正确
  • 为什么数据没有正确序列化？→ 因为序列化器期望的是另一种类型
  • 为什么它期望的是另一种类型？→ 因为架构已更新，但代码没有更新
  • 根因：服务之间的架构版本不匹配

请考虑：

• 环境因素（配置、依赖项、运行时环境）
• 时序与并发（竞态条件、异步问题）
• 代码或系统设计中的隐含假设
• 历史背景（近期更改、迁移、更新）

明确说明假设：

• “我假设 X，因为……”
• “这预设 Y 始终……”
• 指出所有需要验证的假设

**输出：**清晰陈述根因、推导该结论的推理链，以及任何需要验证的假设。

第 4 阶段：解决方案与验证

现在针对每个已识别的问题提出具体修复方案。

对于每个拟议的解决方案：

1. 描述修复方案 - 需要进行哪些代码／配置更改
2. 解释为何能解决根本原因 - 将方案与第 3 阶段的分析联系起来
3. 考虑副作用 - 此更改还可能影响什么
4. 定义验证步骤 - 如何确认修复有效

验证规划：

• 能够发现此 Bug 的具体测试用例
• 手动验证步骤
• 要添加的监控或日志
• 要验证的边缘情况

输出： 包含验证步骤的结构化修复方案列表。

重要指南

• 在进入下一阶段前，彻底完成当前阶段
• 边思考边说明 - 全程口述推理过程
• 明确陈述假设，不要隐含假设
• 标出不明确之处，不要猜测——如果有不确定之处，请直接说明
• 使用可用工具 - 读取文件、搜索代码、运行测试、查看日志
• 着重进行系统性分析，不要只求快速修复
• 验证已标记的方面 - 完成所有阶段后，重新检查任何不明确之处，并在需要时使用 think 工具进行“ultra”深度分析以澄清

最终输出

完成全部四个阶段后，提供：

1. 调查结果摘要 - 主要缺陷及其根本原因
2. 拟议解决方案 - 按优先级排序并说明理由
3. 验证计划 - 如何确认修复有效
4. 后续步骤 - 除非用户另有说明，否则继续实施拟议的解决方案

不适用此技能的情况

• 对于简单明了且修复方案明确的 Bug
• 首次调试尝试仍在进行时
• 对于新功能（此技能用于调试现有代码）
• 问题显然由环境导致（配置、基础设施），无需检查代码