debugging-strategies

调试策略

将调试变成一项有序的调查：复现、隔离、提出假设、测试，最后再修复。不要盲目尝试各种改动。

有关特定语言或工具的命令及高级模式，仅在需要时阅读 references/debugging-toolbox.md。

核心流程

1. 复现

确认：

• 具体步骤；
• 预期行为与实际行为；
• 发生频率：始终发生／偶尔发生／特定环境下发生；
• 最小可复现案例；
• 环境：提交、操作系统、运行时、依赖版本、配置。

如果无法复现，请先收集更多可观测性信息，再修改代码。

2. 隔离

缩小故障范围：

• 移除无关输入；
• 减少并发、缓存和外部服务；
• 对比最近一次已知正常状态与当前状态；
• 对代码、配置、数据或依赖变更进行二分排查。

3. 提出假设

列出 2-5 个可能原因。对于每个原因：

• 说明它为何能解释症状；
• 说明哪些证据可以证实它；
• 说明哪些证据可以证伪它；
• 找出成本最低的测试。

按可能性与测试成本的乘积排序，而不是按理论的有趣程度排序。

4. 一次测试一项

一次只更改或检测一个变量。保留日志和命令。没有确认原因的修复只是风险，不是结果。

5. 验证并防止回归

修复后：

• 重新运行最小复现；
• 重新运行相关测试；
• 可行时添加回归测试；
• 记录根本原因，以及该修复为何有效。

问题路由

• Python 性能瓶颈 → python-performance-optimization。
• 测试设计或 pytest 测试套件失败 → python-testing-patterns。
• 导致反复出现问题的代码结构问题 → python-design-patterns。
• 由 Claude 提供支持的代码中，提示词或模型行为相关问题 → prompting-claude-models。

输出

返回：

• 症状摘要；
• 复现状态；
• 缩小后的故障范围；
• 按优先级排序的假设；
• 明确的下一步诊断；
• 修复验证计划；
• 防止回归的措施。