Auto-Finance/.agents/docs/standards/调试规范.md

last_reviewed

last_reviewed
2026-06-09

调试规范

调试前检查清单

在循环调试任务前，需完成以下检查：

1. 梳理代码链路（最长耗时 5 分钟）。从入口函数追踪至异常执行环节，排查硬编码值、参数缺失或分支逻辑异常等问题。
2. 对比正常与异常场景。若功能 A 运行正常、功能 B 出现故障，梳理二者代码链路的差异，问题通常就出在差异部分。
3. 排查基础配置项。检查代理设置、环境变量、端口号、功能开关等。多数故障由配置问题导致，而非代码逻辑错误。

调试过程要求

1. 两次尝试原则。若同一排查方式（重跑测试、调整参数等）连续失败两次，立即停止，更换排查思路：
   • 增加针对性日志或打印语句
   • 阅读异常依赖库的源码
   • 精简代码，复现最小故障案例
   • 反思：自身哪些预设判断可能存在偏差
2. 禁止无限循环调试。定时任务仅用于监控正常运行的进程，不可作为调试工具。若定时循环连续两轮无进展，关闭循环，转为人工调试。
3. 记录排查思路。每开始一次尝试前，做好记录：
   • 初步判断的问题原因
   • 用于验证猜想的依据
   • 本次准备执行的操作
   • 避免重复无效尝试与逻辑死循环

调试收尾工作

1. 编写经验文档。所有非简单故障的调试工作，均需在.agents/docs/error-experience/ 目录下新建记录文档，内容包含：
   • 故障现象
   • 历次排查操作及失败原因
   • 最终解决方案
   • 后续可借鉴的调试经验