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

CC BY 4.0

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

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

書きながら気づいたのは、その大半を、私は画面から書き写していることでした。URL はアドレスバーに出ています。エラーはコンソールに出ています。画面はそこにあります。私が知っていて画面が知らないのは、「何が変だと思ったか」の一文だけです。

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

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

不具合の詳細は、人が思い出して書くものではなく、その場の画面が知っているものだ。だから書く代わりに、画面に集めさせて、そのまま貼る。

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

置くのはフォーム 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 件は、管理画面に一式で並びます。ページ URL、カテゴリ、環境、スクリーンショット、コンソールログ、そして症状の一文。私がやるのは、そのページを開いて、全部コピーして、AI に貼ることです。打つ言葉は要りません。貼った時点で、着手に要るものは揃っています。

⚠️ ここで集めているのは事実だけです。原因の推測も、直し方も、フォームには入っていません。それは貼られた AI が、コードを読んで決めます。

CC BY 4.0 はここまで

CC BY 4.0

注意: フォームが無いところでは、書くのは今も人です

一つ、フォームが無いなら、詳細を書くのは今も私です。 フォームがあるのは不具合と要望の経路だけで、新機能の設計にはありません。そしてそのフォームを作るのは安くありません。列を決め、送信を繋ぎ、一覧を作り、状態を持たせる。それをやらずに、書くのだけやめるのは、この回の話ではありません。

二つ、フォームが集めるのは、その画面で起きたことだけです。 別の画面から始まる手順、時間が経ってから出る症状は、フォームには載りません。そういう不具合は、症状の一文にそのことを書きます。それでも、URL とログとスクリーンショットは付いてきます。

三つ、コンソールログには、何でも入ります。 手元では 1 件 2,000 字、送信 20 件までに切っていて、クライアントとサーバーの両方で同じ上限を持たせています（呼び手を信用しない）。集める側を厚くするほど、出す側の線引きが要ります。

検証手順: 同じ不具合を、二通りで渡す

前提

• フォームは無くてもできます
• 手元で再現できる不具合が 1 つあること
• セッションを 2 つ立てられること

所要時間: 15 分

手順

1. 1 つ目のセッションに、あなたが、症状の一文だけを渡します——「タイピングでたまに変になる」。⚠️ URL も、エラーの文言も、画面の大きさも書かないでください
2. あなたが、聞き返された項目をそのまま書き出します。直しはまだ頼みません。この一覧が、この検証の成果物です
3. 2 つ目のセッションに、あなたが、同じ不具合を材料付きで渡します——ページの URL、コンソールのログ、スクリーンショットの 3 つです。症状の一文は 1 つ目と同じ文にします

合格条件

• 2 つ目のセッションの AI が、聞き返さずに原因の調査へ入る

合格しなかったとき

• 2 つ目でも聞き返された —— その項目は、3 つの材料に入っていません。手順 2 の一覧に足してください。それが、あなたのフォームが集めるべき列です

後始末

• 要りません。どちらのセッションにも、まだ直させていません

⚠️ 手順 2 で出てくるのは、たいてい URL・再現手順・環境です。それが、フォームが代わりに集めているものです。 フォームを作る前に、この 2 回の比較で列を決められます。

CC BY 4.0 はここまで