# Bug Report

> 创建 bug 工单。把缺陷整理成 docs/bugs/ 下的规范工单：现象、复现步骤、预期与实际、影响范围、验收判据；只写查证过的事实，不写修复方案。工单是一次性交接文档，修完即删、不维护。用于「记一个 bug」「提个工单」「把这个问题记下来」等场景。

- Skill: `baijunjie/bug-report` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add baijunjie/bug-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/baijunjie/bug-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: baijunjie (https://skillmd.com/u/baijunjie)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/baijunjie/bug-report

---


# 创建 bug 工单

把本次描述的缺陷整理成一份工单。**只写事实**——用户说的，以及你查证到的；没查证的不写，缺的信息问用户。

工单的唯一用途是**把问题交接给修复者**：说清哪里不对、怎么复现、怎么算修好。
它是一次性文档——**修完就删，不记进度、不写修复过程、不做状态流转**，任何地方都不许引用它。

## 目录与命名

- 工单目录默认 `docs/bugs/`，项目已有自己的约定时按项目的
- 一个 bug 一份文件 `YYYYMMDD-{中文简述}.md`，日期是工单创建日期
- 同一缺陷的新表现追加进已有工单（这是建单方补充现象，不是修复进度）；
  表象相似但根因明显不同的分开建

## 工单格式

开头一行标注严重程度：

```
> 严重程度: <致命 / 严重 / 一般 / 轻微 之一>
```

判据：致命＝数据损坏或核心流程不可用；严重＝主要功能失效且无法绕过；一般＝功能受损但有绕法；
轻微＝体验或文案问题。拿不准取高的那档。

正文按以下小节写，查不到的写「未知」，**不要省略小节，也不要用猜测填**：

- **现象**：出了什么错，一句话说清
- **复现步骤**：编号步骤，写到照着能复现的粒度；偶发的写明触发条件与出现概率。**不许写「未知」**
- **预期与实际**：各一行。预期行为**不许写「未知」**，并写明它的依据——
  产品文档里的哪一条，或用户当场确认的口径
- **环境**：版本、平台、配置、数据前提等影响复现的条件
- **影响范围**：谁受影响、有没有绕法
- **线索**：已掌握的报错、日志、可疑位置，**每条标明是查证的还是推断的**
- **验收判据**：怎么算修好了，写成能逐条验证的条件

复现步骤或预期行为问不出来就不要建工单，先告诉用户还缺什么。

## 不写什么

- **修复方案与实现代码** —— 工单只界定问题，怎么修是修复阶段的事
- **待办清单、进度、状态流转** —— 工单不是任务板，修复者不回来更新它
- **未经验证的猜测当结论写** —— 推断一律归进「线索」并标明
- 复述代码
- 过程与归属：谁报的、什么时候讨论过、谁写的这段代码