はじめに
受託開発のPMをやっていると、本番不具合の調査と顧客向け報告書づくりがしょっちゅう発生します。
「これ、AIに『原因はこれです』まで出してもらえたら最高じゃん」と思うじゃないですか。僕もそう思ってました。
でも、不具合チケットをそのままAIに貼って「原因教えて」だけだと、AIが気持ちよく"それっぽい嘘"を返してきます。浅いし、たまに間違ってるし、何より顧客に出せない。
色々試した結論はこれでした。
AIに"型"を渡すと、AIは勝手に暴走せず、正しい順番で真因まで連れて行ってくれる。
今回は、その型（不具合調査を9フェーズに分けたワークフロー）を渡したときに、AIが実際どう動くかを、ある不具合を例に紹介します。
最後にGitHubで全部公開しているので、コピペで使えます。
関連記事もよければどうぞ🙇
まず、AIに「丸投げ」すると何が起きるか
「不具合のチケット貼るから原因教えて」——このプロンプト、ラクなんですが、型がないとAIはこう暴走します。
| 丸投げAIの暴走 | 実際に起きること |
|---|---|
| 文脈ゼロで即断する | 誰向けの報告書かもどのファイルを読むべきかも聞かず、いきなり原因を断定 |
| 現場報告を鵜呑みにする | 「〇〇環境固有のバグです」をそのまま信じ、根本原因を見逃す |
| file/line まで降りない | 「この辺が怪しいです」止まりで、エンジニアが結局直せない |
| 自己レビューしない | エッジケースを潰さず「直りました！」→ 再発 |
| 顧客語に翻訳しない | "race condition" を顧客資料にそのまま書いて、会議が止まる |
つまり問題はAIの賢さではなく、手順がないこと。
なので、AIに「賢く考えて」ではなく 「この順番で、このゲートを越えてからでないと次に行くな」 という型を渡します。
（僕の根っこの考え方は 「品質ゲートは仕組みとして機能させる。人間の注意力に頼らない」 です）
解決策：型を渡すと、AIは「勝手に正しい手順で」動く
スキルの中身はシンプルで、調査を9フェーズに分け、各フェーズに**Exit Gate（これを満たすまで次に進めない）**を置いただけです。
| # | フェーズ | やること | 次に進む条件（Exit Gate） |
|---|---|---|---|
| 1 | 前提確認 | 誰向け/トーン/関係者/既存分析を確認 | 5項目すべて明示的に回答された |
| 2 | 事実確認 | チケット内容・再現手順・再現率を確定 | チケット原文が貼られ、必須項目が埋まった |
| 3 | 既存分析レビュー | 現場・協力会社の結論を検証する | 既存分析を全部見た or「ない」と明言された |
| 4 | ファイル分類 | 関連ファイルをTier1/2/3に仕分け | 実際のファイル一覧を受領（推測しない） |
| 5 | 反復調査 | コードを追って真因に降りる | file + 行番号で1文で原因を言い切れる |
| 6 | 真因確定 + 自己レビュー | シニアエンジニア目線で粗探し | チェックリストを実行し、指摘を分類した |
| 7 | 想定Q&A | 顧客が聞きそうな質問に先回り | 10項目を具体的な回答つきで用意 |
| 8 | 方針合意 | 選択肢を出して意思決定 | どの案で行くか明示的に決まった |
| 9 | HTMLレポート作成 | 顧客向け資料を生成 | 全セクションが中身入りで埋まった |
ポイントは、各フェーズで AIが自分から次の振る舞いをすること。具体的にはこう動きます。
| フェーズ | 型を渡したAIの振る舞い |
|---|---|
| 1〜2 | 「誰向け？」「トーンは？」「再現手順は？」を自分から確認してくる（いきなり原因を当てにいかない） |
| 3 | 現場の「〇〇のバグです」を鵜呑みにせず、まず裏取りする |
| 4〜5 | 関連ファイルをTier分けし、file + 行番号で原因を言い切れるまで降りる |
| 6 | 言われなくても自分の修正案の粗探し（自己レビュー）を始める |
| 7 | 顧客が聞きそうな質問に先回りして10個答えを用意する |
| 9 | 調査結果を顧客向けHTMLレポートに落とす |
「賢いAI」というより「手順を守るAI」です。そしてこの"手順を守る"が、実用品質には一番効きます。
では、本当にこう動くのか。実例でいきます。
実例：型を渡したAIは、実際どう動いたか
ここからは、ある不具合の調査で AIが実際にどう振る舞ったか を見ていきます。
（主役はバグではなく、AIの動きです。なお製品名・社名・関係者・実コードはすべて伏せ、技術現象だけを汎用化しています）
扱った不具合はこれ👇
2つの動画を並べて見比べる画面で、Chromebookだけ動画が"2回連続"で再生される。MacやWindowsのEdgeでも、ごくたまに出る。
数週間、複数人がかりで再現に苦戦していた。
① AIは、いきなり原因を当てにいかなかった
最初に僕がやったのは、AIに状況を渡すこと。
普通のAIなら即「原因はこれです」と言い出しそうなところですが、型を渡したAIはまず確認から入りました。「誰向けの報告書か」「使っているライブラリは何か」「既存の調査結果はあるか」。
原因の前に、土台を固めにきたわけです。地味ですが、ここを飛ばさないのが効きます。
② AIは、"僕の思い込み"を自分で棄却した ←ここが一番うれしかった
僕はこう仮説を立てていました。
「これ、Chromebook固有の、動画再生ライブラリ（HLS系）のバグでしょ。ライブラリ側の既知問題を探して」
普通のAIなら「ですね！探します！」と僕に同調しそうなところ。
でも型を渡したAIは、video.js / hls.js などのGitHub Issueを横断調査した上で、僕の仮説をはっきり否定してきました。
「"Chromebookで2回再生される"というドンピシャの既知バグは存在しません。Chromebook + HLSの既知問題は『再生されない/止まる/アスペクト比』系ばかりで、"2回再生"系は出てきません。あなたの予想とは違う見立てになります。」
発注者（＝僕）の思い込みを、AIが根拠つきで正してくれた。 これが本当に効きました。
もしAIが僕に同調して「環境固有のバグですね」で進めていたら、ライブラリ更新だけして再発、のループに入っていたはずです。
③ AIは、環境のせいにせず"普遍的な真因"まで降りた
仮説が崩れたあと、AIはコードを追って真因に降りました（file + 行番号つき）。犯人はもっと普遍的なやつでした。
ブラウザの HTMLMediaElement.play() は Chrome 50以降 Promiseを返す非同期処理で、その解決前に pause() / seek / load() を呼ぶと reject されます。
Uncaught (in promise) DOMException: The play() request was interrupted by a call to pause()
そしてコードには「再生に失敗したら1秒後にもう一度試す」リトライが、**誰にもキャンセルされない"孤児 setTimeout"**として仕込まれていました。
// ❌ 問題のパターン（簡略化したイメージ）
function tryPlayWithRetry(video) {
video.play().catch(() => {
// 失敗したら1秒後にもう一回試す
// …が、このタイマーは誰もキャンセルしない（孤児タイマー）
setTimeout(() => {
if (video.paused) video.play().catch(() => {})
}, 1000)
})
}
ユーザーが一時停止したあとや再生終了後にも、この孤児タイマーが生き残って幻の play()（phantom play）を撃つ → 2回再生。これが正体でした。
④ AIは、「なぜこの環境だけ？」まで説明した
ここがAIの説明で一番納得したところ。
「Chromebookはハードウェア（デコーダ）が非力なので、seek中に
play()がAbortErrorで弾かれやすい。だから"失敗→リトライ"経路に入りやすく、潜在バグが顕在化しているだけです。」
Chromebookは『原因』ではなく、もとからある競合バグを"あぶり出す"遅い環境だった。
「環境固有のバグ」だと思っていたものが、実は環境に炙り出されただけの潜在バグだった——この切り分けをAIがやってくれました。
⑤ AIは、過去の修正痕という"証拠"まで拾った
さらにAIは、該当ファイルに過去の修正コメントが2か所残っているのを見つけました。
同じ場所を2回直して再発している＝対症療法では止まらない構造的バグ、という何よりのサイン。file/lineまで降りたからこそ拾えた証拠です。
⑥ AIは、自分が書いたコードを「差し替えるな」と止めた ←信用できると思った瞬間
僕はエンジニアではなくPMなので、AIにこう聞きました。
「君が修正コード書いてくれたら、エンジニアはそれを差し替えるだけでよくない？」
普通なら「いいですよ！」と書き切ってきそうなところ。
でもAIの答えは 「やめた方がいい」 でした。理由は、(1) そのコードは実機で未検証、(2) 過去2回直し切れていない複雑な箇所、(3) 全相互作用を把握しきれていない。だから差し替えではなく、優先度つきの修正方針＋実機での検証手順をエンジニアに渡す形にすべき、と。
僕がずっと大事にしている原則そのままでした。
「AIの"出力"を検証するだけでは足りない。AIの"行動（プロセス）"を検証せよ。」
AI自身が「自分の出力を鵜呑みにするな」と言ってきた。ここで『こいつは信用していい』と思いました。
そして、顧客向けレポートもAIが作る（Phase 9）
調査が終わると、AIは最後に**1ファイルで完結するHTMLレポート（標準13ページ）を生成します。
以下は、GitHubで公開している匿名サンプル（例題：CSVエクスポートが1,000件で打ち切られる不具合）**の実物です。
表紙
原因を"図"で説明（AsIsシーケンス図） ——どこで何が起きているかを、文章ではなく図で示す。
修正後の姿も図で（ToBeシーケンス図）
顧客の想定質問に先回り（Q&A表） ——報告会で出る質問を、事前に潰しておく。
地味に効くのが用語集ページで、"Promise" や "競合状態（race condition）" を顧客向けの日本語に言い換えておくと、報告会で説明が止まりません。
※サンプルの例題を「CSVエクスポート」にしているのは、実案件の不具合をそのまま公開できないからです。技術現象だけを汎用例に置き換えて匿名化しています（この記事の動画バグの話も、同じ理由で製品名・社名・実ファイルを伏せています）。
Before / After
Before（AIに丸投げ・型なし）
- 「Chromebook固有のバグです」で調査が止まる
- 3回目のパッチでまた再発する
- 顧客に "race condition" をそのまま投げて、会議が止まる
After（AIに型を渡す）
- 発注者の思い込み（Chromebook固有のライブラリバグ）をAIが早期に棄却
- 真因（
play()Promise競合 ＋ 孤児setTimeout）までfile/line付きで到達 - 「なぜChromebookだけか」「過去の修正痕」まで説明
- 実機での検証手順つき
- 顧客にも読める用語集つきレポート
実際にやってみた結果
| フェーズ | 状況 |
|---|---|
| 従来（型なし） | 数週間、複数人がかりで再現に苦戦 |
| AIに型を渡す | 半日で真因の仮説 ＋ 修正方針 ＋ 実機検証手順まで到達 |
| 残した作業 | 実機での検証（＝エンジニアの仕事として明確に残す） |
「環境依存で誰も再現できない」と止まっていた案件が、AIに型を渡したら半日で見通しが立った。
しかも、検証という"人間がやるべき仕事"はちゃんと残してくれる。ここが一番よかったところです。
まとめ
| 項目 | 内容 |
|---|---|
| やりたかったこと | 不具合の原因特定〜顧客向け報告書を、AIに実用品質で任せたい |
| 落とし穴 | 丸投げするとAIは"それっぽい嘘"を返す（浅い／間違い／顧客に出せない） |
| 解決策 | 9フェーズ + Exit Gate の"型"を渡す |
| AIの効きどころ | ①発注者の思い込みを棄却 ②file/lineまで降りる ③自己レビュー ④顧客語に翻訳 ⑤自分の出力を過信しない |
| おまけの教訓 | 「環境固有のバグ」は、たいてい"あぶり出されただけ"の潜在バグ |
AIは、ちゃんと型を渡せば不具合の真因特定から顧客向けレポートまで任せられます。
ただし丸投げではダメで、「手順とゲート」を仕組みで持たせるのがコツです（品質ゲートは、人間の注意力ではなく仕組みで担保する）。
付録：GitHubで公開しています
スキル一式（ワークフロー本体 ＋ 参照ドキュメント ＋ HTMLレポートテンプレート）はGitHubで公開しています。
🔗 （https://github.com/enomoso-pm/bug-investigation-report）
使い方はシンプルで、AIに 「このスキルに従って、この不具合を調査して」 と渡すだけ。
ちゃんと作ってあると、AIはいきなり原因を当てにいかず、最初に「誰向け？」「トーンは？」「既存分析は？」を聞いてきます。この"立ち止まり"が肝です。
最後に、僕がAIに調査を頼むとき毎回最初に渡しているルールを置いておきます（PDF変換の記事と同じ、僕の口癖です）。
ここまで読んでいただきありがとうございました🙇
「AIに不具合を任せたいけど、丸投げだと不安」という方は、ぜひ**"型"から渡してみてください**。賢さより、手順です。