hello-debug

name	hello-debug
description	调试错误、修复 bug、排查失败测试、处理异常行为，或代码行为与预期不符时使用。

调试相关工作必须遵循以下规范。

编码前

禁止未经根因分析直接修复。 先建立可运行、可重复、可判断的反馈循环；没有反馈循环，不直接猜原因或改代码。

Git 作为记忆

每次调试前，先读取相关的 git 历史：

• git log --oneline -20 查看最近变更
• git log --all --grep="revert" 查看过去的失败回滚
• 如果发现之前已经尝试并回滚过类似修复 → 不要重复同样的方向

反馈循环优先

反馈循环是调试入口，必须能证明“问题出现 / 问题消失”：

• 优先写失败测试；不适合写测试时，用 HTTP 脚本、CLI 样例输入、浏览器脚本、请求 / 事件回放、最小验证脚本、差异对比或压力循环复现
• 循环要尽量快、稳定、断言具体症状，不用“没有崩溃”代替正确性
• 非确定性问题先提高复现率，记录触发次数、失败比例和关键条件
• 实在无法建立循环时，停止并说明已尝试方式，向用户请求日志、录屏、请求记录、环境访问或授权加临时观测点

四阶段调试法

1. 定位

• 完整读取错误信息（不截断、不猜测）
• 用反馈循环稳定复现问题（确定触发条件）
• 反向追踪数据流（从错误点向上游追溯）

2. 分析

• 找到类似的正常工作代码，对比差异
• 检查最近的变更（git log/diff）
• 识别所有隐含假设

3. 假设

• 形成 3-5 个按可能性排序的假设
• 每个假设必须可证伪：写清“如果原因是 X，那么改变或观测 Y 会出现 Z”
• 单变量测试（一次只改一个东西）
• 记录每次尝试和结果

4. 修复

• 先写失败测试复现 bug
• 实现最小修复（针对根因，不是症状）
• 验证修复有效且无回归

临时观测点

• 临时日志必须带唯一前缀，如 [DEBUG-a4f2]
• 禁止“到处打印再搜索”；每个观测点都要对应一个假设
• 收尾前搜索前缀，删除所有临时日志、临时验证脚本和实验文件；确需保留时移动到明确的 debug 目录并说明原因

卡住升级机制

连续修复失败时，按以下阶梯升级策略：

第 1-2 次失败：正常反思，调整修复方向 第 3 次失败：停止。3 次失败意味着可能是架构问题而非局部 bug。重新从根因分析开始，质疑当前方向是否正确 第 4 次失败：扩大范围——重读所有相关文件，审查 git 历史中的相关变更，检查是否有隐藏的依赖或副作用 第 5 次失败：必须与用户讨论。提出以下选项：

1. 组合之前接近成功的尝试
2. 尝试完全相反的方向
3. 重构架构而非继续局部修补
4. 重新定义问题

超过 5 次：停止自主尝试，转为用户决策。

交付检查

• 根因已识别并记录
• 已建立能证明问题出现 / 消失的反馈循环
• 有失败测试复现 bug，或已说明没有合适测试切入点并给出替代验证
• 单一修复针对根因
• 临时观测点和实验文件已清理
• 无回归引入