AIとデザインの認識合わせ — スコープのズレはどこで生まれるか

背景

verify-ai の UI を bdiff に寄せる作業をしていた。テストは414件全パス、実装も完了した。しかしブラウザで確認すると、入力フォームの Source と Target が縦に並んだまま。さじを投げた。

なぜそうなったのか、何をすべきだったのかを振り返る。

何が起きていたか

層	状態
テスト（414件）	全パス（CSSクラス名の存在チェック）
実装（結果カード）	完成（3カラムグリッド正しく実装）
実装（入力フォーム）	未変更（別コンポーネント・スコープ外）
ブラウザ確認	失敗（Source/Targetが縦に並ぶ）

食い違いが起きた瞬間

「配置を寄せて」＋スクリーンショット添付、というユーザーの指示に対して、AI は bdiff の DiffPage（結果表示）を参照し、Issue を「結果カードの3カラムグリッド」に絞って作成した。

AI はスクリーンショットの「結果カード部分」だけを拾い、入力フォームを視野から落とした。ユーザーはそのスコープ定義を承認した。この時点で運命が決まっていた。

なぜ AI はそう解釈したか

参照先が src/pages/DiffPage.tsx だったため、「DiffPage = 結果表示ページ」として読んだ。入力フォームは DiffPage の概念に含まれない。

ユーザーの頭の中にあった「画面全体」を、AI は「参照コンポーネントのスコープ」に自動的に縮小した。

ユーザーが伝えるべきだったこと

A. ギャップ分析を先にさせる

「実装前に、現在の verify-ai の各画面と bdiff の対応画面を
 並べて、何が違うか全部洗い出して」

AI に実装させる前に差分リストを作らせる。そこで CompareForm が漏れていれば気づける。

B. 「全体」を明示する

「入力フォーム・比較ボタン・結果表示、すべてを含めて
 bdiff に寄せて。スコープはページ全体」

C. スクリーンショットを2枚渡す

• bdiff の入力画面
• bdiff の結果画面

1枚だと AI は「そこだけ」と判断する。

構造的な教訓

「参考URLを見せる」だけでは AI は参照先の構造に引きずられる。ユーザーの意図（全体的な体験）と AI の解釈（コンポーネント単位の実装）は自然にズレる。

「何を変えるか」ではなく「どこまで変えるか」を最初に合意する。

具体的には:

1. 実装の前に洗い出しフェーズを挟む — 「まず差分を列挙して、承認してから実装して」
2. スコープを画面単位ではなくユーザー体験単位で定義する — 「比較を完了するまでの全操作を bdiff に寄せる」
3. 参照先を複数渡す — 入力画面と結果画面、両方のスクリーンショットを渡す