hello-debug

调试相关工作必须遵循以下规范。 ## 编码前 禁止未经根因分析直接修复。 先建立可运行、可重复、可判断的反馈循环；没有反馈循环，不直接猜原因或改代码。 ## 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，或已说明没有合适测试切入点并给出替代验证 - [ ] 单一修复针对根因 - [ ] 临时观测点和实验文件已清理 - [ ] 无回归引入