バグ報告の書き方|開発者がすぐ動ける 10 のポイント
修正につながるバグ報告の書き方。具体的なタイトル、正確な再現手順、期待される結果と実際の結果、環境情報、証拠のそろえ方を解説します。
開発者がすぐ対応できるバグ報告を書くには、まず問題を再現し、それから具体的な 1 行のタイトル、環境(URL、ブラウザとバージョン、OS、アカウント)、既知の開始地点からの番号付きの再現手順、期待される結果、正確なエラーメッセージを含む実際の結果を書き、スクリーンショットや録画、コンソールのエラー、失敗したネットワークリクエストなどの証拠を添付します。1 つのレポートには 1 つのバグだけを書きます。
良いレポートかどうかの判断基準はシンプルです。その問題を一度も見たことがない開発者が、あなたに何も聞かずに、自分のマシンで問題を起こせるでしょうか。答えがイエスなら、そのバグはおそらくすぐに直ります。開発者が質問を返さなければならないなら、やり取りのたびに 1 日が失われます。項目をチェックリストとして使いたい場合は、バグ報告テンプレートをコピーしてください。
1. 書く前に再現する
バグをもう一度起こしてみましょう。その際、関係がありそうな細部に注意を払います。
- どのアカウントやロールを使っていたか。
- どんなデータが関わっていたか。特定の商品、長い名前、空のリスト、大きなファイルなど。
- 本当に必要な手順はどれか。手順を 1 つずつ省いて、最短の経路を見つけましょう。
- 別のブラウザやシークレットウインドウでも起きるか。
毎回起きるなら、それで十分です。ときどきしか起きないなら、回数を数えましょう。「10 回中 4 回」のようにです。まったく再現できない場合でも報告し、そのことをはっきり書きましょう。
2. すでに報告されていないか確認する
エラーメッセージ、ページ名、いくつかのキーワードでトラッカーを検索します。該当するものがあれば、新しいチケットを作らずに、そこにあなたの情報を追加しましょう。あなたの環境、新たな発生条件、最新のビルドでもまだ起きているという事実などです。重複したチケットは情報を分散させ、トリアージの時間を無駄にします。
3. 具体的なタイトルを書く
トリアージのときに読まれるのは、タイトルだけということもよくあります。機能名ではなく、問題を説明するタイトルにしましょう。
| 弱いタイトル | 改善したタイトル |
|---|---|
| ログインが壊れている | Safari で Google ログインするとログインページに戻ってループする |
| レポートのバグ | 売上レポートの CSV エクスポートで 1,000 行目以降が欠ける |
| ページが遅い | 請求書が多いアカウントで請求ページの読み込みに 10 秒以上かかる |
| 保存時にエラー | 名前に絵文字を含むプロフィールを保存すると「Invalid input」が返る |
便利な型は、何が壊れているか+いつ起きるか+どこで起きるか、です。
4. 環境を書く
多くのバグは、特定の環境でしか現れません。次の情報を含めましょう。
- 問題が起きたページの URL。
- ブラウザとバージョン。たとえば Chrome、Firefox、Safari、Edge と、「バージョン情報」ページに表示されるバージョン番号。
- OS とデバイス。
- レイアウトの問題なら 画面サイズ。
- アプリに表示されていれば アプリのバージョンやビルド。
- アカウント、ロール、テストユーザーと、その特徴(トライアルアカウント、大規模な組織、英語以外の言語設定など)。
- チームがサーバーログで見つけられるよう、タイムゾーン付きの発生時刻。
5. 再現手順を書く
手順はレポートの核です。良い手順とは次のようなものです。
- 既知の状態から始める:「管理者としてサインインし、ダッシュボードを開いている状態」。
- 番号付きの 1 つの手順には 1 つの操作だけを書く。
- 正確なデータを明記する:商品、ファイル、入力したテキスト。本物のパスワードやカード番号は絶対に含めず、テストデータを使う。
- 開発者が同じボタンを見つけられるよう、アプリに表示されているラベルを太字かかぎかっこで書く。
- バグが現れた時点で終わる。
1. [email protected](管理者ロール)でサインインする。
2. 「Settings」、「Team」の順に移動する。
3. 「Invite member」をクリックする。
4. 「[email protected]」と入力し、ロール「Viewer」を選ぶ。
5. 「Send invite」をクリックする。
6. 期待される結果と実際の結果を書く
2 つを並べて書きます。
期待:招待が保留中(Pending)の一覧に表示され、確認のトーストが表示される。
実際:ダイアログが閉じるが、トーストは表示されず、Pending の一覧は空のまま。
再読み込みしても招待は表示されない。
原因と思われることではなく、観察したことを書きましょう。「招待のリクエストが失敗した」は結論で、「ダイアログが閉じ、一覧には何も表示されなかった」は観察です。エラーメッセージが表示されたら、テキストのまま正確にコピーしましょう。開発者はその文字列でコードを検索します。
7. 証拠を添付する
証拠は説明を裏付けに変え、多くの場合、原因を直接指し示してくれます。
- スクリーンショット。問題の箇所を強調し、関係のない個人データはトリミングで取り除きます。
- 画面録画。動き、タイミング、複数の手順が関わるものに使います。短くまとめ、問題が起きる直前から始めましょう。
- コンソールのエラー。Web アプリでは、ブラウザのコンソールに出る赤いエラーが最も役に立つ手がかりであることがよくあります。「Chrome でコンソールログをエクスポートする方法」をご覧ください。
- 失敗したネットワークリクエスト。失敗した API 呼び出しの URL、ステータスコード、レスポンスボディです。「Chrome でネットワーク通信をキャプチャする方法」をご覧ください。
- チームからネットワークのセッション全体を求められたら HAR ファイル。「HAR ファイルを取得する方法」に従い、先に HAR サニタイザーできれいにしてください。HAR ファイルには Cookie やトークンが含まれるからです。
8. 影響を正直に評価する
どれほど深刻で、何人に影響するかを書きましょう。チームに重大度の基準があれば、それを使います。正直に評価してください。すべてが「致命的」なら、何も致命的でないのと同じです。回避策を見つけたら書いておきましょう。修正の緊急度が変わり、それまでの間サポートの助けにもなります。
9. 1 つのレポートに 1 つのバグ
同じページで 3 つの問題を見つけたら、レポートを 3 つ書きましょう。そうすれば、それぞれを個別に割り当て、修正、テスト、クローズできます。関連がありそうなら、互いにリンクしておきます。
10. 連絡がつくようにしておく
送信したあとは、チケットに質問が来ていないか見ておきましょう。修正がリリースされたら、同じ手順で再テストして確認します。あとでバグが再発したら、元のチケットを再オープンするかリンクして、経緯を 1 か所にまとめておきましょう。
よくあるミス
- 「動かない」「ページの問題」のようなあいまいなタイトル。
- 手順の抜け、またはフローの途中から始まる手順。
- エラーメッセージをテキストではなくスクリーンショットで添付すること。検索できません。
- 1 つのチケットに複数のバグ。
- レポートに含まれる本物の機密情報:スクリーンショットやログに写ったパスワード、API キー、セッション Cookie、顧客データ。
- 感情的な言葉づかい。冷静で事実に基づいたレポートのほうが、怒ったレポートより早く直ります。
良いレポートと悪いレポートを並べて比べたい場合は、バグ報告の例をご覧ください。
書く量を減らし、記録する量を増やす
バグ報告の手間の大部分は技術的な詳細にかかり、報告者が書き忘れるのもその部分です。無料の Chrome 拡張機能 Midge は、画面を録画するかスクリーンショットを撮り、そうした詳細を代わりに添付するので、あなたが書くのはタイトル、手順、期待していた結果だけです。すべての録画に、コンソールログ、ネットワークリクエスト、ユーザー操作、デバイス情報が含まれます。パスワード、カード番号、トークン、Cookie は、デバイスから送信される前にブラウザ内で伏せられます。レポートは 1 つのリンクとして共有され、チームが使っているどのトラッカーにも貼り付けられます。
関連ガイド
よくある質問
バグ報告で最も重要な部分はどこですか?
再現手順、期待される結果、実際の結果です。この 3 つがあれば、たいていの開発者は問題を自分で確認できます。環境の情報や、スクリーンショット、コンソールのエラーなどの証拠があれば、さらに早くなります。
バグ報告はどれくらいの長さにすべきですか?
必要な情報をそろえたうえで、できるだけ短くしましょう。良いレポートの多くは 1 画面に収まります。1 行のタイトル、短い概要、5〜10 個の手順、期待される結果と実際の結果、そして添付ファイルです。
バグを再現できない場合はどうすればいいですか?
それでも報告し、再現できなかったことを書きましょう。何をしていたか、いつ起きたかを正確に説明し、スクリーンショットやコンソールのエラーなど、手元にある証拠を添付します。発生頻度は「1 回だけ発生」としておきます。
原因についての自分の考えも書くべきですか?
観察と推測は分けて書きましょう。主な項目には見たことを書き、仮説がある場合は、推測であることを明記してメモ欄に加えます。