bug-reporting-excellence

バグ報告のベストプラクティス

<default_to_action> バグを報告する場合：

1. タイトル：[コンポーネント] が [条件] で失敗し、[影響] が発生する
2. 説明：期待される動作 → 実際の動作 → 再現手順
3. 含める情報：環境、重大度、スクリーンショット／ログ、ビジネスへの影響
4. 条件を絞り込む：ブラウザー、ユーザー、金額のしきい値など
5. 1 件のバグにつき 1 件の報告にする（複数の問題をまとめない）

バグ報告の基本式：

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

クイックリファレンスカード

重大度レベル

レベル	定義	例
Critical	システム停止、データ損失、セキュリティ問題	DB が削除された、決済が機能しない、認証情報が漏えいした
High	主要機能が壊れている、多数のユーザーに影響	チェックアウトできない、検索が機能しない、ダッシュボードが失敗する
Medium	一部の機能に問題があるが、回避策がある	フィルターが機能しない（再読み込みで解決）、エクスポートが遅い
Low	見た目の問題、まれなエッジケース	モバイルでボタンの文字が折り返される、ツールチップの色が間違っている

タイトルの形式

❌ 悪い例：「チェックアウトが壊れている」 ✅ 良い例：「注文合計が 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)

---

例：優れたバグ報告

## [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 秒未満）」
1 件に複数のバグ	個別に追跡できない	バグ 1 件につき報告 1 件

---

エージェントとの連携

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

---

エージェント連携のヒント

メモリの名前空間

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

フリート連携

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 - 明確なバグの文書化
• exploratory-testing-advanced - バグの発見
• sherlock-review - 根本原因の調査

---

覚えておくこと

バグ報告は、誰かが作業を始めるための出発点です。完全（必要な情報がすべてそろっている）、明確（誰でも理解できる）、簡潔（余計な情報がない）、実行可能（開発者が次の手順を把握できる）な報告にしてください。

優れたバグ報告 ＝ 修正の迅速化 ＝ より良い製品 ＝ より満足度の高いユーザー

スキルの組み合わせ

• バグを発見した後 → /test-failure-investigator から始めて根本原因を調査します
• 再発を防ぐ → /regression-testing を使って再発防止テストを追加します
• 品質を追跡する → 傾向分析のために /test-metrics-dashboard にデータを取り込みます

注意点

• エージェントが環境の詳細（OS、ブラウザーのバージョン、Node.js のバージョン）を省略することがあります。再現には不可欠です
• 「1. アプリを開く」から始まる「再現手順」は役に立ちません。正確な URL、ユーザーのロール、状態を指定してください
• エージェントが複数のバグを 1 件の報告にまとめることがあります。必ず「1 件のバグにつき 1 件の報告」を徹底してください
• 注釈のないスクリーンショットでは役に立ちません。実際にエラーが発生している箇所を必ず強調してください
• 重大度の評価は誤りがちです。エージェントがすべてを「Critical」またはすべてを「Low」と分類することがあります