diagnose-loop 是一个纪律化的缺陷诊断循环技能,其核心主张是:第一阶段——构建一个快速、确定、二值信号的反馈循环——本身就是这项技能,其余阶段只是机械地消费第一阶段的产出。
用途与定位 该技能用于系统化地排查缺陷。它明确偏向彻底性而非速度。对于原因显而易见的琐碎缺陷(拼写错误、差一错误、堆栈跟踪已直接指出的缺失导入),建议跳过各阶段直接修复。对于其他所有情况——不稳定测试、性能回归、“在我机器上能跑”、间歇性故障,以及任何你已经盯着超过 15 分钟的问题——这种纪律正是重点所在。该技能改编自 mattpocock 的 diagnose 模式。
与 systematic-debugging 的区别 插件技能 superpowers:systematic-debugging 是适用于任何缺陷或意外行为的通用纪律,即“在动手修复之前先形成假设”。而 diagnose-loop 专门适用于收益在于先构建快速、确定、二值反馈循环的场景——不稳定测试、性能回归、难以复现或间歇性故障。对于只需纪律化假设的简单缺陷,superpowers:systematic-debugging 是更轻量的选择。
第一阶段——构建反馈循环(技能核心) 在此投入不成比例的精力。要激进,要创造性,拒绝放弃。后续每个阶段都机械地消费第一阶段的产出。快速确定的循环把假设变成二分查找;缓慢或嘈杂的循环则把假设变成猜测。构建循环就是工作本身,其余只是记账。一个好的循环有三个属性:几秒内运行完成、返回二值通过/失败信号、每次因相同原因失败。在做其他任何事情之前,先针对这些属性进行优化。
构建循环的十种排序方法(按成本从低到高,选择实际能复现缺陷的最便宜方法):
- 已有的失败测试——最便宜的信号,测试框架已存在。
- 捕获缺陷的新失败测试——写好断言,看它失败,然后开始。
- 可复现的 curl / HTTP 请求——用于 API 和 webhook 缺陷;捕获为 shell 脚本以便一行重放。
- CLI 命令 + 与已知良好输出的 diff——对任何输出文本的工具做黄金文件测试。
- 无头浏览器脚本(Playwright/Puppeteer)用于 UI 缺陷——可与 playwright 技能组合。
- 跟踪/日志重放——当缺陷只在生产环境出现时,转储请求并在本地重放。
- 用仓库语言编写的一次性测试脚本——一个 20 行文件,导入有缺陷的模块并直接调用。
- 基于属性/模糊测试——当缺陷依赖数据且尚不清楚哪个输入触发时。
- git bisect——当缺陷是近期引入且存在已知良好提交时;循环就是 bisect 脚本。
- 针对参考实现的差分测试——用于解析器、编译器或协议缺陷,其中“正确”在别处定义。
最后手段:人在回路 bash 测试框架——用户执行一步,智能体读取 stdout。参见 scripts/hitl-loop.template.sh。仅当以上方法都不可达时使用(例如缺陷需要物理硬件、付费第三方服务或手动 UI 步骤)。所有十种方法的具体代码片段位于 references/feedback-loop-recipes.md。
迭代循环本身 在使用循环进行调查之前,先让循环更快、更锐利、更确定。一个自动触发的 30 秒循环胜过你必须记得运行的 5 秒循环。通过缩小测试面、剥离无关设置、移除掩盖信号的日志噪声来锐化循环。
非确定性缺陷 如果缺陷复现率低于一半,你还没有循环,只有抛硬币。在做其他任何事情之前,先把复现率从约 1% 提高到约 50%。方法包括:收紧循环(更小的测试面、更少的依赖);并行运行(for i in {1..20}; do ...; done &)以暴露竞态;刻意对系统施压:限制 CPU、慢网络、受限内存、故意时钟偏移。
第二阶段——复现 运行循环并确认它显示的是用户的故障,而不是邻近的故障。逐字符对照报告的征兆阅读失败的断言或输出。两个看起来相似的缺陷仍然是两个缺陷。
第三阶段——假设 生成三到五个排序的可证伪假设。每个假设使用 references/hypothesis-format.md 中的格式:“如果 <X> 是原因,那么 <改变 Y> 将使缺陷消失。”在测试任何一个之前,先把列表展示给用户——用户往往能从智能体不具备的上下文中知道哪个最可能。
第四阶段——插桩 一次测试一个假设。每次循环迭代只改变一个变量。给每条调试日志、打印或断点打上唯一标记,如 [DEBUG-7f3a](任意短随机字符串均可),这样第六阶段的清理只需一次 grep -r '[DEBUG-7f3a]'。未标记的调试输出正是 console.log("here") 被发布到生产环境的原因。
第五阶段——修复与回归测试 在正确的接缝处编写回归测试——即缺陷可被观察到的最小范围。如果自然接缝不存在(测试必须触及私有实现细节才能观察到失败),请在 PR 中注明。缺失接缝是模块存在架构问题的信号;建议后续调用 architecture-rescue,而不是用脆弱的测试来掩盖。
第六阶段——清理与复盘 grep -r '[DEBUG-xxxx]' . ——每条标记行都被移除。再次运行第一阶段的原始循环。它必须在修复前提交上仍然失败,在修复后提交上通过。在 PR 消息中提交假设——真正的根因——而不只是“修复了缺陷”。未来调试回归的你将会感谢现在的你。如果缺失接缝阻碍了第五阶段,建议将 architecture-rescue 作为后续问题。
反模式 禁止:跳过第一阶段。如果你没有快速确定的循环,再怎么盯着代码也找不到缺陷。没有循环地阅读代码,就是多此一举的猜测。