diagnosing-bugslisted

# Diagnosing Bugs — 6 阶段 Bug 诊断 硬 bug 的诊断纪律。只有明确理由才跳过阶段。 探索代码库时，读取 `CONTEXT.md`（如存在）获取相关模块的清晰心智模型，检查触及区域的 ADR。 ## 阶段 1 — 构建反馈循环 **这是所有技巧的核心。** 其他都是机械的。如果你有一个针对这个 bug 的**紧的**通过/失败信号——能在*这个* bug 上变红——你一定能找到原因；二分法、假设检验和检测手段都只是消费这个信号。如果你没有，盯着代码看也没用。 在这里花不成比例的精力。**要激进。要有创��力。拒绝放弃。** ### 构建途径（按顺序尝试） 1. **失败测试** — 在能到达 bug 的 seam 处 2. **Curl / HTTP 脚本** — 对着运行中的 dev server 3. **CLI 调用** — 用 fixture 输入，diff stdout 与已知正确快照 4. **无头浏览器脚本**（Playwright/Puppeteer）— 驱动 UI，断言在 DOM/console/network 上 5. **重放捕获的 trace** — 把真实网络请求/payload/事件日志存到磁盘，隔离回放 6. **一次性 harness** — 启动最小系统子集（一个服务，mock 依赖），通过一个函数调用测试 bug 代码路径 7. **Property/fuzz 循环** — 如果 bug 是"有时输出错误"，跑 1000 个随机输入找失败模式 8. **Bisection harness** — 如果 bug 在两个已知状态之间出现，自动化"启动状态 X，检查，重复" 9. **Differential 循环** — 相同输入跑旧版本 vs 新版本，diff 输出 10. **HITL bash 脚本** — 最后的手段 ### 收紧循环 把循环当产品对待。一旦你有了*一个*循环，**收紧**它： - 能更快吗？（缓存 setup，跳过无关初始化，缩小测试范围） - 能让信号更清晰吗？（断言特定症状，不是"没有崩溃"） - 能更确定性吗？（固定时间，种 RNG，隔离文件系统，冻结网络） ### 非确定性 bug 目标不是干净的复现而是**更高的复现率**。循环触发 100×，并行化，加压力，缩小时间窗口，注入 sleep。50% 概率的 flaky bug 是可调试的；1% 不是——不断提升直到可调试。 ### 完成标准 —— 一个紧的、能变红的循环 阶段 1 完成时，循环是**紧的**且**能变红**：你可以命名**一个命令**——脚本路径、测试调用、curl——你已经**至少运行过一次**（粘贴调用和输出），且满足： - [ ] **能变红** — 它驱动真正的 bug 代码路径并断言**用户的精确症状**，所以它能在有这个 bug 时变红，修复后变绿 - [ ] **紧** — 在 debug 模式下（额外的日志/检查关掉）少于 10 秒，最好在 3 以内 ## 阶段 2 — 理解系统 不要猜测。**检查。** 如果任何检查找到相关材料，停下来读。 ### 检查顺序 1. **`git log` on the file(s)** — 谁、什么时候、为什么改了这代码？Diff 对理解有帮助 2. **检查 `docs/adr/`** — 在这个区域有 ADR 吗？当前行为是故意的吗？ 3. **读取整个相关函数/模块** — 不是只看写死的行 4