debug-methodology

name	debug-methodology
description	Agent 调试方法论和硬性规则。Use when: 修改代码前查规范、代码改动2次还不行、排查硬件/配置/软件问题、不确定修改影响范围、新增文件或变量。含四步调试法（STOP→THINK→VERIFY→FIX）、反例速查、项目特有硬性规则。

Agent 调试范式 — 改代码前必过

一条铁律

改代码 2 次还不行 → 停止，查硬件。

四步法

1. STOP — 先读全局（5 分钟）

• 读 AGENTS.md、README.md 了解项目
• 搜索已有基础设施（调试函数、波形发送、测试计数器）
• 找到数据流：传感器→处理→输出

2. THINK — 列所有可能原因

按优先级：硬件(接线/供电) > 配置(时钟/中断) > 软件(逻辑) > 环境(编码/编译)

• 外设完全没反应 → 优先怀疑硬件
• 数值异常但有规律 → 优先怀疑软件
• 改了多次无效 → 必是硬件/配置问题

3. VERIFY — 逐个排除

• 不要猜，要验证：加测试计数器、让用户量电压、单独测模块
• 主动质疑用户："你说接线对，但现象指向硬件，请确认 XX 引脚"
• 分模块独立验证，不要混在一起调

4. FIX — 一步到位

• 想清楚所有影响范围
• 一次性改完所有相关文件
• 改完立即让用户编译验证

硬性规则

• ❌ GB2312 文件（含中文注释/字模）→ 禁用手动编辑，用脚本转 hex
• ❌ printf 和 datavision_send 不能同时开 → 共用 UART1，选一个
• ❌ 不要小修小补反复改 → 想清楚一步到位
• ✅ 新增变量 → .h 加 extern + headfile.h 加 include
• ✅ 问题确认解决后 → 更新 AGENTS.md 和 README.md（引脚变更、新模块、新规则、已知坑）

反例速查

错误做法	正确做法
见现象就改代码	先诊断根因
用户说接线对就信	追问具体引脚、建议量电压
GB2312 文件反复打开编辑	识别编码→一次性脚本转换
编码器方向改 5 次	第 3 次就该让用户查接线
没注意到 datavision_send	先搜索项目已有基础设施