系统性调试

概述

随机修复既浪费时间又会制造新问题。快速补丁会掩盖根本原因。

核心原则：尝试修复前必须找到根本原因。仅处理症状的修复意味着失败。

违反此流程的具体要求，即违背调试的根本精神。

铁律

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
NO INVESTIGATION WITHOUT CONTEXT RECALL FIRST

若未完成阶段0，则不能进入阶段1。 若未完成阶段1，则不能提出修复方案。

适用场景

适用于任何技术问题：

• 测试失败
• 生产环境故障
• 异常行为
• 性能问题
• 构建失败
• 集成问题

特别适用于以下情况：

• 时间紧迫时（紧急情况易诱发盲目尝试）
• 看似存在"显而易见的快速修复方案"时
• 已尝试多种修复方案仍未解决时
• 之前的修复没有奏效
• 你并未完全理解这个问题

在以下情况下不要跳过步骤：

• 问题看似简单（简单的错误也有其根本原因）
• 你很匆忙（仓促行事必然导致返工）
• 经理要求立刻修复（系统化处理比瞎忙乱试更快）

五个阶段

你必须完成每个阶段，才能进入下一阶段。

阶段 0：上下文回顾（强制性的第一步）

在进行任何其他操作之前：

1. 从错误信息中提取关键词

   • 错误类型是什么？（内存溢出、超时、连接错误、类型错误...）
   • 涉及哪个组件？（服务器、浏览器、API、数据库...）
   • 涉及代码库的哪个区域？

2. 搜索已有知识

   • 检查项目文档、MEMORY 文件或过去的对话记录
   • 在代码库中搜索类似的错误模式：grep -r "ErrorType" .
   • 检查 git 日志，查找近期相关的更改：git log --oneline -20

3. 审查结果

   • 找到相关经验？ ->直接应用，跳转到第 4 阶段
   • 找到部分匹配？ -> 用作第 1 阶段的起点
   • 没有找到？ -> 进入第 1 阶段，记得稍后记录解决方案

4. 输出格式

   Context Recall:
   - Query: "xxx"
   - Found: [description of related knowledge]
   - Action: [apply experience / continue investigation / no match]
   

违规：在没有上下文回忆输出的情况下进入第 1 阶段 = 流程失败。

第 1 阶段：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误信息

   • 不要跳过错误或警告
   • 它们通常包含确切的解决方案
   • 完整阅读堆栈跟踪
   • 注意行号、文件路径、错误代码

2. 一致地复现

   • 你能可靠地触发它吗？
   • 具体步骤是什么？
   • 每次都会发生吗？
   • 如果无法复现问题 -> 收集更多数据，不要猜测

3. 检查最近的变更

   • 哪些变化可能导致此问题？
   • Git diff，最近的提交
   • 新的依赖项、配置变更
   • 环境差异

4. 在多组件系统中收集证据

   当系统包含多个组件时（例如：CI -> 构建 -> 签名，API -> 服务 -> 数据库）：

   在提出修复方案前，先添加诊断工具：

   For EACH component boundary:
     - Log what data enters component
     - Log what data exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence showing WHERE it breaks
   THEN analyze evidence to identify failing component
   THEN investigate that specific component
   

5. 追踪数据流

   • 错误值源自何处？
   • 是谁传递了这个错误值？
   • 持续向上追溯直至定位源头
   • 在源头修复，而非在症状处

第二阶段：模式分析

修复前先寻找规律：

1. 寻找可运行示例

   • 在同一代码库中定位类似的可运行代码
   • 哪些正常运行的代码与故障代码相似？

2. 与参考案例进行对比

   • 如果实现模式，请完整阅读参考实现
   • 不要略读——逐行阅读
   • 在应用之前充分理解该模式

3. 识别差异

   • 正常和异常之间有何不同？
   • 列出每一个差异，无论多么微小
   • 不要假设“那不可能有影响”

4. 理解依赖关系

   • 此模式需要哪些其他组件？
   • 需要哪些设置、配置、环境？
   • 它做了哪些假设？

第三阶段：假设与测试

科学方法：

1. 提出单一假设

   • 清晰陈述：“我认为X是根本原因，因为Y”
   • 将其写下来
   • 要具体，不要模糊

2. 最小化测试

   • 做出尽可能小的更改来测试假设
   • 一次只改变一个变量
   • 不要一次性修复多个问题

3. 继续前请验证

   • 成功了吗？是 -> 阶段4
   • 没成功？提出新假设
   • 不要堆叠更多修复方案

4. 当你不确定时

   • 直接说"我不理解X"
   • 不要假装明白
   • 寻求帮助
   • 深入研究

阶段4：实施阶段

解决根本原因而非表象：

1. 创建失败测试用例

   • 最简单的可复现案例
   • 尽可能自动化测试
   • 若无框架则使用一次性测试脚本
   • 修复前必须完成

2. 实施单一修复方案

   • 解决已确认的根本原因
   • 每次只做一处修改
   • 禁止"顺带"优化
   • 禁止捆绑式重构

3. 验证修复效果

   • 测试现在通过了吗？
   • 没有破坏其他测试吗？
   • 问题确实解决了吗？

4. 如果修复无效

   • 停止
   • 计数：你尝试了多少次修复？
   • 如果 < 3：返回第一阶段，用新信息重新分析
   • 如果 >= 3：停止并质疑架构（见下面的步骤5）
   • 未经架构讨论，不要尝试第四次修复

5. 如果3次或更多修复失败：质疑架构

   表明存在架构问题的模式：

   • 每次修复都揭示出不同地方的新共享状态/耦合/问题
   • 修复需要“大规模重构”才能实施
   • 每次修复都会在其他地方引发新的症状

   停止并质疑基本原则：

   • 这个模式从根本上来说是合理的吗？
   • 我们是否“仅凭惯性坚持这个模式”？
   • 我们应该重构架构，还是继续修复症状？

   在尝试更多修复之前，与用户讨论。

危险信号 - 立即停止并遵循流程

如果你发现自己产生以下想法：

• "先快速修复，稍后再调查"
• "试试修改X，看看是否有效"
• "一次性做多处修改，然后运行测试"
• "跳过测试，我会手动验证"
• "问题可能出在X，让我修复它"
• "我不完全理解，但这方法可能有效"
• "模式表明是X，但我要用不同方式调整"
• "主要问题是：[未调查就直接列出修复方案]"
• 在追踪数据流之前就提出解决方案
• "再尝试一次修复"（当已尝试2次以上时）
• 每次修复都会在不同位置暴露新问题

所有以上情况都意味着：立即停止。返回第一阶段。

如果3次以上修复均失败：质疑系统架构（参见第4.5阶段）

常见合理化借口

快速参考

现实影响

根据调试会话数据：

• 系统化方法：15-30分钟修复
• 随机修复方法：2-3小时低效尝试
• 首次修复率：95% 对比 40%
• 引入新错误：接近零 对比 常见