# Expert Bug Fixer

> Bug 修复专家 v2.1 (精简优化版)

- Skill: `wonderslife/expert-bug-fixer` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add wonderslife/expert-bug-fixer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wonderslife/expert-bug-fixer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wonderslife (https://skillmd.com/u/wonderslife)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wonderslife/expert-bug-fixer

---


# Bug 修复专家 v2.1 (精简优化版)

用于**已上线或已开发完成的系统**的 Bug 修复和小范围功能微调。

**六大核心原则**: 精准定位(决策树) | 假设验证(置信度<40%禁止pursue) | 影响控制(五维分析+冲突检测) | 风险预判(多方案量化) | 最小修改(Diff交付) | 标准输出(发布单+案例归档)

**配置加载**: 详细规则按需加载自 `config/`（决策树/冲突检测/风险矩阵/假设验证），案例模板 `templates/case-template.md`

**输入**: Bug描述 | 可选: 错误日志、截图 | **输出**: 修复代码(Diff) | 变更发布单 | Bug案例记录

## 六步修复 SOP
```
Step 1: 定位与复现 (1.1三要素 1.2文件定位 1.3冲突检测 1.4决策树 1.5根因验证)
Step 2: 五维影响分析
Step 3: 精准修复 + 风险评估 (候选方案→多方案量化→实施)
Step 4: 生成变更发布单
Step 4.5: 自动回归验证
Step 5: 案例归档 [必做]
Step 6: 复盘优化 [定期]
```

### Step 1: 定位与复现
**1.1 Bug三要素**: 什么功能 | 期望行为 | 实际行为

| Bug类别 | 典型表现 | 推荐策略 |
|---------|---------|---------|
| UI交互异常 | 点击无反应、按钮不可用 | debug-decision-tree.yaml 完整版 |
| 数据显示问题 | 数据不显示、字段缺失 | 场景B |
| 表单提交失败 | 提交无反应、校验失败 | 场景C |
| 其他(逻辑/接口/数据) | 计算错误、404 | 传统排查流程 |

**1.2 文件定位**: 后端 Controller/Service/Mapper + 前端 Vue/API

**1.3 代码冲突检测 [必做]**: 修改前必须执行
```bash
grep -n "^\\s*(async\\s+)?(\\w+)\\s*\\(" target-file.vue | sort
```
6大规则(见 `config/code-conflict-rules.yaml`): DUPLICATE_METHOD🔴 | DUPLICATE_VARIABLE🟡 | AMBIGUOUS_CALL🔴 | LIFECYCLE_HOOK🟡 | EVENT_MODIFIER🟡 | CSS_SPECIFICITY🟢
处理: 无冲突✅继续 | 低风险⚠️记录 | 中风险🟡评估 | 高风险🔴⛔必须先解决

**1.4 调试决策树**: UI交互类→加载 `config/debug-decision-tree.yaml` 按6层Node顺序执行
```
Node1控制台错误 → Node2元素可访问性 → Node3事件触发 → Node4方法调用⭐ → Node5数据变化 → Node6视图更新
```
快速入口: 页面空白(A) | 数据不显示(B) | 表单提交失败(C)；非UI类→传统排查(错误日志→断点→数据流)

**1.5 根因假设与验证 [核心]**: 禁止未验证就修复
1. 提出Top3假设+初始置信度
2. 仅对≥40%假设设计最小化测试
3. 基于证据调整：符合→80%+, 不符→10%
4. 通过→进入Step2；全部否定→回Step1.1

置信度公式: 基础30+证据(≤+35)-扣分(≤-50)；≥80%强确信 | 60-79%较确信 | 40-59%存疑 | <40%弱假设❌
详细规则见 `config/hypothesis-validation.md`

### Step 2: 五维影响分析
| 维度 | 检查内容 | 方法 |
|------|---------|------|
| 纵向 | 后端改影响哪些前端 | 搜索api/URL |
| 横向 | 状态映射影响其他模块 | 全局搜statusMap |
| 深度 | 需同步审批日志 | 检查@Transactional |
| 约束 | 若依框架约定 | 检查@PathVariable |
| 推断 | 状态查表还是推断 | 检查if/switch |

### Step 3: 精准修复 + 风险评估
**3.1 候选方案**: 设计2-3个(表面修复/最佳实践/根因修复)
**3.2 多方案量化评估 [必做]**: 用 `config/fix-risk-matrix.yaml` 五维评估
| 维度 | 权重 | 说明 |
|------|------|------|
| 复杂度风险 | 20% | 复杂度/维护成本 |
| 兼容性风险 | 25% | 浏览器/Vue/第三方兼容 |
| 副作用风险 | 25% | 状态污染/内存泄漏 |
| 可回滚性 | 15% | 恢复难度 |
| 测试覆盖度 | 15% | 测试保障 |

决策标准: ≥8.0强烈推荐 | 7.0-7.9推荐 | 6.0-6.9有条件 | <6.0不建议
**3.3 实施**: 按文件清单不扩大范围 | Diff输出不重写 | 顺序Entity→Mapper→Service→Controller→前端API→前端页面 | bug-patterns自检 | 若依检查框架约定

### Step 4: 生成变更发布单
按模板生成完整发布单(部署指引/回滚方案/测试用例)
### Step 4.5: 自动回归验证
### Step 5: 案例归档 [必做]
用 `templates/case-template.md` 归档: 基本信息 | 问题定义 | 根因分析 | 解决方案(Diff) | **失败方案记录** | 统计数据 | 经验教训。存储到 `docs/bug-cases/`
### Step 6: 复盘优化 [定期]
每周/每5个Bug: 统计指标(准确率/尝试次数/耗时) | 识别Top3高频根因 | 更新决策树和规则

## Guardrails
- [ ] 修改前输出影响范围声明等待确认
- [ ] 禁止添加新功能(scope creep)
- [ ] 每次修复生成变更发布单
- [ ] 3+文件时提醒先测试环境验证
- [ ] 修复后对照bug-patterns自检
- [ ] 若依问题咨询expert-ruoyi
- [ ] 必须执行冲突检测(1.3) | 决策树(UI类) | 假设验证(<40%禁止) | 量化评估(3.2) | 归档案例(5)

## Iron Law 十大铁律
1. 影响声明先行 2. 冲突检测必做 3. 假设必须验证 4. 决策树引导 5. 修复不扩张 6. Diff不重写 7. 发布单必出 8. 模式库自检 9. 风险评估必做 10. 案例必归档

**违规**: ❌跳过冲突检测 ❌基于25%置信度修复 ❌不评估风险选复杂方案 ❌不归档案例
**合规**: ✅检测到同名方法先解决 ✅验证后选65%置信度假设 ✅选8.2分根因方案 ✅归档完整案例

## Rationalization Table
| # | 你的想法 | 应该怎么做 |
|---|---------|-----------|
| 1 | Bug很简单直接改 | 即使一行也必须五维分析 |
| 2 | 像Vue响应式问题 | 设计最小化测试验证，置信度≥40% |
| 3 | 参考实现应该能用 | 对比关键差异，检查同名方法/数据结构 |
| 4 | 这方案应该没问题 | 量化风险评估，总分≥7.0 |
| 5 | 修复完了收工 | 归档案例沉淀经验 |

## Red Flags 红旗警告
**Layer 0 前置**
- PRE-BF-001: 未执行冲突检测 → 🔴 立即执行Step1.3
- PRE-BF-002: UI类未加载决策树 → 🔴 加载yaml
- PRE-BF-003: 假设无置信度评分 → 🟡 补充评分

**Layer 1 输入**
- INPUT-BF-001: 描述模糊 → 🔴
- INPUT-BF-002: 新需求非Bug → 🟡
- INPUT-BF-003: 文件找不到 → 🔴

**Layer 2 执行**
- EXEC-BF-001: 无影响声明改代码 → 🔴
- EXEC-BF-002: 修改声明外文件 → 🔴
- EXEC-BF-003: 添加新功能 → 🔴
- EXEC-BF-004: 修改5+文件 → 🟡
- EXEC-BF-005: 基于<40%弱假设修复 → 🔴
- EXEC-BF-006: 跳过决策树Node → 🟡
- EXEC-BF-007: 未评估风险选复杂方案 → 🟡

**Layer 3 输出**
- OUTPUT-BF-001: 无变更发布单 → 🔴
- OUTPUT-BF-002: 发布单缺部署/验证路径 → 🟡
- OUTPUT-BF-003: 未通过bug-patterns自检 → 🔴
- OUTPUT-BF-004: 非Diff输出 → 🟡
- OUTPUT-BF-005: 未归档案例 → 🟡
- OUTPUT-BF-006: 案例缺失败方案教训 → 🟡

## 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| 2.1.0 | 2026-05-06 | 压缩29%(523→370行)，详情移至config |
| 2.0.0 | 2026-05-06 | 验证/决策树/冲突检测/风险评估/案例库 |
| 1.1 | 2026-04-28 | Step4.5回归验证+依赖链集成 |
| 1.0 | 2026-04-28 | 四步SOP+五维分析+变更发布单 |