開発者が本当に読むバグレポートのテンプレート
コピーして使えるバグレポートのテンプレート、各項目の役割、そして曖昧な苦情を開発者が直せるチケットに変える習慣。
ソフトウェアチームの時間を、本来以上に奪っている2つの言葉があります。1つ目は「自分の環境では動きます」。2つ目は「もう少し詳しく教えてもらえますか?」です。
どちらの言葉も、何かが抜け落ちたバグレポートから生まれます。報告者には問題がはっきり見えていました。開発者には見えないので、チケットは止まったままになり、報告者は別の仕事に移り、答えが届くころには細かいことを覚えている人はほとんどいません。
解決策は、レポートを長くすることではありません。必要な項目がそろい、ざっと目を通せる形になっていることです。ここでは、テンプレートと各項目の役割、そしてそれを機能させるためのいくつかの習慣を紹介します。
そのまま貼り付けられるテンプレート
トラッカーの説明欄や、チームで共有しているテンプレートにコピーしてください。
``` タイトル:[対象領域] 何がおかしいかを短く
再現手順
- 開始地点(ページ、画面、コマンド)
- 行う操作
- 次に行う操作
- 問題が起きる手順
期待結果 本来どうなるべきだったか。
実際の結果 代わりに何が起きたか。表示されたメッセージも含める。
環境 バージョンまたはビルド、プラットフォーム、ブラウザまたは OS、 アカウントの種類、発生頻度。
エビデンス ログの抜粋、スクリーンショット、リクエスト ID、または短い録画。
重大度と理由 どの程度深刻か、誰に影響するか。
関連 似ているチケットや、同じ領域に関わるチケット。 ```
まるで記入フォームのようですが、それこそが狙いです。この形のチケットを開いた開発者は、1語も読まないうちに、それぞれの答えがどこにあるかがわかります。
各項目が必要な理由
タイトルは症状であって、推測ではありません。 「プロモーションコード適用後、チェックアウトの合計に年払いプランが反映されない」なら、トリアージ担当者はどこを見ればよいかがすぐにわかります。「料金のバグ」では何もわかりません。先頭に [Checkout] のようなタグを付けると、長い一覧をざっと見たり、同じまとまりに属するチケットを仕分けたりしやすくなります。
手順には番号を振り、初めての人でもたどり着ける場所から始めます。 プロモーションコードやプランなど、実際に使った値を書いてください。バグは特定の入力を好むからです。そして、多くの人が飛ばすことをしましょう。登録する前に、自分の手順をもう一度実行するのです。バグが再現しなければそう書き、それまでどのくらいの頻度で起きたかを説明します。その正直さのおかげで、開発者は午後を丸ごと無駄にせずに済みます。
期待結果と実際の結果があれば、議論は早く決着します。 期待結果がなければ、開発者はあなたが何を望んでいたかを推測するしかありません。実際の結果がなければ、あなたが何を見たかを推測するしかありません。短い2行で、2つの推測がなくなります。
環境は、開発者が最初に抱く疑問に答えます。 これはどのビルドだったのか。バージョンがわかれば、手元のコードにまだその問題があるかどうかを判断できます。プラットフォームと、動作を変えうるアカウント設定を書き添え、発生頻度も伝えてください。毎回起きる問題と、ときどき起きる問題とでは、調査の進め方が変わります。
説明よりもエビデンスです。 エラー行とその前後の数行に絞ったログは、何段落もの説明より価値があります。スクリーンショットには、どこにいるかがわかるだけの範囲を写してください。何かを添付する前に、メールアドレスやアクセストークンなどの個人情報や秘密情報がないか確認し、取り除きます。
重大度には理由が必要です。 「高」だけでは単なる意見です。「高:有料のお客様に誤った合計金額が表示される」と書けば、チームはそのチケットをキューにある他のすべてのチケットと比べて順位を付けられます。
記入例
実際の形にすると、テンプレートはこうなります。
``` タイトル:[Checkout] 年払いに切り替えた後、SAVE20 が月額料金に適用される
再現手順
- Pro プランをカートに追加する(月払い)
- 請求期間を年払いに切り替える
- プロモーションコード SAVE20 を適用する
- 注文概要を確認する
期待結果 年額料金から 20% 引き。
実際の結果 月額料金から 20% 引きした金額が、年額の合計として表示される。
環境 本番環境、Web、ビルド 2.14.1、毎回発生。
エビデンス TypeError: plan.period is undefined at applyPromo (pricing.ts:88)
重大度と理由 高:有料のお客様に誤った合計金額が表示される。 ```
開発者が最初の1分でこれをどう使えるかに注目してください。対象の領域がわかり、手順をたどれ、エラー行がファイルを指し示しています。追加の質問は必要ありません。
レポートを役立つものに保つ習慣
完璧なテンプレートよりも、小さな習慣のほうが大切です。
- 1つのチケットに1つのバグ。 1つのレポートに2つの問題があると、修正されるタイミングが別々になります。分けて登録し、互いにリンクしてください。
- 登録する前に検索する。 同じ問題がすでに報告されているかもしれません。そのチケットにあなたのエビデンスを追加すれば、経緯が1か所にまとまります。
- 試したことを書く。 再読み込み、別のブラウザ、別のアカウントで結果が変わるなら、それは1行書く価値のある手がかりです。
- 淡々とした書き方を保つ。 レポートは不満をぶつける場所ではありません。感情より事実を書いたほうが、早く修正されます。
- わかったことがあればチケットを更新する。 新しいビルド番号や、より絞り込んだ手順は、1日後でも価値があります。
BugIt の出番
この形で書くことに反対する人はいませんが、長い1日の終わりに実行するのは大変です。BugIt はそのすき間を埋めます。BugIt は、すでにお使いのアシスタントの中で動く QA エージェントです。何が壊れたかを大まかな一文で伝えると、チームの言い回しでレポートを書きます。タイトル、手順、期待結果と実際の結果、重大度、そしてあなたが渡したエビデンスです。一般的な個人情報はマスクしますが、これはベストエフォートなので、下書きが外に出る前に読んでください。下書きはすべて登録前にあなたが確認し、FILE IT と入力するまで、トラッカーには何も書き込まれません。
仕組みは bugit.dev で、製品の詳細は taskivator.com/bugit でご覧いただけます。
まとめ
良いバグレポートは、開発者が尋ねる前にその疑問に答えます。どこで、どうやって、何を期待し、何が起き、どのビルドで、どのくらい深刻なのか。テンプレートを使い、手順を一度確認し、絞り込んだエビデンスを添付し、重大度に理由を付けてください。数分の手間が、より早い修正となって返ってきます。