메뉴
针对疑难 bug 和性能回归的诊断循环。当用户说"诊断"/"调试这个"，或报告有东西损坏/抛出异常/失败/变慢时使用。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
询问哪种技能或流程适合你的情况。本仓库技能的导航器。
沿两个轴线审查自某个固定点（commit、分支、tag 或合并基准）以来的变更 — 标准（代码是否遵循此仓库已记录的编码规范？）和规范（代码是否匹配原始 issue/PRD 要求的内容？）。以并行子 agent 运行两项审查，并将结果并排呈现。当用户想要审查分支、PR、进行中的变更，或要求"从 X 开始审查"时使用。
设计深层模块的共享词汇。当用户想要设计或改进模块接口、寻找深化机会、决定缝合点放在哪里、使代码更可测试或更适合 AI 导航，或当其他技能需要深层模块词汇时使用。
构建和精炼项目的领域模型。当用户想要确定领域术语或通用语言、记录架构决策，或当其他技能需要维护领域模型时使用。
一场无情的面试，用于打磨方案或设计。
一场无情的访谈，用于打磨计划或设计，同时在此过程中创建文档（ADR 和词汇表）。
| name | diagnosing-bugs |
| description | 针对疑难 bug 和性能回归的诊断循环。当用户说"诊断"/"调试这个"，或报告有东西损坏/抛出异常/失败/变慢时使用。 |
针对疑难 bug 的规程。仅在明确有理由时才跳过阶段。
探索代码仓时，阅读 CONTEXT.md（如果存在）以获取相关模块的清晰心智模型，并检查你接触区域的 ADR。
这就是核心技能。 其他一切都是机械性的。如果你针对 bug 有一个紧凑的通过/失败信号 — 一个在_此_ bug 上会变红的信号 — 你就会找到原因；二分查找、假设检验和插桩都只是消费它。如果你没有一个这样的信号，再盯着代码看也救不了你。
在此投入不成比例的精力。要激进。要有创意。拒绝放弃。
git bisect run。scripts/hitl-loop.template.sh 驱动_他们_，使循环仍然结构化。捕获的输出反馈给你。构建了正确的反馈回路，bug 就修复了 90%。
将回路视为产品。一旦你有了_一个_回路，收紧它：
一个 30 秒的抖动回路比没有回路好不了多少；一个 2 秒的确定性回路才是紧凑的 — 这是调试的超能力。
目标不是干净的复现，而是更高的复现率。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 抖动的 bug 是可调试的；1% 则不行 — 持续提高复现率直到可调试。
停下来，明确说明。列出你尝试过的方法。向用户请求：(a) 访问能复现的任何环境，(b) 一个捕获的产物（HAR 文件、日志转储、核心转储、带时间戳的屏幕录制），或 (c) 添加临时生产环境插桩的许可。不要在没有回路的情况下进入假设阶段。
阶段 1 完成的条件是回路紧凑且具备变红能力：你能说出一条命令 — 一个脚本路径、一个测试调用、一个 curl — 你已经至少运行过一次（粘贴调用及其输出），并且该命令满足：
scripts/hitl-loop.template.sh 时才能有人工参与。如果你发现自己在回路存在之前阅读代码来构建理论，停下来 — 直接跳到假设正是本技能要防止的确切失败模式。 没有变红能力的命令，就没有阶段 2。
运行回路。看着它变红 — bug 出现。
确认：
一旦变红，将复现场景缩小到仍能变红的最小场景。逐个削减输入、调用者、配置、数据和步骤，每次削减后重新运行回路 — 只保留对故障有负载作用的部分。
为什么费这个劲：最小复现场景缩小了阶段 3 的假设空间（值得怀疑的移动部件更少），并成为阶段 5 的干净回归测试。
完成条件是每个剩余元素都有负载作用 — 移除其中任何一个都会使回路变绿。
在复现且最小化之前不要继续。
在测试任何假设之前生成 3-5 个排名假设。单一假设生成会锚定在第一个看似合理的想法上。
每个假设必须是可证伪的：陈述它的预测。
格式："如果 是原因，那么 <改变 Y> 会使 bug 消失 / <改变 Z> 会使它更糟。"
如果你无法陈述预测，这个假设只是感觉 — 丢弃或精炼它。
在测试之前向用户展示排名列表。 他们通常拥有能立即重新排名的领域知识（"我们刚刚部署了对第 3 项的改动"），或知道他们已经排除的假设。低成本检查点，大幅节省时间。如果用户 AFK，不要等待 — 按你的排名继续。
每个探测必须映射到阶段 3 中的一个具体预测。每次只改变一个变量。
工具偏好：
用唯一前缀标记每条调试日志，例如 [DEBUG-a4f2]。最后的清理只需一次 grep。未标记的日志保留；已标记的日志删除。
性能分支。 对于性能回归，日志通常是错误的。替代方案：建立基线测量（计时夹具、performance.now()、分析器、查询计划），然后二分查找。先测量，后修复。
在修复之前编写回归测试 — 但仅当存在正确的缝合点时才这样做。
正确的缝合点是指测试能在调用点处驱动真实的 bug 模式。如果唯一可用的缝合点太浅（bug 需要多个调用者时却只有单调用者测试，单元测试无法复现触发 bug 的调用链），在那里的回归测试会给出虚假的信心。
如果不存在正确的缝合点，这本身就是发现。 记录下来。代码仓架构正在阻止锁定此 bug。将此标记给下一阶段。
如果存在正确的缝合点：
宣布完成前必须完成：
[DEBUG-...] 插桩已移除（grep 该前缀）然后问：什么本可以预防这个 bug？ 如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况移交给 /improve-codebase-architecture 技能。在修复之后提出建议，而非之前 — 你现在比开始时拥有更多信息。