代码调试

代码调试

本技能是流程指引，不是逐条打勾清单：按场景判断使用，遇不适用情况保持裁量，不机械执行。

总原则

先确认"谁在执行"，再优化"怎么执行"。 报错位置常常是受害者，不是凶手。

强制流程（跳步视为流程违规）

写失败测试（规则 0）
  → 收集数据（规则 8）
  → 分析根因（规则 7 / 9 / 12）
  → 写回归测试并验证（规则 11）
  → 修改代码

本技能遵循《编程领域规则》中的行为测试规范（§6.3 行为测试原则、§6.4 时序测试铁律）。

---

执行流程

第 1 步：确认需要（调试前必做）

进入调试前，先确认故障信息和复现条件就位，缺则停下追问，不靠猜测推进。

1. 确认故障现象：报的什么错、什么场景下出现、预期行为 vs 实际行为
2. 确认复现条件：最小复现路径、触发输入、运行环境；无法复现的 bug 先和上报方确认复现步骤
3. 确认需求维度：这个 bug 是"功能没实现/行为不符合预期"还是"报错崩溃"。前者是需求符合性问题——核对实际行为偏离了哪个 AC、设计本意应该是什么，不能只盯着报错；后者才是纯技术故障
4. 确认涉及范围：故障在哪个模块、调用链上下游、可能受影响的依赖
5. 确认已有线索：错误日志、stack trace、已知的可疑点、之前是否修过该模块
6. 信息不全则停下：通过 human_interaction 向上追问，确认齐了再进入第 2 步

第 2 步：摸清现有实现（防重复修复、防破坏架构，调试前必做）

调研故障模块现有实现，需要得出以下结论：

• 调用链摘要：故障模块的调用链上下游、数据流、依赖方向
• 可复用项：现有代码里有没有已经正确处理该场景的函数/分支
• 接口契约：本模块对外接口的签名、入参出参、异常、调用约束
• 架构边界：本模块职责边界、依赖方向，修复会不会跨过模块边界乱改、破坏对外接口契约

第 3 步：复现与定位（最多 2 轮，只加诊断标记，禁止改代码）

按 coding_domain_rules.md §1.5 Bug修复安全执行。

1. 先写失败测试（见规则 0）：必须先写一个能复现该 bug 的行为测试，确认它失败。已有测试能复现则跳过这步。
2. 最小输入复现：用最小的输入触发失败
3. 收集数据（见规则 8）：按数据收集清单采集事实，不靠直觉
4. 确认 WHO 不只是 WHAT（见规则 1）：确认"是哪个对象/实例在执行"，而不只是"报了什么错"

第 4 步：追踪根因（最多 2 轮，只加诊断标记，禁止改代码）

1. 逐层追问根因（见规则 7）：用 5 Whys 追到可操作根因
2. 管理假设（见规则 9）：同时跟踪不超过 3 个假设，各列正反证据
3. 在构造函数加 traceback（limit=4）
4. 确认对象被创建了几次、由谁创建
5. 检查 fork/clone/rebuild 是否丢失依赖
6. 检查对象生命周期：bug 通常在对象被重建时丢失属性，不在报错代码本身

第 5 步：修复根因

1. 修复真正的根因（不是症状）
2. 在完整系统中验证（不是只跑隔离测试——见规则 2）
3. 移除所有临时诊断代码（print/traceback 标记）

第 6 步：回归验证

1. 写回归测试（见规则 11）：必须是行为测试，验证根因被修复而非症状消失
2. 重新运行全部测试（包括之前通过的）
3. 复验失败测试：原来复现 bug 的测试现在应通过
4. 如果仍有失败 → 回到第 3 步（同方向最多 3 次，超过则切换假设）

---

调试原则（含使用条件与示例）

规则 0：用测试捕获理想行为（前置硬门槛）

使用条件：发现 bug 的第一时间——任何分析代码、读日志、改逻辑之前。

怎么使用：

• 第一动作是写出能暴露 bug 的行为测试（红灯），而不是分析代码。该测试即理想模型的可执行形式——精确描述"在给定输入下，正确的可观察行为应该是什么"。
• 优先于所有分析动作。先有失败测试，再谈诊断。
• 测试必须断言可观察行为（输入 → 输出 / 副作用），而非内部实现细节，遵循《编程领域规则》§6.3。
• 如果无法写出测试（缺乏可观测性），不要绕过这一步——先重构增加可观测性（暴露事件、时间戳、状态查询接口），再写测试。

小例子：

通知推送时序错了，先不读代码。直接写一个测试断言"通知推送时间戳 ≤ LLM 收到请求时间戳"，跑一次，红灯——这就是 bug 的可执行形式。