用途
bug 是一个面向软件缺陷处理的结构化工作流技能,目标是把“调查、复现并修复一个缺陷”的过程标准化。它适用于开发者或智能体在某一代码库中定位并解决缺陷,尤其强调不能靠改症状了事,而要先找到真正的根因。
核心原则(Iron Laws)
- 先复现再调查:无法稳定触发的缺陷,就无法确认是否真正修好。
- 先找根因再写修复:只修症状视为失败;如果三次修复尝试都失败,说明尚未找到真正原因。
- 先写会失败的测试再修复:该测试用于证明诊断正确并防止回归。
- 一次只验证一个假设:用尽可能小的改动验证最可能的原因,不同时更改多个变量。
- 用原始复现路径验证,而不仅是单元测试:必须确认用户可见的症状确实消失。
主要阶段
第一阶段:捕获(Capture)
收集理解与复现问题所需的信息:观察到的行为、预期行为、精确的复现步骤(编号且具体)、环境(操作系统、版本、浏览器、部署层级 dev/staging/prod)、错误信息或堆栈或日志(原文而非转述)、问题开始时间、是否稳定复现、影响范围以及是否有临时绕行方案。若信息缺失,应先询问再继续。此外,用 git log --oneline -15 和 git diff HEAD~5 -- <相关文件> 检查近期改动;如果是“以前能用”的回归问题,直接进入回归检测。
第二阶段:复现(Reproduce)
在分析之前先建立可靠复现。复现阶梯(从上到下尝试):失败的单元测试(最快、最易调试)、可触发错误的独立脚本、curl / API 调用序列、手动 UI 步骤、循环 50 次以捕获间歇性失败。需要记录精确的复现命令或步骤。若无法稳定复现,不应继续修复,而应先调查非确定性。对间歇性缺陷,可循环 50 次查找频率,并排查共享可变状态、异步顺序问题、竞态条件、时序依赖、测试顺序污染。
第三阶段:根因调查(Root Cause Investigation)
- 形成假设:生成 3–5 个按可能性排序的假设,每个包含具体且可证伪的命题、支持证据与反驳证据。
- 插桩观察:在相关代码边界添加带假设标签的日志,所有输出写入文件,例如 <run-command> > /tmp/bug-debug.log 2>&1,再用 grep '[BUG-H1]' /tmp/bug-debug.log 过滤;日志需带假设标签。
- 反向追溯源头:从症状出发逐层追问“是什么导致了这个?”,直到找到最初触发点。
- 确认根因:在写修复前,用一句话陈述根因、证明证据、以及为何排除其他假设。如果已测试并排除 3 个以上假设,应停下来重新审视对系统的理解。
第四阶段:先写失败测试
在改生产代码前,先写一个能复现该缺陷、在当前代码下失败、且只有根因修复后才会通过的测试。可用 <test-command> -- <test-name> 确认修复前为 FAIL,并可单独提交该失败测试。
第五阶段:修复
先用 git restore . 清理插桩,然后在根因处实现最小修复;不修复用户未提及的问题,不重构周边代码。若修复很复杂,往往意味着还没找到真正根因。
第六阶段:验证
检查清单包括:失败测试现已通过;原始复现步骤不再触发缺陷;完整测试套件通过且无回归;对间歇性缺陷循环 50 次确认不再出现。在所有项目均以实际命令输出确认之前,不要声称缺陷已修复。
第七阶段:提交 GitHub Issue(可选)
若用户希望提交 GitHub Issue,可使用 gh issue create,并提供标题、描述、复现步骤、预期行为、实际行为、环境、根因、严重程度等字段,标签为 bug。正文模板包含 Description、Reproduction Steps、Expected Behavior、Actual Behavior、Environment、Root Cause、Severity(Critical/High/Medium/Low 多选)。
回归检测
针对“以前能用”的缺陷,可用 git bisect start、git bisect bad HEAD、git bisect good <last-known-good-sha>,再以 git bisect run <repro-command> 自动定位引入缺陷的提交,最后 git bisect reset。找到后应阅读该提交的 diff 与提交信息,判断是否是意外的“修复”或“重构”导致,并用 git log -S "<removed-code-pattern>" 检查相同模式是否存在于别处。
严重等级与提交信息
严重等级分为 Critical(数据丢失、安全漏洞、全部用户服务中断;立即修复并考虑生产事故流程)、High(核心功能损坏且无绕行方案;当前周期修复)、Medium(功能降级但有绕行方案;下个周期修复)、Low(边缘情况、外观问题、罕见发生;进入待办)。提交信息模板为 fix(<scope>): <简明描述>,并包含 Root cause、Reproduction、Fix 以及 Fixes #<issue-number> 字段。
限制
资料未说明该技能适配的具体平台、编程语言、依赖版本、收费情况或性能指标。其流程依赖可执行命令、git 仓库以及可运行测试的环境;若无法稳定复现间歇性缺陷,按流程应暂停修复并优先调查非确定性。