バグレポートの作成

概要

開発者がバグを再現し、理解し、修正するために必要な情報をすべて含んだ、包括的で実行可能なバグレポートを作成します。すべてのバグレポートには、再現手順、環境詳細、および予想される動作と実際の動作の明確な区別が含まれる必要があります。

ワークフロー

1. プロジェクトコンテキストを確認 — .chalk/docs/ で以下をチェック:

   • アーキテクチャドキュメント(影響を受けるコンポーネントを特定するため)
   • 過去のバグレポート(形式と規約を一致させるため)
   • 既知の問題または関連する可能性のある最近の変更
   • package.json、pyproject.toml などからのバージョン情報

2. バグの詳細を収集 — $ARGUMENTS と会話コンテキストから以下を抽出:

   • ユーザーが観察した内容(実際の動作)
   • ユーザーが期待していた動作
   • バグが最初に報告された時期
   • バグの発生頻度(常に、時々、一度だけ)
   • エラーメッセージ、ログ、またはスタックトレース
   • 詳細が不足している場合は、ユーザーに的を絞った質問をします(下の「必要な情報」を参照)

3. 環境を特定 — 以下を特定するか質問:

   • アプリケーションバージョンまたはコミットハッシュ
   • オペレーティングシステムとバージョン
   • ブラウザとバージョン(Webアプリの場合)
   • デバイスタイプ(モバイルアプリの場合)
   • 関連する設定(フィーチャーフラグ、ユーザーロール、ロケール)
   • 環境(本番環境、ステージング環境、ローカル)

4. 再現手順を記述 — ユーザーの説明を番号付きの具体的な手順に変換:

   • 既知の状態から開始(例:「標準ユーザーとしてログイン」)
   • 各手順は単一の観察可能なアクション
   • 使用した具体的なデータを含める(例:「メールフィールドに 'test@example.com' を入力する」「メールを入力する」ではなく)
   • バグが発生する正確なポイントを記述
   • バグが間欠的な場合は、およその再現率を記述

5. 重大度を割り当て — 重大度マトリックスを使用:

   • Critical(致命的): データ損失、セキュリティ脆弱性、機能の完全な停止、回避方法なし
   • High(高): 主要な機能の障害、重大な影響、回避方法が困難
   • Medium(中): 機能の劣化、回避方法が存在、中程度の影響
   • Low(低): 外観の問題、軽微な不便、回避方法が容易

6. 二分探索ヒントを特定 — 可能な限り以下を特定:

   • これが最後に正しく動作したのはいつ?(バージョン、日付、またはコミット)
   • 「動作している」状態から「壊れた」状態の間で何が変わった?(デプロイメント、設定変更、データマイグレーション)
   • これにより調査範囲を劇的に縮小できます

7. 関連する問題をチェック — .chalk/docs/engineering/ を検索:

   • 類似のバグレポート(重複を避けるため)
   • 根本原因を共有する可能性のある関連バグ
   • コンテキストを提供する関連アーキテクチャまたは設計の決定

8. 次のファイル番号を特定 — .chalk/docs/engineering/ 内の *_bug_* にマッチするファイルをリスト。最も大きい番号を見つけて1ずつ増やします。

9. バグレポートを作成 — .chalk/docs/engineering/<n>_bug_<slug>.md に保存するか、必要に応じてGitHubイシューの形式でフォーマットします。

10. 確認 — バグレポートをユーザーに提示します。レポートを改善するために不足している情報をハイライトします。

ファイル名の規則

<number>_bug_<snake_case_slug>.md

例:

• 6_bug_login_timeout_on_slow_connections.md
• 13_bug_duplicate_orders_on_retry.md

バグレポートのフォーマット

# Bug: <説明的なタイトル>

**報告日**: <YYYY-MM-DD>
**重大度**: Critical | High | Medium | Low
**ステータス**: Open
**コンポーネント**: <影響を受けるコンポーネントまたはモジュール>
**報告者**: <名前または識別子>

## 環境

| フィールド | 値 |
|----------|-----|
| アプリバージョン | <バージョンまたはコミットハッシュ> |
| OS | <OS名とバージョン> |
| ブラウザ | <ブラウザとバージョン(該当する場合)> |
| デバイス | <デバイスタイプ(該当する場合)> |
| 環境 | Production / Staging / Local |
| ユーザーロール | <ロールまたは権限レベル> |
| フィーチャーフラグ | <有効/無効な関連フラグ> |

## 概要

<バグの1～2文での説明。何が壊れており、ユーザーへの影響は何か。>

## 再現手順

**前提条件**: <開始状態。例:「ダッシュボードページ上で管理者ロールを持つユーザーとしてログイン」>

1. <具体的なデータを伴う特定のアクション>
2. <次の特定のアクション>
3. <バグが発生するアクション>

**再現率**: Always | ~X% | Intermittent (Y回中X回観察)

## 予想される動作

<上記の手順に従うときに起こるべきこと。>

## 実際の動作

<実際に起こることを具体的に記述:エラーメッセージ、不正な値、表示の不具合を含めます。>

