debug

Vendored from mattpocock/skills · MIT © 2026 Matt Pocock · upstream 6eeb81b · 已汉化并完成 VoidTech 插件内自包含适配。LICENSE 见 ../_vendor-licenses/mattpocock-LICENSE

诊断缺陷

一套针对疑难缺陷的纪律。只有在有明确理由时才跳过某个阶段。

探查代码库时，读取 CONTEXT.md（若存在），先弄清相关模块、业务词汇和边界，再查看改动区域内的 ADR。

阶段 1 — 构建反馈循环

本阶段的目标是建立一个快速、稳定且针对当前缺陷的通过或失败信号。它必须在缺陷存在时失败，在缺陷修复后通过。二分定位、假设检验和诊断信息都依赖这个信号；没有可靠信号时，继续阅读代码很容易产生无法验证的猜测。

优先投入时间建立这个反馈循环。常规方法无效时，再尝试更小的测试环境、请求重放或差分对比。

构建它的若干途径——大致按此顺序尝试

1. 失败的测试，放在任何能触发该缺陷的可测试位置，例如单元测试、集成测试或端到端测试（e2e）。
2. Curl / HTTP 脚本，打向一个运行中的开发服务器。
3. CLI 调用，提供一份固定测试输入，把 stdout 与已知正确的快照对比。
4. 无头浏览器脚本（Playwright / Puppeteer）——驱动 UI，对 DOM/console/network 做断言。
5. 重放已捕获的轨迹。 把一个真实的网络请求 / 载荷 / 事件日志存到磁盘；隔离地让它重新走一遍代码路径。
6. 一次性测试环境。 启动系统的最小子集（例如只启动一个服务，并 mock 外部依赖），用单次函数调用覆盖缺陷路径。
7. 随机输入测试。 如果缺陷表现为“偶尔输出错误”，运行大量随机输入并记录失败样本。
8. 二分定位脚本。 如果缺陷出现在两个已知状态（commit、数据集、版本）之间，自动执行“在指定状态启动、检查、重复”，以便使用 git bisect run。
9. 版本对比测试。 用同一输入分别运行旧版与新版（或两套配置），然后比较输出。
10. HITL bash 脚本。 最后手段。如果必须有人点击，Claude Code 从 ${CLAUDE_PLUGIN_ROOT}/skills/debug/scripts/hitl-loop.template.sh 读取模板；OMP 从 skill://debug/scripts/hitl-loop.template.sh 读取同一模板。把内容复制到操作系统临时目录，在副本中填写步骤后运行；不要修改插件安装目录中的模板。捕获的输出回流给你。

正确的反馈循环会显著降低后续定位和验证的成本。

改进反馈循环

建立初始循环后，继续缩短运行时间并提高信号质量：

• 能更快吗？（缓存初始化、跳过无关的 init、收窄测试范围。）
• 能让信号更锐利吗？（断言具体症状，而不是"没崩"。）
• 能更确定吗？（固定时间、给 RNG 播种、隔离文件系统、冻结网络。）

一个耗时 30 秒且结果不稳定的循环难以使用；一个耗时 2 秒且结果确定的循环更适合反复验证。

偶发缺陷

目标不是干净的复现，而是更高的复现率。把触发器循环跑 100 次、并行化、加压、收窄时序窗口、注入 sleep。一个 50% 概率出错的缺陷可调试；1% 则不行——持续提高复现率，直到可调试为止。

当你确实无法构建循环时

停下并明确说明当前限制，列出已经尝试的方法。向用户索取：(a) 能复现问题的环境访问权限，(b) 已捕获的材料（HAR 文件、日志转储、core dump、带时间戳的屏幕录像），或 (c) 在生产环境增加临时诊断日志或指标的许可。没有反馈循环时，不进入假设阶段。

完成判据 — 反馈循环能够捕获缺陷

当反馈循环足够快速、稳定且能捕获当前缺陷时，阶段 1 完成。此时应给出一条已经至少运行过一次的命令，可以是脚本、测试调用或 curl，并附上调用方式及输出。它必须满足：

• 能够捕获缺陷 — 它覆盖真实的缺陷代码路径，并断言用户报告的确切症状；缺陷存在时失败，修复后通过。仅验证“运行不报错”不够。
• 确定 — 每次运行结论相同（不稳定缺陷：按上文，固定一个高复现率）。
• 快 — 以秒计，而非以分钟计。
• 可由 agent 运行 — 你能无人值守地跑它；只有通过插件随附的 HITL 模板副本才允许人介入循环。