AI アシスタントが正確に診断できるように、bug をどのように説明しますか？

Question

Accepted Answer

AI への良い bug report は、人間への良い bug report と同じです。**問題を頭の中で再現できるだけの context** を与え、noise を削ります。AI は貼られた情報だけで推論するため、曖昧な説明は曖昧な推測になります。

## 含めるべきもの

- **正確な error message と完全な stack trace** — 言い換えず、そのままコピーします。trace 内の file と line は最も有用な手がかりです。
- **関連する code** — 例外を投げる function と直近の caller。repo 全体ではありません。
- **Expected vs actual behavior** — 「X を期待したが Y になる」が bug report の核です。
- **Repro steps** — 問題を起こす正確な input や sequence。
- **Environment/versions** — language、framework、library version。bug は version-specific な場合があります。
- **DB schema または sample data** — query や data shape に関係する bug の場合。

## 省くべきもの

無関係な file、config 全体、secret/API key、診断を偏らせる「X が原因かもしれない」という推測。hunch ではなく fact を渡します。

## 弱い report と強い report

```text
❌ WEAK: "My login is broken, it throws an error. Why?"
   → error text なし、code なし、repro なし → AI は推測しかできない

✅ STRONG:
   Error (verbatim):
     TypeError: Cannot read properties of undefined (reading 'id')
       at getUser (auth.js:42)
   Code (auth.js:40-43):
```

```js
function getUser(token) {
  const session = sessions.find(s => s.token === token); // 見つからない場合 undefined を返す
  return session.user.id; // line 42: session が undefined だと crash する
}
```

```text
   Expected: unknown token では null を返す。
   Actual:   上記 TypeError を投げる。
   Repro:    getUser('expired-token') を呼ぶ。
   Env:      Node 20, no framework.
```

強い version では、AI は missing `undefined` check を直接指摘し、guard を提案できます。必要な fact がすべて page 上にあるからです。

## なぜ重要なのか

AI assistant は**実行中の system に access できません**。あなたが提供した情報だけで推論します。弱い report は error、code、environment を同時に推測させるため、間違った推測で round-trip を浪費します。強い report（exact trace + relevant code + expected/actual + repro + versions）は診断を focused task に変え、多くの場合 1 回で正しい fix に到達します。簡潔な bug report を書く練習は、自分自身の debugging も向上させます。質問前に fact を isolate する必要があるからです。