Codex 如何诊断 Bug？mattpocock/skills 调试技能使用方法

一个接口昨天还正常，今天突然返回空数组；你让 Codex “帮我看看”，它可能先翻代码、猜缓存、改条件，最后把真正的错误绕过去。诊断 Bug 最怕的不是不会修，而是还没抓到稳定症状就开始修。mattpocock/skills 里的 `/diagnosing-bugs`，解决的正是这个顺序问题。

先让 Bug 有一个红灯

`/diagnosing-bugs` 的第一阶段不是看代码，而是建立反馈环。它要求先找到一个会因为这个 Bug 变红、修好后变绿的命令，可以是失败测试、curl 请求、CLI 输入、Playwright 脚本、日志回放，甚至是一个临时 harness。

这一步能阻止 Codex 凭感觉改代码，不能保证第一次就抓到最小复现。失败场景是只让测试“能跑完”，却没有断言用户看到的具体错误；这样即使测试全绿，线上问题仍可能还在。

把复现压到最小

有了红灯之后，再让 Codex 复现并缩小范围。输入、配置、调用链、数据样本都可以一项项删，删完继续跑同一个反馈环。留下来的每个条件都应该是“拿掉它 Bug 就消失”的必要条件。

最小复现的好处，是让后面的假设少很多噪声。它能帮你看清是哪条路径坏了，不能替你识别所有业务例外。失败场景是复现里还夹着无关初始化，Codex 可能顺着噪声去修一个旁支问题。

假设要能被证伪

进入假设阶段时，不要只让 Codex 给一个“最可能原因”。`/diagnosing-bugs` 要求列出 3-5 个排序后的假设，并给出预测：如果原因是它，改哪一个变量会让 Bug 消失，或者让症状变得更明显。

这个要求很朴素，但对 AI 很有用。它能减少“看见一个可疑文件就动手”的冲动，不能替代项目成员的领域经验。失败场景是预测写成“可能和缓存有关”这种空话，后面的验证就没有抓手。

插桩只验证一个判断

插日志也要克制。技能建议优先用调试器或 REPL，其次才是边界位置的定向日志，而且每个探针只对应一个假设。调试日志最好带唯一前缀，修完后可以一次性清掉。

如果是性能回退，思路还要变：先建立基线，再用 profiler、查询计划或二分定位，不要靠满屏日志猜慢在哪里。失败场景是到处加 log，Codex 得到更多文本，却没有得到更清楚的信号。

修复必须回到原始场景

真正修复前，要把最小复现转成回归测试；如果找不到合适测试缝隙，也要记录这是架构问题，而不是硬塞一个浅层测试。修完后不仅看新测试通过，还要重跑最开始的反馈环，确认原始 Bug 不再出现。

所以，Codex 诊断 Bug 的关键提示可以很短：用 `/diagnosing-bugs`，先给我一个会变红的复现命令，再最小化、列假设、定向插桩，最后用回归测试锁住。能跑通这条链路，修错方向的概率会低很多。