本文へスキップ

バグ報告の書き方|開発者がすぐ動ける 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 回だけ発生」としておきます。

原因についての自分の考えも書くべきですか?

観察と推測は分けて書きましょう。主な項目には見たことを書き、仮説がある場合は、推測であることを明記してメモ欄に加えます。