Back to Details

bug-reporting-excellence

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Reporting Excellence

高质量Bug报告编写指南

<default_to_action> When reporting bugs:
  1. TITLE: 
    [Component] fails [Condition] causing [Impact]
  2. DESCRIBE: Expected behavior → Actual behavior → Steps to reproduce
  3. INCLUDE: Environment, severity, screenshots/logs, business impact
  4. ISOLATE: Narrow down conditions (browser, user, amount thresholds)
  5. ONE BUG = ONE REPORT (don't combine issues)
Bug Report Formula:
markdown
undefined
<default_to_action> 提交Bug时：
  1. 标题：
    [Component] fails [Condition] causing [Impact]
  2. 描述：预期行为 → 实际行为 → 复现步骤
  3. 需包含内容：环境、severity、截图/日志、业务影响
  4. 隔离问题：缩小问题触发条件范围（浏览器、用户、金额阈值等）
  5. 一个Bug = 一份报告（不要合并多个问题）
Bug报告模板：
markdown
undefined

[Component] Issue Title

[Component] Issue Title

Severity: Critical/High/Medium/Low Environment: Production/Staging/Dev
Severity: Critical/High/Medium/Low Environment: Production/Staging/Dev

Expected Behavior

Expected Behavior

What should happen
What should happen

Actual Behavior

Actual Behavior

What actually happens (with error messages)
What actually happens (with error messages)

Steps to Reproduce

Steps to Reproduce

  1. Step one
  2. Step two
  3. Observe issue
  1. Step one
  2. Step two
  3. Observe issue

Impact

Impact

How this affects users/business

**Critical Success Factors:**
- Reproducible steps (100%)
- Environment info (100%)
- Business impact stated (90%)
- Screenshots or logs (80%)
</default_to_action>
How this affects users/business

**关键成功要素：**
- 可100%复现的步骤
- 完整的环境信息（100%）
- 明确的业务影响说明（90%）
- 截图或日志（80%）
</default_to_action>

Quick Reference Card

快速参考卡

Severity Levels

严重等级（Severity Levels）

LevelDefinitionExamples
CriticalSystem down, data loss, securityDB deleted, payments broken, credentials exposed
HighMajor feature broken, many usersCan't checkout, search broken, dashboard fails
MediumPartial break, workaround existsFilter broken (refresh works), slow export
LowCosmetic, rare edge caseButton wraps on mobile, tooltip wrong color
等级定义示例
Critical系统宕机、数据丢失、安全问题数据库被删除、支付功能不可用、凭证泄露
High核心功能故障、影响大量用户无法结账、搜索功能失效、仪表盘加载失败
Medium部分功能故障、存在临时解决方案筛选功能失效（刷新可恢复）、导出速度慢
Low样式问题、罕见边缘场景移动端按钮换行、提示框颜色错误

Title Formula

标题编写规则

❌ Bad: "Checkout broken" ✅ Good: "Payment fails with Visa cards when order total > $1000"
Pattern: 
[Component] fails [Condition] causing [Impact]
❌ 错误示例："Checkout broken" ✅ 正确示例："Payment fails with Visa cards when order total > $1000"
规则： 
[Component] fails [Condition] causing [Impact]

Essential Information

必备信息

Environment Details

环境详情

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: test@example.com (ID: 12345)
Request ID: abc-123-def-456
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: test@example.com (ID: 12345)
Request ID: abc-123-def-456

Supporting Evidence

佐证材料

Error Messages:
json
{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}
Console Logs:
[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)
错误信息：
json
{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}
控制台日志：
[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)

Example: Excellent Bug Report

示例：优秀Bug报告

markdown
undefined
markdown
undefined

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

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

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

Expected Behavior

Expected Behavior

Payment completes within 5 seconds regardless of amount.
Payment completes within 5 seconds regardless of amount.

Actual Behavior

Actual Behavior

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

Steps to Reproduce

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
  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

Environment

  • Browser: Chrome 120 (Windows 11)
  • User: test@example.com
  • Request ID: abc-123-def-456
  • Browser: Chrome 120 (Windows 11)
  • User: test@example.com
  • Request ID: abc-123-def-456

Evidence

Evidence

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

Impact

Impact

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

Additional Context

Additional Context

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

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

---

Anti-Patterns

反模式

❌ BadProblem✅ Good
"Checkout is broken"What doesn't work?"Payment button doesn't respond when clicked"
"I saw an error"No reproduction stepsFull steps with conditions
"Page loads slowly"No specifics"Dashboard takes 12s to load (should be <3s)"
Multiple bugs in oneCan't track separatelyOne report per bug
❌ 错误写法问题✅ 正确写法
"Checkout is broken"未说明具体故障点"Payment button doesn't respond when clicked"
"I saw an error"没有复现步骤包含触发条件的完整复现步骤
"Page loads slowly"没有具体指标"Dashboard takes 12s to load (should be <3s)"
一份报告包含多个Bug无法单独跟踪处理每个Bug单独提交报告

Agent Integration

Agent集成

typescript
// 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");
typescript
// 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 Coordination Hints

Agent协同说明

Memory Namespace

内存命名空间

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

Fleet Coordination

集群协同

typescript
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'
});
typescript
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'
});

Related Skills

相关技能

  • technical-writing - Clear bug documentation
  • exploratory-testing-advanced - Finding bugs
  • sherlock-review - Root cause investigation
  • technical-writing - 清晰的Bug文档编写
  • exploratory-testing-advanced - Bug挖掘
  • sherlock-review - 根因调查

Remember

注意要点

Your bug report is the starting point for someone else's work. Make it complete (all info needed), clear (anyone can follow), concise (no noise), and actionable (developer knows next step).
Good bug reports = Faster fixes = Better product = Happier users
你的Bug报告是其他人工作的起点。要确保报告完整（包含所有需要的信息）、清晰（任何人都能看懂）、简洁（无冗余信息）、可执行（开发人员知道下一步要做什么）。
好的Bug报告 = 更快的修复 = 更好的产品 = 更满意的用户