不具合詳細を書かない技術

CC BY 4.0

👤私が書いていたのは、画面が知っていることでした

不具合の報告は、書くのに時間がかかります。どのURLか。どの曲か。何をクリックしたか。コンソールに何が出ていたか。画面の大きさはいくつか。👤私が書き終えて🤖AIに渡すと、🤖AIから足りない項目を聞き返され、👤私はまた画面を開いて確かめます。

書きながら👤私が気づいたのは、報告に書く項目の大半を、画面から書き写しているということでした。URLはアドレスバーに、エラーはコンソールに出ています。画面の見た目は、目の前に映っています。👤私が知っていて画面が知らないのは、「何が変だと思ったか」という症状の一文だけです。

📖あなたが、🤖AIに不具合を直させようとして、どの画面で何をしたら何が出たかを書いて渡したとします。書くのに時間がかかったうえ、🤖AIからは、どのURLか、コンソールに何が出ていたかを聞き返されました。📖あなたは画面を開き直して確かめ、書き足しました。次に不具合を伝えるとき、📖あなたなら次のどちらにしますか。

• 聞き返されないように、URL、エラーの文言、画面の大きさまで、漏れなく書いてから渡す
• 不具合が出た画面からフォームで送り、URLとエラーとスクリーンショットはフォームに集めさせて、自分が書くのは症状の一文だけにする

答えは、フォームで送るほうです。聞き返されたURLもコンソールの中身も、📖あなたが確かめに開き直した画面に出ていました。📖あなたが書いていたのは、画面に出ているものの書き写しです。漏れなく書けば、聞き返される項目は減っても、書き写す項目が増えるぶん、書くのにかかる時間が長くなるだけです。フォームに集めさせれば、画面に出ているものは、📖あなたが書き写さなくても報告に入り、📖あなたが書くのは、画面が知らない、何が変だと思ったかの一文だけになります。

👤私の手元には、typingtube という本番プロジェクトがあります。YouTube の音楽動画でタイピング練習ができる Web サービスです。そこには、ユーザー向けの不具合報告のフォームがあります。ある日から、👤私は、自分で見つけた不具合も、そのフォームから送るようになりました。運営者用に別の入口を作る代わりに、ユーザーと同じ画面から、同じフォームで送ります。

理解したことは一文にできます。

不具合の詳細の大半は、人が書き写す前から、その場の画面が知っている。だから人が書くのは症状の一文だけにして、残りはフォームに集めさせ、そのまま🤖AIに貼る。

仕組み: 人が書くのは、症状の一文だけにする

👤私が置くのは、フォーム 1 つです。

// app/javascript/controllers/feedback_controller.js（手元のコードを短くしたもの）
const payload = {
  category: this.categoryValue,                                  // 選ぶだけ（不具合 / 要望 / 歌詞の間違い）
  comment:  this.commentTarget.value,                            // ← 症状の一文。人が書くのは、ここだけ
  page_url: window.location.pathname + window.location.search,  // どこで（画面が知っている）
  screenshot_data: includeScreenshot ? this._screenshotData : null,          // 画面そのもの（html2canvas）
  console_logs:    includeConsoleLogs ? getErrorLog().slice(-20) : [],       // 直近 20 件。スタックトレース込み
  screen_resolution: `${window.screen.width}x${window.screen.height}`
}

サーバー側は、これに送信日時と環境の情報を足します。人が書くのは症状の一文だけで、ほかに人がするのは、カテゴリを選ぶことと、スクリーンショットとコンソールログを添えるかどうかの、チェック 2 つです。

届いた報告は、1 件ごとに管理画面の 1 ページに一式で並びます。並ぶのは、不具合が出たページのURL、カテゴリ、環境、スクリーンショット、コンソールログ、そして症状の一文です。👤私がやるのは、その管理画面のページを開いて中身を全部コピーし、🤖AIに貼ることだけです。👤私が貼った時点で、画面が知っていることは、👤私が書き写さなくても一式に入っています。

フォームが集めているのは、事実だけです。原因の🧬推測開いていないファイルを開いたかのように話すことと直し方は、一式を受け取った🤖AIが、コードを読んで決めます。

CC BY 4.0 はここまで

CC BY 4.0

注意: フォームが無いところでは、詳細を書くのは今も👤私です

一つ、👤私がフォームを置いているのは、不具合と要望の経路だけです。新機能の設計のように、フォームが無いところでは、詳細を書くのは今も👤私です。

そして、そのフォームを作るには手間がかかります。保存する列を決め、送信をサーバーにつなぎ、管理画面に一覧を作り、報告ごとに対応の状態を持たせる必要があります。書くのをやめるのは、そのフォームを作ったあとです。

二つ、フォームが集めるのは、送った時点の画面と、それまでに溜まったエラーの直近 20 件です。どの画面で何をクリックしてきたかは、集めません。別の画面から始まる再現手順や、時間が経ってから出る症状は、フォームが集める範囲の外にあります。そういう不具合では、👤私が症状の一文にそのことを書きます。それでも、報告に付くURLとコンソールログとスクリーンショットは、いつもと同じです。

三つ、コンソールログには、ページで出たエラーが、スタックトレースごと入ります。スタックトレースは長いので、1 件で送る量が膨らみます。👤私の手元の上限は、ログ 1 件あたり 2,000 字、1 回の送信あたり 20 件です。この上限で、クライアントは送る前に、サーバーは受け取ったあとに、それぞれログを切ります。

検証手順: フォームが集めた一式を点検する

前提

不具合報告のフォームと、届いた報告を開く管理画面を置いておきます。手元で再現することのできる不具合を 1 つと、新しいセッション（🤖AIとの、始まりから終わりまで一続きのやり取り）を 1 つ用意します。

所要時間: 10 分

手順

1. 📖あなたが、不具合の出る画面で、その不具合を起こします
2. 📖あなたが、同じ画面のフォームから、症状の一文だけを書き、スクリーンショットとコンソールログのチェックを入れて送ります
3. 📖あなたが、管理画面で届いた報告を開き、ページのURL・環境・スクリーンショット・コンソールログ・症状の一文の 5 つを見ます
4. 📖あなたが、その一式をそのままコピーし、新しいセッションの🤖AIに貼ります。何も書き足しません

合格条件

手順 3 で、5 つの欄がすべて埋まっていて、コンソールログに手順 1 で出たエラーが入っていることを確かめます。手順 4 では、🤖AIが、項目を聞き返さずに原因の調査を始めれば合格です。

合格しなかったとき

• 空の欄があった —— フォームがその項目を集めていません。その欄を集める処理を疑う
• 🤖AIが項目を聞き返した —— 聞き返された項目は、フォームが集めていないものです。フォームに足す列の候補です

後始末

検証で送った報告を、管理画面で対応済みにします。

CC BY 4.0 はここまで