systematic-debugging

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

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

流程概览

为四个阶段分别创建任务，然后逐一完成；每个阶段完成后再开始下一个阶段，并将其标记为已完成。

按顺序完成以下四个阶段。不要跳过任何阶段，也不要在完成检查前尝试修复。

阶段 1：初步了解

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

• 说明问题：使用通俗易懂的语言，不要使用技术术语
• 说明预期行为：应该发生什么
• 说明实际行为：实际发生了什么
• 记录症状：错误消息、日志、可观察到的故障
• 背景：何时发生、发生频率、在什么条件下发生
• 之前的修复尝试：列出每次尝试、修改内容及失败原因；将其视为已排除的假设，阶段 3 必须对此作出解释

输出： 一份任何人都能理解的清晰问题陈述。

阶段 2：系统化检查

按照 Fagan 检查法中“阅读者”的角色，逐行检查代码。先找出缺陷，不要尝试修复——此阶段只进行检查。

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

1. 逻辑错误
2. 边界条件
3. 错误处理
4. 数据流问题
5. 集成点

在此阶段边分析边说明思路。对于每段代码：

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

输出： 按类别整理的缺陷清单，包含行号和具体说明。

阶段 3：根因分析

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

五个为什么法：

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

考虑因素：

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

明确说明假设：

• “我假设 X，因为……”
• “这预设了 Y 始终……”
• 标记任何需要验证的假设

输出： 清晰说明根因、推理过程以及需要验证的假设。

阶段 4：解决方案与验证

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

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

1. 说明修复内容：需要进行哪些代码或配置更改
2. 解释为何能解决根因：与阶段 3 的分析相联系
3. 考虑副作用：这项更改还可能影响什么
4. 定义验证步骤：如何确认修复有效

验证计划：

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

使用子 Agent 作为讨论对象，对拟议的解决方案和验证计划提出批判性反馈。

输出： 调查结果摘要（关键缺陷和根因）、按优先级排列并附有理由的拟议修复清单，以及用于确认修复有效的验证计划。

重要指南

• 彻底完成每个阶段后，再进入下一阶段
• 标记不明确之处，不要猜测——如果某些内容不确定，请说明
• 使用可用工具——读取文件、搜索代码、运行测试、检查日志
• 优先进行系统性分析，而不是快速修复
• 验证已标记的内容——完成所有阶段后，重新检查所有不明确之处；如有需要，使用 think 工具并选择“ultra”深度来澄清

最终输出

完成全部四个阶段后，除非用户另有说明，否则继续实施所提出的解决方案。

不应使用此技能的情况

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