SuperAPI AI 工具集

bugfix

编程与开发

查看项目

更新于 11-15 16:06

技能介绍

用途

bugfix 是一个用于处理缺陷与性能回归的诊断技能。所有 bug 都从这里开始,只有在明确说明理由时才可跳过阶段。其核心方法论是 Matt Pocock 的六阶段诊断循环(Phase 1–6),并加入 Phase 0(上下文加载)以及增强的 Phase 5、Phase 6。每次阶段切换都必须显式声明(如“进入 Phase N”“Phase N 完成”),不允许静默跳过。

主要能力

Phase 0 加载上下文:在改动代码前,读取 CONTEXT.md(领域术语与概念关系)、docs/specs/<area>.md(已知隐患与不变量,先检查该 bug 是否匹配既有隐患)、相关 docs/adr/(架构决策)以及 bug 上下文(Issue 全文、PRD + E2E 报告或对话上下文)。若 Issue 带有调试链(Debug Chain),则从上次状态继续,不重复测试已被排除的假设。

Phase 1 构建反馈闭环:这是该技能的关键。若能获得快速、确定、可由智能体运行的通过/失败信号,就能定位原因。构建方式按大致顺序尝试:在触达 bug 的接缝处写失败测试(单元、集成、e2e);针对运行中的开发服务器执行 curl / HTTP 脚本;用固定输入调用 CLI 并与已知良好快照对比 stdout;无头浏览器脚本(Playwright / Puppeteer)驱动 UI 并断言 DOM/console/network;回放捕获的 trace;搭建一次性最小化测试框架;属性/模糊循环;二分查找框架;差分循环;HITL bash 脚本(最后手段)。还应持续优化闭环本身:更快、信号更锐利、更确定。对非确定性 bug,目标不是干净复现,而是提高复现率。若确实无法构建闭环,应明确停止并说明尝试内容,向用户请求环境访问、捕获产物或临时生产插桩许可,不得在无闭环情况下进入假设阶段。

Phase 2 复现:运行闭环并观察 bug 出现,确认失败模式与用户描述一致、可重复(或非确定性 bug 的复现率足够高),并捕获精确症状供后续验证。

Phase 3 假设:在测试前生成 3–5 个排序假设,每个假设必须可证伪并给出预测。假设应解释“为什么”而非仅“是什么”,持续追问直到找到修复后能消除症状的根因。测试前向用户展示排序列表以便其领域知识快速调整。若对多模块、状态机或迁移类 bug 的修复方式不确定,可先用 /prototype 验证。

Phase 4 插桩:每个探针都映射到 Phase 3 的具体预测,一次只改一个变量。优先使用调试器/REPL,其次在区分假设的边界处定向打日志,禁止“全部打日志再 grep”。调试日志加唯一前缀(如 [DEBUG-a4f2])以便最后一次性清理。性能回归场景应建立基线度量(计时框架、performance.now()、profiler、查询计划)后再二分。

Phase 5 修复 + 回归测试:列出了修复反模式:在症状处修复(null 检查、try-catch、回退)、仅做加法修复、通过放宽校验来修复、通过复制逻辑来修复、无法解释因果链的修复。回归测试应在修复前编写,但仅当存在正确接缝时;不接受仅复述实现、mock 全部依赖的测试。若无正确接缝,这本身即为发现,需记录并在 Phase 6 标记。有正确接缝时:将最小化复现转为该接缝处的失败测试、观察其失败、应用修复、观察其通过,再对原始场景重跑 Phase 1 闭环。

Phase 6 清理 + 知识沉淀(不可跳过):清理清单包括原始复现不再复现、回归测试通过(或记录接缝缺失)、移除所有 [DEBUG-...] 插桩、在提交信息中写明正确假设。知识沉淀需回答三问:学到了哪些此前未知的领域知识(更新 CONTEXT.md);下一位在此写代码的人应知道哪些隐患(更新 docs/specs/<area>.md,格式为 [条件] → [不变量] + [违反后果]);什么架构变更能从根本上防止此类 bug(转交 /improve-codebase-architecture 或记录 none)。路径升级:设计缺陷转 /grill-with-docs → /to-prd;范围超出 Issue 则新建 Issue。退出路由:若由 E2E 失败进入,修复后重跑 /e2e-verify;若由 /functional-test 进入,返回并继续剩余测试。若发现方法论缺陷,直接告知用户,或在自主运行时追加到 bugfix/IMPROVEMENTS.md。

使用方式

以技能命令 /bugfix 调用,随后按 Phase 0 到 Phase 6 依次执行,并在每次阶段切换时显式声明。多会话交接协议与调试链格式见 multi-session.md,完整入口/出口点参考见 handoffs.md。

适用场景

适用于缺陷排查、性能回归诊断,尤其需要结构化、可复用、可交接根因分析的开发场景。

限制

该技能要求能够构建可运行的反馈闭环;若环境或产物不可获得,需停下并向用户请求支持,而非继续假设。文档未提供具体平台、收费或价格信息,暂未提供。