From dev-toolkits
Guides structured bug fixing: code location, root cause analysis, reproduction tests, minimal fix, and regression testing. Activates on error reports, exceptions, or crash symptoms.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-toolkits:bug_fixThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Bug修复是**线性单线任务**:快速定位 → 精准复现 → 最小修改 → 充分验证。流程从 ez-dev 抽取核心约束(Worktree / 文档 / 修复闭环 / 测试分级 / 合并规范),砍掉并行策略与重型 Review,保持轻量。
Bug修复是线性单线任务:快速定位 → 精准复现 → 最小修改 → 充分验证。流程从 ez-dev 抽取核心约束(Worktree / 文档 / 修复闭环 / 测试分级 / 合并规范),砍掉并行策略与重型 Review,保持轻量。
.dev_doc/<bug>/status.md(阶段状态锚点 + 进度 checkbox)bug-analysis.md(根因 + 修复策略 + 风险)test-report.md(P0/P1/P2 测试点 + 0 failures 证据)summary.md(变更摘要 + worktree 路径 + 合并命令预览)致命问题(必须回退上 Phase 重做):
非致命问题(记录继续,不阻塞):
闭环流程: 失败 → 自纠 → 1 次机会 → 仍失败暂停并向用户报告(当前失败点、已尝试方案、需人工输入)。
CLAUDE.md 的"测试"章节| 文档 | 时机 | 必填字段 |
|---|---|---|
status.md | Phase 1 启动 | 当前阶段 / Bug 信息 / 测试清单 / 进度 checkbox |
bug-analysis.md | Phase 1 结束 | 概述 / 根因 / 触发条件 / 修复策略 / 风险 |
test-report.md | Phase 4 结束 | P0/P1/P2 测试点 / 覆盖率 / 0 failures 证据 |
summary.md | Phase 5 结束 | 变更摘要 / worktree 路径 / 合并命令预览 |
tests/<module>/test_<bug>_reproduce.py —— 1:1 对应用户报错,必须先 fail 后 passtests/<module>/test_<bug>_edge_cases.py —— 根因代码路径的边界值tests/<module>/test_<bug>_regression.py —— 相邻场景的回归保护WORKTREE_BASE_DIR:默认 .worktrees,启动 Phase 3 时从以下顺序推断:
CLAUDE.md 中显式声明.worktreeconfig(如存在).worktreesDEFAULT_BRANCH:从 git symbolic-ref refs/remotes/origin/HEAD 推断当前主线,缺失则用 git rev-parse --abbrev-ref HEADPhase 1 结束后、进入 Phase 2 前,AI 用以下 checklist 自审 bug-analysis.md:
# 修复策略自审清单
## 根因审查
- [ ] 根因是否找到了真正的代码问题,而不是表象?
- [ ] 调用链追踪是否完整?
## 修复策略审查
- [ ] 修复策略是否针对根因,而不是绕过症状?
- [ ] 是否识别了对其他模块的影响?
- [ ] 边界条件(空值/极值/异常)是否考虑?
- [ ] 是否存在更简单的修复方案?
## 风险审查
- [ ] 是否存在破坏性变更?
- [ ] 向后兼容性是否考虑?
- [ ] 修复后是否会引入新的 bug?
## 结论
- [ ] 通过(进入 Phase 2)
- [ ] 不通过(修订 bug-analysis.md 后重审)
不通过则修订 bug-analysis.md 后再审;通过则继续。
目标: 找到问题代码位置 + 完成根因分析 + 修复策略
步骤:
收集信息(用户已提供)
定位问题代码
根因分析 + 修复策略
修复策略自审(见上 checklist)
配置自动推断(打印 worktree 基目录 + 基准分支)
输出:
.dev_doc/<bug>/status.md(启动 + 更新阶段为"代码定位完成").dev_doc/<bug>/bug-analysis.md(根因 + 修复策略 + 风险)阶段声明:
🔍 Phase 1: 代码定位
正在定位问题代码 + 分析根因 + 制定修复策略...
完成标准: 根因清晰、修复策略明确、修复策略自审通过
目标: 创建测试用例稳定复现 Bug
步骤:
创建 P0 复现测试
tests/<module>/test_<bug>_reproduce.py 创建创建 P1 边界测试
tests/<module>/test_<bug>_edge_cases.py 创建运行测试确认复现
阶段声明:
🧪 Phase 2: 问题复现
正在创建 P0 复现测试 + P1 边界测试...
完成标准: P0 测试稳定复现 Bug(fail),P1 测试创建完成
目标: 在 worktree 中最小化修复 Bug
步骤:
创建 worktree
git worktree add <WORKTREE_BASE_DIR>/<bug> -b fix/<bug> <DEFAULT_BRANCH>
路径与分支名按"配置自动推断"取
进入 worktree 修改代码
bug-analysis.md 的修复策略修改验证 P0 复现测试通过
tests/<module>/test_<bug>_reproduce.py阶段声明:
🔧 Phase 3: 问题修复
已在 worktree 中修复,准备验证...
完成标准: P0 测试通过,代码修改最小化(仅针对根因)
目标: 全面验证修复 + 创建 P2 回归测试
步骤:
执行 P0 + P1 确认修复
创建 P2 回归测试
tests/<module>/test_<bug>_regression.py 创建运行完整测试套件
CLAUDE.md 测试章节(本地 / 远程)记录 test-report.md
输出:
tests/<module>/test_<bug>_{reproduce,edge_cases,regression}.py.dev_doc/<bug>/test-report.md阶段声明:
✅ Phase 4: 回归测试
正在执行 P0/P1/P2 + 全量测试套件...
完成标准: 0 failures,test-report.md 记录完整
目标: 整理交付
步骤:
提交 worktree
cd <WORKTREE_BASE_DIR>/<bug>
git add -A
git commit -m "[修复] <bug>: <修复描述>"
同步文档到本地分支
cp -r <WORKTREE_BASE_DIR>/<bug>/.dev_doc/<bug>/* .dev_doc/<bug>/
生成 summary.md
git merge --squash fix/<bug>)调用 doc_integrate(如需归位散落文档)
调用 todo_list_manager(更新任务状态)
通知用户
阶段声明:
🎉 Phase 5: 提交完成
Bug修复完成,worktree 已提交,等待用户 merge
完成标准: worktree 已提交、summary.md 已生成、用户已通知
用户说"算了"/"不用了"/"先停一下"/"暂停"时:
git worktree list(记录路径)git status(commit / untracked / staged).dev_doc/<bug>/ 哪些文档已创建git worktree remove + git branch -D fix/<bug>)按"修复闭环"原则处理:
WORKTREE_BASE_DIR 或 DEFAULT_BRANCH 自动推断失败时:
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub ayanjiushishuai/dev_toolkits