## エラー出力

<スタックトレース、コンソールエラー、サーバーログ、またはエラーメッセージ。コードブロックを使用します。>

<エラー出力をここに貼り付け>

## スクリーンショット/動画

<スクリーンショットまたは動画が示す内容を記述します。利用可能な場合は添付ファイルを参照。>

## 二分探索ヒント

| フィールド | 値 |
|----------|-----|
| 最後に動作していた | <バージョン、日付、または「不明」> |
| 最初に壊れた | <バージョン、日付、または「現在」> |
| 疑わしい原因 | <最近のデプロイメント、設定変更、データマイグレーション、または「不明」> |

## 影響評価

| 項目 | 評価 |
|----|-----|
| 影響を受けるユーザー | All / Most / Some / Few |
| 頻度 | Every time / Often / Sometimes / Rarely |
| 回避方法 | None / <回避方法の説明> |
| データへの影響 | Data loss / Data corruption / No data impact |
| 収益への影響 | <該当する場合> |

## 関連イシュー

- <関連するバグ、PR、またはアーキテクチャの決定へのリンクまたは参照>

## 追加コンテキスト

<その他の有用な情報:最近の変更、過去の類似バグ、関連する設定、ユーザーレポートなど。>

必要な情報チェックリスト

提出前に、以下のフィールドが入力されていることを確認します:

フィールド	必須	理由
説明的なタイトル	Yes	「ログインが壊れた」は実行可能ではありません。「パスワードに特殊文字が含まれている場合にログインが500エラーで失敗する」の方が実行可能です
環境詳細	Yes	バグは環境に依存することが多いです。これがないと、開発者は「私の環境では動作している」に時間を無駄にします
再現手順	Yes	最も重要なセクションです。これがないと、開発者は修正を検証できません
予想される動作	Yes	バグが誤解なのか、実際の欠陥なのかを明確にします
実際の動作	Yes	具体的である必要があります:エラーメッセージ、不正な値。「動作しない」だけではダメです
重大度	Yes	優先順位付けを導きます。直感ではなくマトリックスを使用します
エラー出力	利用可能な場合	スタックトレースとエラーメッセージは調査時間を劇的に短縮します
二分探索ヒント	既知の場合	調査範囲を「コードベース全体」から「先週の変更」に狭めます

必須フィールドが不足している場合は、レポートを完成させる前にユーザーに要求してください。

タイトルガイドライン

良いバグタイトルは以下に答えます:何が壊れているのかとどのような状態で。

悪いタイトル	良いタイトル
ログインが壊れた	パスワードに特殊文字が含まれている場合にログインが500を返す
ページが遅い	ダッシュボードが1000以上のアイテムで30秒かかってロードする
保存時にエラー	タイトルが255文字を超える場合、ドキュメント保存がサイレントで失敗する
UIの問題	ドロップダウンメニューがモバイルビューポートで送信ボタンと重なる
動作しない	日付範囲が90日を超える場合、CSVエクスポートが空のファイルを生成する

アンチパターン

• 「動作しない」 — 具体的な症状のないバグレポートは実行可能ではありません。具体的に何が動作しないのか?どのエラーが表示される?どのデータが影響を受ける?曖昧な説明は、修正を遅延させる往復応答につながります。
• 再現手順がない — 「クリックしていたら壊れた」は開発者に推測を強います。既知の開始状態からの番号付きの具体的な手順は必須です。バグを再現できない場合は、明示的にそう述べ、それが観察された状況を説明します。
• 重大度が間違っている — ズレたボタンはCriticalではありません。データ損失バグはLowではありません。重大度マトリックスを一貫して使用します。カテゴリー分けが誤ると、軽微な問題でパニックが起きるか、実際の緊急事態への対応が遅れます。
• 環境情報がない — OS、ブラウザ、バージョン、設定の詳細がなく「私のマシンで壊れた」はデバッグ時間を無駄にします。環境に固有のバグは一般的であり、開発者がそれを再現するにはこの情報が必要です。
• 複数のバグが1つのレポートに混在 — 各バグレポートは正確に1つの欠陥を説明すべき。2つのものが壊れている場合は、2つのレポートをファイルしてください。統合されたレポートは追跡が難しく、割り当てが難しく、解決済みとしてマークするのが難しいです。
• 説明ではなく責任を押し付ける — 「バックエンドチームがログインを壊した」はバグレポートではありません。責任を割り当てることなく、観察可能な動作を説明してください。根本原因の分析はファイル時ではなく調査中に行われます。
• 利用可能な場合に二分探索ヒントがない — ユーザーが先週は動作していて火曜日のデプロイ後に壊れたことを知っている場合、その情報は極めて貴重です。常に「これが最後に動作したのはいつ?」と尋ねてください。調査を数日から数時間に狭めることができます。
• コンテキストなしのスクリーンショット — エラーメッセージのスクリーンショットは有用です。ユーザーが何をしていたか、または何を期待していたかの説明がないスクリーンショットではありません。常に視覚的な証拠をテキストの説明とペアにしてください。