mcpField
B
bug-fix-brief

bug-fix-brief

github.com/giuseppe-trisciuoglio开发3653.0k 次安装7 周前更新
代码仓库

关于 bug-fix-brief

Bug Fix Brief（BFB）是用于在 `docs/bfb/` 创建结构化缺陷修复文档的 Skill，记录复现步骤、根因、修复选项和检查清单，并在写入前征求确认。

主要功能

  1. 01结构化缺陷修复模板
  2. 02记录复现步骤和根因
  3. 03比较修复选项
  4. 04附带验证清单
  5. 05写入前征求确认

适用场景

  1. 01实施修复前记录缺陷
  2. 02记录可复现步骤和实际表现
  3. 03比较跟踪问题的修复方案

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/giuseppe-trisciuoglio/developer-kit --skill bug-fix-brief

安装后在 Claude Code 中输入/bug-fix-brief确认已加载。

详细介绍

Bug Fix Brief（BFB）

概述

此技能用于生成 Bug Fix Brief（BFB）：在 docs/bfb/ 中创建一份结构化文档，统一记录每个 bug 修复的根因、复现步骤、修复方案和检查清单。

适用场景

  • 用户要求创建 BFB
  • 用户想以结构化方式记录 bug 修复
  • 找到 bug 的根因后、实施修复前

触发词：“create BFB”“document bug”“bug fix brief”“document fix”

操作说明

阶段 1：收集信息

检查现有编号：

ls docs/bfb/ 2>/dev/null || echo "Directory does not exist"

向用户询问：

  • BFB 编号（或建议下一个连续编号）
  • 简洁标题（3-5 个词，kebab-case）
  • Issue 链接（例如 #1287）
  • 环境（Prod/Stg/Dev）+ 版本
  • 实际行为与预期行为
  • 根因所在的文件/函数/行号
阶段 2：生成模板

填写完整的 BFB 模板：

## BFB-XXX: [Title]

**Reference:** [Issue link]
**Environment:** [Env] `vX.Y.Z`
**Date:** YYYY-MM-DD

---

### 1. Bug
- **Observed:** [wrong behavior]
- **Expected:** [correct behavior]

### 2. Repro
  1. ...
  2. ... → [错误/输出]

### 3. Cause
`path/file.ext` — `function()` @ line N
[Why it happens, max 3 lines]

### 4. Decision
| Option | Fix | Choice |
|--------|-----|--------|
| A | [desc] | ✅/❌ |
| B | [desc] | ✅/❌ |

**Rationale:** [why]

### 5. Fix
- [ ] [change 1]
- [ ] [test]
- [ ] [verify repro]

### 6. Notes
[recurring patterns, links, warnings]
阶段 3：请求确认

展示生成的 BFB，并使用 AskUserQuestion 询问：

  • “创建 BFB”
  • “创建前编辑”
  • “取消”
阶段 4：写入磁盘

仅在获得批准后：

mkdir -p docs/bfb

写入 docs/bfb/BFB-XXX-title.md

示例

输入：“create BFB for login email null crash”

最终输出：

## BFB-042: Login crash with null email

**Reference:** #1287
**Environment:** Prod `v2.4.1`
**Date:** 2026-05-02

---

### 1. Bug
- **Observed:** App crashes if email field is empty
- **Expected:** Error message "Email required"

### 2. Repro
  1. 打开登录界面
  2. 未输入电子邮件地址就点击“Login” → AuthManager.kt:34 处发生 NullPointerException

### 3. Cause
`AuthManager.kt` — `validateEmail()` @ line 34
Missing null check on email.trim()

### 4. Decision
| Option | Fix | Choice |
|--------|-----|--------|
| A | Add safe call `?.` | ✅ |
| B | Refactor with Result type | ❌ |

**Rationale:** Option A is minimal, zero impact.

### 5. Fix
- [ ] Add `email?.trim()?.isNotEmpty() == true`
- [ ] Test `validateEmail_null_returnsFalse()`
- [ ] Verify repro

### 6. Notes
- Check other forms for missing null checks

最佳实践

  1. **连续编号：**BFB-001、BFB-002，不跳号
  2. **简洁标题：**3-5 个词，文件名使用 kebab-case
  3. **根因：**精确到文件、函数和行号
  4. **至少 2 个修复方案：**说明优缺点和理由
  5. **可验证的检查清单：**每项都必须可测试

约束和警告

  • **必须确认：**写入前务必征求确认
  • **根因最多 3 行：**保持简洁
  • **目录 docs/bfb/：**如果不存在则创建

评论

支持 Markdown