系统化调试

铁律

未经根本原因调查，绝不修复。

仅修复表象会导致“打地鼠式”调试：每一次未触及根本原因的修复，都会让下一个 Bug 更难定位。务必先定位根本原因，再实施修复。

第一阶段：根本原因调查

在形成任何假设前，先全面收集上下文信息。

1. 收集表象现象：仔细阅读错误信息、堆栈跟踪（stack traces）及复现步骤。若用户未提供足够上下文，请每次仅提出 一个问题，切勿一次性追问五个问题。

2. 阅读代码：从表象现象出发，逆向追踪代码执行路径，直至潜在成因。搜索所有相关引用，通读故障点周边逻辑。

3. 检查近期变更：

   git log --oneline -20 -- 
   

   该功能此前是否正常？哪些内容发生了变更？若为回归问题（regression），则根本原因必然存在于 diff 中。

4. 尝试复现：能否以确定性方式触发该 Bug？若无法稳定复现，请先补充更多证据，再继续推进。

5. 检查内存记录：回顾此前在同一模块/文件中的调试会话。相同文件中反复出现 Bug 是一种架构异味（architectural smell）。

输出要求：“根本原因假设：……” —— 一项具体、可验证的陈述，明确指出问题所在及其成因。

第二阶段：模式分析

检查该 Bug 是否符合已知典型模式：

竞态条件（Race condition） …… 表现为偶发性、依赖时间顺序的问题。重点关注共享状态的并发访问。

空值传播（Nil/null propagation） …… 如 NoMethodError、TypeError。通常因对可选值缺乏防护逻辑所致。

状态损坏（State corruption） …… 数据不一致、更新不完整。需检查事务、回调（callbacks）、钩子（hooks）等机制。

集成失败（Integration failure） …… 如超时、响应异常。常见于外部 API 调用或服务边界交互。

配置漂移（Configuration drift） …… 本地运行正常，但在 staging/prod 环境失败。需排查环境变量、功能开关（feature flags）、数据库状态等。

缓存陈旧（Stale cache） …… 展示过期数据，清除缓存后即恢复正常。涉及 Redis、CDN、浏览器缓存等。

还需检查：

• 项目中是否存在与该问题相关的已知问题（Known issues）
• Git 日志中同一区域的历史修复记录。相同文件中反复出现 Bug 是架构层面的问题征兆，而非偶然现象。

外部搜索：若 Bug 不匹配任一已知模式，请在线搜索对应错误类型。前提：务必先脱敏—— 移除主机名、IP 地址、文件路径、SQL 片段、客户数据等敏感信息。应按错误类别（error category）而非原始错误消息进行搜索。

第三阶段：假设验证

在编写任何修复代码前，必须先验证你的假设。

1. 确认假设：在疑似根本原因位置添加临时日志、断言（assertion）或调试输出。运行复现流程，观察证据是否支持假设。

2. 若假设错误：对错误信息进行脱敏后重新搜索；返回第一阶段，进一步收集证据。严禁凭猜测推进。

3. 三击不中规则（3-strike rule）：若连续三个假设均被证伪，请立即暂停，并告知用户：

   “已验证三个假设，均未匹配。该问题可能属于架构层面缺陷，而非简单 Bug。”

   后续可选方案：

   • 基于新假设继续深入调查（请明确描述该假设）
   • 提报人工审查（需熟悉该系统的人员介入）
   • 增加日志埋点并等待下次触发（对该区域进行观测性增强，捕获下一次发生）

危险信号（Red flags） …… 若出现以下任一情况，请立即放慢节奏：

• “先来个快速修复”…… 不存在“暂时”的修复。要么彻底修复，要么及时升级处理。
• 尚未梳理清楚数据流就提出修复方案…… 你正在猜测，而非推理。
• 每次修复都引发其他位置的新问题…… 说明问题不在具体代码，而在所处抽象层级错误。

第四阶段：实现修复

待根本原因确认无误后：

1. 修复根本原因，而非表象。 采用最小必要变更，直接消除真实问题。

2. 保持 diff 最小化：修改最少的文件数、最少的代码行数。克制重构邻近代码的冲动。

3. 编写回归测试（regression test），确保其满足：

   • 不修复时测试失败（证明测试本身有意义）
   • 修复后测试通过（证明修复确实生效）

4. 运行完整测试套件。 不允许引入任何新的回归问题。

5. 若修复涉及超过 5 个文件：请在执行前向用户明确提示影响范围（blast radius）。对一个 Bug 修复而言，此规模过大。

第五阶段：验证与报告

全新验证：严格复现原始 Bug 场景，并确认其已被解决。此步骤不可跳过。

运行全部测试套件。

输出结构化调试报告：

DEBUG REPORT

• 表象现象（Symptom）：用户实际观察到的现象
• 根本原因（Root cause）：实际出错的本质所在
• 修复内容（Fix）：具体变更内容，并注明涉及的文件路径
• 证据（Evidence）：测试输出结果、复现验证截图或日志，证明修复有效
• 回归测试（Regression test）：新增测试用例所在位置
• 关联信息（Related）：同一区域的历史 Bug、架构层面注意事项
• 状态（Status）：DONE | DONE_WITH_CONCERNS | BLOCKED

将本报告保存至 memory/ 目录，文件名含今日日期，以便后续调试会话引用。

重要规则

• 连续三次以上修复尝试失败：立即暂停，并质疑系统架构。 此时问题大概率源于架构设计缺陷，而非假设错误。
• 绝不应用无法验证的修复。 若无法稳定复现并确认修复效果，则禁止上线。
• 禁止使用“这应该能修复它”类表述。 必须验证并实证有效——运行测试，展示结果。
• 若修复涉及超过 5 个文件：执行前须向用户明确提示影响范围。
• 完成状态定义：
  • DONE …… 已定位根本原因、已应用修复、已编写回归测试、全部测试通过
  • DONE_WITH_CONCERNS …… 已修复但无法完全验证（例如偶发 Bug、需 staging 环境验证）
  • BLOCKED …… 经充分调查仍无法明确根本原因，已升级处理