bug-reporting
SKILL.md
缺陷上报（中文版）
英文版： 见技能 bug-reporting-en。
提示词见本目录 prompts/bug-reporting.md。
何时使用
- 用户提到「缺陷上报」「bug reporting」「缺陷报告」「bug report」
- 需要编写或优化缺陷报告
- 触发示例：「帮我写一个缺陷报告」「优化这个 bug 描述」
输出格式选项
本技能默认输出为 Markdown（与 Standard-version 模板一致）。若需其他格式，请在需求末尾明确说明：
| 格式 | 说明 | 如何请求（示例） |
|---|---|---|
| Markdown | 默认，便于阅读与版本管理 | 无需额外说明 |
| Jira | Jira 格式，包含自定义字段 | 「请以 Jira 格式输出」 |
| GitHub Issues | GitHub Issues 格式 | 「请以 GitHub Issues 格式输出」 |
| Excel | 制表符分隔，可粘贴到 Excel | 「请以 Excel 可粘贴的制表符分隔表格输出」 |
| CSV | 逗号分隔，首行为表头 | 「请以 CSV 格式输出」 |
| JSON | 便于程序解析 | 「请以 JSON 形式输出」 |
详细说明与示例见本目录 output-formats.md。
如何使用
- 打开本目录
prompts/下对应提示词文件，复制虚线以下内容。 - 附加你的需求与上下文（业务流程、环境、约束、验收标准）。
- 若需非 Markdown 输出，在末尾追加
output-formats.md中的请求句。
参考文件
- prompts/bug-reporting.md — 缺陷上报 Standard-version 提示词
- output-formats.md — Markdown / Jira / GitHub / Excel / CSV / JSON 请求说明
代码示例 | Code Examples
本技能提供以下真实代码示例：
-
Bug Report 模板和示例 - 完整的缺陷报告模板集
- 10+ 个真实缺陷报告示例
- 多种格式模板（Markdown、Jira、GitHub）
- 最佳实践和反模式对比
- 自动化报告生成脚本
-
截图和日志收集工具（即将推出）
-
缺陷报告质量检查器（即将推出）
查看 examples/ 目录获取更多示例。
常见误区 | Common Pitfalls
- ❌ 标题不清晰 → ✅ 使用简洁明确的标题，包含关键信息
- ❌ 缺少复现步骤 → ✅ 提供详细的、可重现的步骤
- ❌ 没有环境信息 → ✅ 包含操作系统、浏览器、版本等信息
- ❌ 只说"不工作" → ✅ 描述预期行为和实际行为的差异
- ❌ 没有附件 → ✅ 添加截图、视频、日志文件
- ❌ 情绪化描述 → ✅ 保持客观、专业的语气
- ❌ 一个报告多个问题 → ✅ 每个缺陷单独报告
最佳实践 | Best Practices
1. 标题编写
好的标题：
- ✅
[登录] 使用特殊字符密码时登录失败 - ✅
[购物车] 删除商品后总价未更新 - ✅
[iOS] 应用在 iPhone 12 上启动崩溃
不好的标题：
- ❌
登录有问题 - ❌
Bug - ❌
这个不工作
2. 复现步骤
使用编号列表，清晰具体：
## 复现步骤
1. 打开应用并登录（用户名：test@example.com）
2. 点击"购物车"图标
3. 在购物车中添加商品 A（价格：¥100）
4. 添加商品 B（价格：¥200）
5. 点击商品 A 旁边的"删除"按钮
6. 观察总价显示
## 预期结果
总价应该更新为 ¥200（只有商品 B）
## 实际结果
总价仍然显示 ¥300（未更新）
3. 环境信息
提供完整的环境信息：
## 测试环境
- **操作系统**: macOS 13.5
- **浏览器**: Chrome 120.0.6099.109
- **应用版本**: v2.3.1
- **测试环境**: Staging (https://staging.example.com)
- **用户角色**: 普通用户
- **网络**: WiFi
- **屏幕分辨率**: 1920x1080
4. 严重程度和优先级
严重程度（Severity）：
- Critical（致命）: 系统崩溃、数据丢失、安全漏洞
- High（高）: 核心功能无法使用
- Medium（中）: 功能可用但有明显问题
- Low（低）: 界面问题、文字错误
优先级（Priority）：
- P0: 立即修复（阻塞发布）
- P1: 尽快修复（本周内）
- P2: 计划修复（本迭代内）
- P3: 可以延后（下个迭代）
5. 附件和证据
- 📸 截图: 标注关键区域
- 🎥 视频: 展示操作过程
- 📄 日志: 控制台日志、错误日志
- 🔗 链接: 相关文档、类似问题
6. 影响范围
说明问题的影响：
## 影响范围
- **影响用户**: 所有使用购物车的用户
- **发生频率**: 100%（每次删除商品都会出现）
- **业务影响**: 用户可能支付错误金额，导致投诉
- **变通方案**: 刷新页面后总价会正确显示
故障排除 | Troubleshooting
问题1：缺陷被标记为"无法复现"
症状：开发人员无法复现你报告的问题
解决方案：
- 提供更详细的复现步骤
- 录制视频展示问题
- 提供测试数据和账号
- 检查是否是环境特定问题
- 与开发人员一起复现
改进示例：
## 复现步骤（详细版）
**前置条件**：
- 使用测试账号：test@example.com / Test123!
- 购物车中已有 2 件商品
- 浏览器清除缓存和 Cookie
**详细步骤**：
1. 打开 Chrome 浏览器（版本 120+）
2. 访问 https://staging.example.com
3. 点击右上角"登录"按钮
4. 输入邮箱：test@example.com
5. 输入密码：Test123!
6. 点击"登录"按钮
7. 等待页面跳转到首页（约 2 秒）
8. 点击右上角购物车图标（显示数字 2）
9. 在购物车页面，找到第一件商品
10. 点击该商品右侧的红色"删除"按钮
11. 观察页面右上角的总价显示
**预期**: 总价从 ¥300 变为 ¥200
**实际**: 总价仍显示 ¥300
**附件**:
- 视频: bug-reproduction.mp4
- 控制台日志: console-log.txt
问题2：缺陷报告被认为不够清晰
症状：需要多次来回沟通才能理解问题
解决方案：
- 使用 5W1H 原则（What, When, Where, Who, Why, How）
- 添加截图并标注关键区域
- 使用对比表格展示预期 vs 实际
- 提供具体的数据示例
改进示例：
## 问题描述
**What（什么问题）**: 用户无法使用特殊字符作为密码登录
**When（何时发生）**:
- 首次发现：2024-02-06 14:30
- 发生频率：每次使用包含 `@#$%` 的密码时
**Where（在哪里）**:
- 页面：登录页面 (https://example.com/login)
- 组件：密码输入框
**Who（影响谁）**:
- 所有使用特殊字符密码的用户
- 估计影响 15% 的用户（根据密码策略）
**Why（为什么重要）**:
- 密码策略要求使用特殊字符
- 用户无法登录会导致流失
**How（如何表现）**:
| 密码类型 | 示例 | 能否登录 |
|---------|------|---------|
| 纯字母 | `abcdefgh` | ✅ 可以 |
| 字母+数字 | `abc12345` | ✅ 可以 |
| 包含 `@` | `abc@1234` | ❌ 失败 |
| 包含 `#` | `abc#1234` | ❌ 失败 |
| 包含 `$` | `abc$1234` | ❌ 失败 |
问题3：不知道如何确定严重程度
症状：不确定应该标记为 High 还是 Medium
解决方案：
使用决策树：
1. 是否导致系统崩溃/数据丢失/安全问题？
是 → Critical
否 → 继续
2. 是否影响核心业务流程？
是 → High
否 → 继续
3. 是否有变通方案？
无 → High
有 → 继续
4. 是否影响用户体验？
严重影响 → Medium
轻微影响 → Low
问题4：缺陷报告太长，没人看
症状：报告写得很详细，但开发人员反馈太长
解决方案：
使用"倒金字塔"结构：
# [登录] 特殊字符密码登录失败
## 🔴 快速摘要（30秒阅读）
使用包含 `@#$%` 等特殊字符的密码无法登录。
影响 15% 用户，无变通方案。
## 📋 核心信息
- **严重程度**: High
- **影响**: 所有使用特殊字符密码的用户
- **频率**: 100%
- **环境**: 所有浏览器
## 🔄 快速复现（3步）
1. 访问登录页面
2. 输入密码 `Test@123`
3. 点击登录 → 失败
---
## 📖 详细信息（需要时展开）
<details>
<summary>详细复现步骤</summary>
1. 打开浏览器...
2. ...（详细步骤）
</details>
<details>
<summary>环境信息</summary>
- OS: macOS 13.5
- Browser: Chrome 120
- ...
</details>
<details>
<summary>技术细节</summary>
控制台错误：
Error: Invalid character in password field
</details>
问题5：不知道如何描述间歇性问题
症状：问题时有时无，难以描述
解决方案：
记录多次观察：
## 问题描述
登录功能间歇性失败
## 观察记录
| 时间 | 结果 | 环境 | 备注 |
|------|------|------|------|
| 2024-02-06 10:00 | ✅ 成功 | Chrome | 首次尝试 |
| 2024-02-06 10:05 | ❌ 失败 | Chrome | 第二次尝试 |
| 2024-02-06 10:10 | ❌ 失败 | Chrome | 第三次尝试 |
| 2024-02-06 10:15 | ✅ 成功 | Chrome | 第四次尝试 |
| 2024-02-06 14:00 | ❌ 失败 | Firefox | 首次尝试 |
## 模式分析
- **失败率**: 60% (6/10 次尝试)
- **可能相关因素**:
- 时间：上午失败率更高
- 网络：WiFi 环境下更容易失败
- 负载：可能与服务器负载相关
## 可能的根因假设
1. 服务器负载过高时超时
2. 网络不稳定导致请求失败
3. Session 管理问题
问题6：缺陷被标记为"按设计工作"
症状：你认为是 bug，但被告知是预期行为
解决方案：
- 引用需求文档或设计稿
- 说明用户体验问题
- 提供竞品对比
- 建议改进方案
## 问题描述
删除购物车商品需要二次确认，影响用户体验
## 为什么这是问题
**用户体验角度**：
- 用户期望：点击删除后直接删除（可撤销）
- 实际体验：需要点击两次，增加操作成本
- 竞品对比：淘宝、京东都是直接删除+撤销
**数据支持**：
- 用户调研：85% 用户认为二次确认多余
- 操作数据：60% 用户在确认弹窗停留超过 3 秒
**建议方案**：
1. 直接删除，提供"撤销"按钮（推荐）
2. 只在删除多件商品时确认
3. 添加"不再提示"选项
## 参考
- 需求文档：PRD-2024-001 第 3.2 节
- 设计稿：Figma 链接
- 竞品分析：attached-competitor-analysis.pdf
问题7：不知道如何报告性能问题
症状：页面"很慢"，但不知道如何量化
解决方案：
提供性能指标：
## 问题描述
首页加载速度过慢
## 性能数据
**测试方法**: Chrome DevTools Performance 面板
**测试结果**:
| 指标 | 当前值 | 目标值 | 状态 |
|------|--------|--------|------|
| FCP (First Contentful Paint) | 3.2s | <1.8s | ❌ 超标 |
| LCP (Largest Contentful Paint) | 5.8s | <2.5s | ❌ 超标 |
| TTI (Time to Interactive) | 7.2s | <3.8s | ❌ 超标 |
| Total Blocking Time | 850ms | <200ms | ❌ 超标 |
**网络条件**: Fast 3G (模拟)
**性能瓶颈**:
1. 主线程阻塞 2.3s（JavaScript 执行）
2. 图片未优化（总大小 4.5MB）
3. 未使用 CDN
4. 未启用 Gzip 压缩
**附件**:
- Performance 报告: performance-report.json
- Network 截图: network-waterfall.png
- Lighthouse 报告: lighthouse-report.html
获取更多帮助
如果问题仍未解决：
- 查看 FAQ.md
- 查看示例的 README.md 文件
- 参考缺陷报告模板
- 咨询团队的测试负责人
相关技能： manual-testing、test-case-writing、test-reporting、functional-testing。
目标受众
- 在真实项目中执行该测试域工作的 QA 与开发人员
- 需要结构化、可复用测试交付物的测试负责人
- 需要快速生成可落地测试产出的 AI 使用者
不适用场景
- 无测试范围上下文的纯线上应急处置
- 需要法律/合规最终裁定但缺少专家复核的决策
- 缺少最小输入（范围、环境、期望行为）的请求
关键成功因素
- 先明确范围、环境与验收标准，再生成测试内容
- 生成结果必须结合真实系统约束做二次校验
- 保持产物可追踪（需求 -> 测试点 -> 缺陷 -> 决策）
输出模板与解析脚本
- 模板目录：
output-templates/template-word.md（Word 友好结构）template-excel.tsv（Excel 可直接粘贴）template-xmind.md（XMind 结构化大纲）template-json.jsontemplate-csv.csvtemplate-markdown.md
- 解析脚本目录：
scripts/- 解析通用：
parse_output_formats.py - 解析按格式：
parse_word.py、parse_excel.py、parse_xmind.py、parse_json.py、parse_csv.py、parse_markdown.py - 转换通用：
convert_output_formats.py - 转换按格式：
convert_to_word.py、convert_to_excel.py、convert_to_xmind.py、convert_to_json.py、convert_to_csv.py、convert_to_markdown.py - 批量转换：
batch_convert_templates.py（批量输出到artifacts/）
- 解析通用：
示例：
python3 scripts/parse_json.py output-templates/template-json.json
python3 scripts/parse_markdown.py output-templates/template-markdown.md
python3 scripts/convert_to_json.py output-templates/template-markdown.md
python3 scripts/convert_output_formats.py output-templates/template-json.json --to csv
python3 scripts/batch_convert_templates.py --skip-same
Weekly Installs
7
Repository
naodeng/awesome…a-skillsGitHub Stars
3
First Seen
10 days ago
Security Audits
Installed on
cursor7
gemini-cli6
github-copilot6
codex6
amp6
cline6