SuperAPI AI 工具集

diagnosing-bugs

编程与开发

查看项目

更新于 10-16 08:56

技能介绍

Diagnosing Bugs 是一个用于诊断疑难缺陷(hard bugs)和性能回归(performance regressions)的诊断循环技能。当用户说“diagnose/debug”,或报告程序损坏、失败、变慢等行为时使用。

使用原则:只有在明确说明理由时才可跳过阶段。应阅读 CONTEXT.md 和本地 ADR 以了解模块上下文。

阶段 0 — 代码图谱查询(可选,若可用) 如果存在 graphify-out/graph.json,先简要告诉用户“查询代码图谱了解影响范围”,然后在开始诊断前查询代码图谱:

  • /code-graph query impact <suspected-file> — 查找受疑似代码区域影响的所有模块
  • /code-graph query deps <suspected-module> — 了解疑似模块依赖什么
  • /code-graph query hotspot — 检查缺陷区域是否也是已知热点(高耦合 + 频繁变更) 用这些结果缩小阶段 3 的假设空间。如果没有图谱,静默跳过。

阶段 1 — 构建紧凑反馈回路 这是本技能的核心。一个针对该缺陷会变红的紧凑通过/失败信号,胜过盯着代码看。 按顺序尝试:失败测试 → curl/脚本 → CLI fixture → 无头浏览器 → 重放 trace → 一次性 harness → fuzz → bisect harness → 新旧差分 → HITL 脚本。 然后收紧:更快、断言更锐利、更确定。 非确定性缺陷:提高复现率直到可调试。如果无法建立回路,停止——列出尝试过的方法,请求环境访问或捕获的产物。没有能变红的命令,就没有阶段 2。 完成条件:一个可由 agent 运行的命令,能变红、确定、快速,并且已经运行过一次(粘贴调用与输出)。

阶段 2 — 复现 + 最小化 回路在用户症状上变红。一次一刀地缩小复现——每个剩余部分都必须是承重的。

阶段 3 — 提出假设 在测试前提出 3–5 个排序的、可证伪的假设。尽可能向用户展示列表。

阶段 4 — 插桩 一次一个变量。调试器 > 定向日志。用 [DEBUG-xxxx] 标记日志以便清理。性能问题:先测量基线,再二分。

阶段 5 — 修复 + 回归测试 仅在正确的接缝处(调用点存在真实缺陷模式)才在修复前写回归测试。没有接缝 → 记录为架构发现。

阶段 6 — 清理 移除调试标记,删除一次性 harness,重新运行阶段 1 回路,在提交信息中说明胜出的假设。

修复后:如果预防需要架构变更(没有测试接缝、耦合纠缠),在修复之后,结合具体情况推荐 /aiops 与 Architecture health。