---
last_reviewed: 2026-06-09
---
# 调试规范

## 调试前检查清单

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

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

## 调试过程要求

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

## 调试收尾工作

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