bug-reporting-excellence

Bug 报告最佳实践

<default_to_action> 报告 Bug 时：

1. 标题：[组件] 在[条件]下失败，导致[影响]
2. 描述：预期行为 → 实际行为 → 复现步骤
3. 包含：环境、严重程度、截图/日志、业务影响
4. 隔离：缩小条件范围（浏览器、用户、金额阈值）
5. 一个 Bug = 一份报告（不要合并多个问题）

Bug 报告公式：

## [Component] Issue Title
**Severity:** Critical/High/Medium/Low
**Environment:** Production/Staging/Dev

### Expected Behavior
What should happen

### Actual Behavior
What actually happens (with error messages)

### Steps to Reproduce
1. Step one
2. Step two
3. Observe issue

### Impact
How this affects users/business

关键成功因素：

• 可复现的步骤（100%）
• 环境信息（100%）
• 说明业务影响（90%）
• 截图或日志（80%） </default_to_action>

速查卡

严重程度级别

级别	定义	示例
严重	系统宕机、数据丢失、安全问题	数据库被删除、支付故障、凭据泄露
高	主要功能故障、影响众多用户	无法结账、搜索故障、仪表板失效
中	部分功能故障，但有变通方法	筛选器故障（刷新后可用）、导出缓慢
低	视觉问题、罕见边缘情况	按钮在移动设备上换行、工具提示颜色错误

标题公式

❌ 错误：「结账功能坏了」 ✅ 正确：「订单总额超过 $1000 时，Visa 卡支付失败」

模式： [组件] 在[条件]下失败，导致[影响]

---

必要信息

环境详情

Browser: Chrome 120.0.6099.109 (Windows)
OS: Windows 11 Pro
URL: https://example.com/checkout
Date/Time: 2025-10-17 14:23 UTC
User: [email protected] (ID: 12345)
Request ID: abc-123-def-456

支持证据

错误消息：

{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}

控制台日志：

[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)

---

示例：优秀的 Bug 报告

## [Checkout] Payment processing times out for orders > $1000

**Severity:** High
**Environment:** Production
**Affected Users:** ~15% of premium purchases

### Expected Behavior
Payment completes within 5 seconds regardless of amount.

### Actual Behavior
For orders above $1000, payment gateway times out after 30 seconds.
User sees "Payment failed" error. Order not created.

### Steps to Reproduce
1. Add items totaling $1,050 to cart
2. Proceed to checkout
3. Enter payment: Visa 4532 1234 5678 9010
4. Click "Place Order"
5. Wait 30+ seconds
6. Observe timeout error

### Environment
- Browser: Chrome 120 (Windows 11)
- User: [email protected]
- Request ID: abc-123-def-456

### Evidence
Console error: `PaymentGateway timeout: 30000ms exceeded`
Network: /api/checkout: 30.14s (timeout)

### Impact
- Lost revenue: ~$15K/week from failed orders
- 23 support tickets this week
- Affects 15% of orders over $1000

### Additional Context
Started after Oct 15 deployment (v2.3.0)
Possibly related to PR #456 (fraud check)

---

反模式

❌ 错误	问题	✅ 正确
「结账功能坏了」	哪些部分无法使用？	「点击支付按钮后没有响应」
「我看到一个错误」	没有复现步骤	提供包含具体条件的完整步骤
「页面加载很慢」	没有具体信息	「仪表板需要 12 秒才能加载（应少于 3 秒）」
在一份报告中包含多个 Bug	无法分别跟踪	每个 Bug 单独提交一份报告

---

Agent 集成

// Automated bug triage
const triage = await Task("Triage Bug", {
  title: 'Payment fails for orders > $1000',
  description: bugDescription,
  steps: reproductionSteps
}, "qe-quality-analyzer");

// Returns: { severity, priority, component, suggestedAssignee, relatedIssues }

// Duplicate detection
const dupeCheck = await Task("Check Duplicates", {
  bugReport: newBug,
  similarityThreshold: 0.85
}, "qe-quality-analyzer");

// Bug report enhancement
const enhanced = await Task("Enhance Report", {
  originalReport: userSubmittedBug,
  addMissingInfo: true,
  identifyRootCause: true
}, "qe-production-intelligence");

---

Agent 协作提示

记忆命名空间

aqe/bug-reports/
├── triaged/*          - Bug triage results
├── duplicates/*       - Duplicate detection
├── patterns/*         - Recurring bug patterns
└── root-cause/*       - Root cause analyses

Fleet 协作

const bugFleet = await FleetManager.coordinate({
  strategy: 'bug-investigation',
  agents: [
    'qe-quality-analyzer',        // Triage and categorize
    'qe-flaky-test-hunter',       // Check if test-related
    'qe-production-intelligence'  // Check production logs
  ],
  topology: 'parallel'
});

---

相关技能

• technical-writing - 编写清晰的 Bug 文档
• exploratory-testing-advanced - 发现 Bug
• sherlock-review - 调查根本原因

---

请记住

你的 Bug 报告是他人工作的起点。确保它完整（包含所需的全部信息）、清晰（任何人都能照着操作）、简洁（没有冗余信息）且可执行（开发者知道下一步该做什么）。

好的 Bug 报告 = 更快修复 = 更好的产品 = 更满意的用户

技能组合

• 发现 Bug 后 → 从 /test-failure-investigator 开始调查根本原因
• 防止回归 → 使用 /regression-testing 添加测试，防止问题再次发生
• 跟踪质量 → 将数据输入 /test-metrics-dashboard 进行趋势分析

易错点

• Agent 遗漏环境详情（操作系统、浏览器版本、node 版本）——这些信息对复现至关重要
• 以「1. 打开应用」开头的「复现步骤」毫无用处——请注明确切的 URL、用户角色和状态
• Agent 将多个 Bug 合并为一份报告——严格遵守一个 Bug = 一份报告
• 没有标注的截图没有帮助——务必突出显示实际出错的区域
• 严重程度评估往往不准确——Agent 会把所有问题都标为「严重」或都标为「低」