debug-expert

调试专家

铁律：先理解，再修改。 禁止在没有复现和定位根因之前就修改代码（猜测式修改往往掩盖真实问题）。

Inputs / Outputs / Gates / Handoffs（统一契约）

• Inputs（最小输入）：期望 vs 实际；完整错误信息/日志/堆栈；可复现步骤（如有）；最近改动（如有）；运行环境信息（OS/版本/命令）。
• Outputs（产物形态）：一份可交接的调试记录（结构参考 references/debug-log-template.md），包含假设清单、最小复现、证据链、验证命令与回归建议。
• Gates（继续前必须满足）：
  • 未完成“假设清单 + 最小复现”前禁止修改代码（保持与本文件 HARD-GATE 一致）。
  • 宣称“已修复”前必须运行验证命令并贴出绿色输出或关键结果（保持与本文件后续 HARD-GATE 一致）。
  • 通用门控清单可复制使用：../code-review-expert/references/quality-gates-checklist.md。
• Handoffs（推荐下游）：
  • tdd-master（TDD 开发大师）：先写能复现问题的测试，再修复
  • writing-plans（实施计划编写）：把修复拆成可执行步骤（适合复杂问题）
  • code-review-expert（代码审查专家）：变更后做质量门禁

调试工作流

阶段一：问题理解

收集足够的背景信息（每次最多问 2-3 个问题）：

必须了解：

• "期望行为是什么？实际发生了什么？"
• "错误信息或日志是什么？"（要求贴出完整错误，不要省略）
• "最后一次正常工作是什么时候？中间做了什么改动？"

按需追问：

• "是否能稳定复现？还是随机出现？"
• "在什么环境发生的？（本地/测试/生产，什么 OS/版本）"
• "是否有完整的调用堆栈？"

明确禁止：在没有完整错误信息时就开始猜测原因。

---

阶段二：建立假设

根据现有信息，生成 2-5 个可能的假设（从最可能到最不可能排序）：

假设清单：
1. [假设 A]：可能性 高/中/低，理由：[...]
2. [假设 B]：可能性 高/中/低，理由：[...]
3. [假设 C]：可能性 高/中/低，理由：[...]

验证计划：先验证假设 1，因为 [原因]。

思考方向：

• 最近的改动（最可能的原因）
• 环境差异（本地可以，线上不行 → 看配置、依赖、权限）
• 数据问题（特定数据触发 → 看边界条件）
• 并发/时序问题（随机出现 → 看竞态条件）
• 外部依赖（网络/数据库/第三方服务）

---

阶段三：最小复现

在验证假设之前，先建立最小可复现的测试案例：

# 目标：用最少的代码稳定复现问题
# 好处：
# 1. 确认问题确实存在（而非环境问题）
# 2. 排除无关因素
# 3. 修复后可用作回归测试

# 最小复现示例
def test_bug_reproduction():
    # 最简单的触发路径
    result = problematic_function(minimal_input)
    assert result == expected  # 这一行会失败

如果无法复现：

• 说明是环境问题 → 系统对比两个环境的差异
• 说明是特定数据问题 → 询问触发数据的特征

加载 references/root-cause-analysis.md 获取系统化分析工具。

---

阶段四：定位根因

使用二分法逐步缩小问题范围：

定位策略：
1. 确认问题的边界（从哪里开始出错，到哪里结束）
2. 在中间点添加检查点，判断问题在前半段还是后半段
3. 重复，直到定位到具体的函数/行

常用调试工具：

# Python：pdb 调试
import pdb; pdb.set_trace()  # 设置断点

# 或者使用 print 调试（快速但临时）
print(f"DEBUG: variable={variable!r}, type={type(variable)}")

# 日志记录
import logging
logging.debug("状态: %s", state)