systematic-debugging

系统化调试

核心原则： 修复前先找到根本原因。只修复症状注定会失败。

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

阶段 1：根本原因调查

在尝试任何修复之前：

1. 仔细阅读错误消息

   • 完整阅读堆栈跟踪
   • 记下行号、文件路径和错误代码
   • 不要跳过警告

2. 稳定复现

   • 确切的步骤是什么？
   • 如果无法复现 → 收集更多数据，不要猜测

3. 检查近期更改

   • Git 差异、近期提交
   • 新依赖项、配置更改
   • 环境差异

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

   当系统包含多个组件时（CI → 构建 → 签名、API → 服务 → 数据库）：

   提出修复方案前，先添加诊断检测：

   For EACH component boundary:
     - Log what data enters/exits component
     - Verify environment/config propagation
     - Check state at each layer
   
   Run once to gather evidence → analyze → identify failing component
   

   示例：

   # Layer 1: Workflow
   echo "=== Secrets available: ==="
   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
   
   # Layer 2: Build script
   env | grep IDENTITY || echo "IDENTITY not in environment"
   
   # Layer 3: Signing
   security find-identity -v
   

5. 追踪数据流

   有关向后追踪技术，请参阅 references/root-cause-tracing.md。

   简要来说：错误值从哪里产生？沿调用链向上追踪，直到找到源头。在源头修复。

阶段 2：模式分析

1. 查找可用示例 - 在代码库中查找类似的可用代码
2. 与参考实现进行比较 - 完整阅读参考实现，不要略读
3. 找出差异 - 列出所有差异，不要想当然地认为“这无关紧要”
4. 了解依赖项 - 组件、配置、环境、假设

阶段 3：假设与测试

1. 提出单一假设 - “我认为 X 是根本原因，因为 Y”——具体说明
2. 进行最小测试 - 尽可能小的更改，一次只改一个变量
3. 验证 - 修复有效？→ 阶段 4。无效？→ 提出新假设，不要叠加修复
4. 不知道时 - 直说。不要假装知道。

阶段 4：实施

1. 创建失败的测试用例

   • 使用 test-driven-development 技能
   • 修复前必须创建

2. 实施单一修复

   • 一次只做一项更改
   • 不要顺便进行改进

3. 验证修复

   • 测试通过了吗？其他测试仍然通过吗？问题解决了吗？

4. 修复无效时

   • 统计尝试次数
   • 如果 < 3：根据新信息返回阶段 1
   • 如果 ≥ 3：升级处理（见下文）

升级处理：3 次或更多修复失败

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

• 每次修复都会在其他地方暴露新问题
• 修复需要大规模重构
• 不断出现共享状态／耦合问题

处理方式： 停下。质疑基本假设：

• 这种模式在根本上是否合理？
• 我们是否只是惯性地继续？
• 应该重构架构，还是继续修复症状？

继续尝试修复前，先与人类伙伴讨论。 这是架构错误，而非假设失败。

警示信号 → 停下并返回阶段 1

如果你发现自己在想：

• “先快速修复，之后再调查”
• “先试试改 X”
• “我跳过测试吧”
• “大概是 X”
• “模式建议用 X，但我会用别的方式改写”
• 尚未追踪数据流就提出解决方案
• 失败 2 次或更多后还想“再修一次”

表明你偏离方向的人类信号

• “这不是没发生吗？” → 你未经验证就下了结论
• “这能让我们看到……吗？” → 你本该添加证据收集
• “别再猜了” → 你还没弄清楚情况就提出修复方案
• “深入思考” → 质疑基本假设
• 对方沮丧地问“我们卡住了吗？” → 你的方法不起作用

应对方式： 返回阶段 1。

辅助技术

references/ 中的参考文件：

• root-cause-tracing.md - 沿调用栈向后追踪缺陷
• defense-in-depth.md - 找到根本原因后，在多个层级添加验证
• condition-based-waiting.md - 用基于条件的轮询替代任意超时

相关技能：

• test-driven-development - 创建失败的测试用例（阶段 4）
• verification-before-completion - 宣称成功前验证修复