AIエージェントにUIを実装させるとき、テキストだけで意図を伝えるのは難しい。DrawIOでワイヤーフレームを描き、それを設計の Single Source of Truth にしたところ、人間のイメージとAIの出力のズレが大幅に減り、開発速度が上がった。
はじめに
AIコーディングエージェントの進化により、「要件を伝えればコードが出てくる」時代が現実になりつつある。ロジック部分は比較的うまくいく。しかし UI の実装 となると、途端に認識のズレが発生する。
「サイドバーの右にメール一覧を配置して、選択したメールの詳細を右ペインに表示して」——この一文から人間が思い描くレイアウトと、AIが生成するレイアウトは、驚くほど一致しない。
この記事では、個人プロジェクト SmartAM（AI ネイティブなデスクトップメーラー）の開発を通じて見つけた、DrawIO ワイヤーフレームをハブにした AI エージェント駆動 UI 開発 のアプローチを紹介する。
課題：テキストだけでUIを伝える限界
AIエージェントにUIを作らせるとき、典型的にはこうなる：
- テキストで要件を書く（「3カラムレイアウトで…」）
- AIがコードを生成する
- 実行してみると 思ってたのと違う
- 修正指示を出す（「もっと左寄せにして…」「ここにボタンを追加して…」）
- 2-4 を何度も繰り返す
この繰り返しが発生する根本原因は、人間の頭の中にある視覚的なイメージを、テキストだけでは正確に伝えられない ことにある。UIを相手に伝える、また理解することには、開発者とAIの双方に課題が存在する。
開発者側の課題： デザイナーでない限り、デザインを言語化するボキャブラリーが少ない。頭に思い描いたレイアウト、色彩、質感、アニメーションを正確に言語化することは難しい。
AI側の課題： AIはあくまで言語モデルであり、実際にデザインを視覚しているわけではない。たとえ同じ画像を読み込んだとしても、人間と言語モデルでは情報を受け取るフォーマットや、咀嚼するメカニズムが異なる。
具体的には、以下のような情報がテキストだけでは伝わりにくい：
- レイアウトの曖昧さ: 「サイドバー」の幅は？「メイン領域」の比率は？
- 要素の関係性: どのボタンがどのパネルに属するのか
- 状態の表現: モーダルが開いたとき、背景はどうなるのか
- 画面遷移: 設定画面のタブ構成は？各タブに何があるのか
テキストベースの要件定義書だけでは、これらを網羅的かつ正確に伝えるのは困難だ。
アプローチ：DrawIO を「共通言語」にする
解決策はシンプルだった。DrawIO でワイヤーフレームを描き、それをプロジェクトに含める。
SmartAM では screens.drawio という 24 ページのワイヤーフレームを作成し、全画面・全状態を設計した。これにより、UIについてAIと共通認識を構築する作業が劇的に楽になる。
なぜ DrawIO なのか
-
テキストベース（XML）:
.drawioファイルは XML なので Git 管理できる -
AIが読める: AIエージェントは
.drawioの XML を解析し、画面構成を正確に理解できる - 人間も読める: GUI エディタで視覚的に確認・編集できる
- ページ機能: 1ファイルで複数画面を管理できる
プロジェクト構成
SmartAM/
├── screens.drawio # UIワイヤーフレーム（24ページ）← 視覚的な設計
├── ai-native-mailer.md # 要件定義書 ← テキストベースの設計
├── CLAUDE.md # AIアシスタント向けコンテキスト
└── app/
├── src/ # フロントエンド（SvelteKit）
└── src-tauri/src/ # バックエンド（Rust/Tauri v2）
ポイントは、テキストの要件定義書 と 視覚的なワイヤーフレーム の両方を用意し、「何を作るか」と「どう見えるか」を分離したこと。
実践ワークフロー
実際の開発フローは以下の通り：
1. 要件定義書を書く
このプログラムが何をするのかを言語化する。ワイヤーフレームだけでは伝わらない情報をテキストで定義する：
- 各機能の振る舞い（「ボタンを押したらAPIを呼び、結果をパネルに表示」）
- データフロー（「メール一覧はIMAPから取得し、ローカルにキャッシュ」）
- 技術スタック（「フロントエンドは SvelteKit、バックエンドは Rust/Tauri v2」）
2. 設計書を書く
要件を実現するための機能を設計する。ここで、どんな画面に、どんなボタンが必要なのかを決める。
3. DrawIO でワイヤーフレームを描く
設計書をもとに、全画面・全状態のワイヤーフレームを DrawIO で作成する。Figma のような高精度なデザインは不要。重要なのは：
- 画面のレイアウト構成（カラム分割、ヘッダー/フッター）
- UI要素の配置と種類（ボタン、リスト、入力欄）
- 画面間の遷移関係
- 各状態のバリエーション（モーダル表示時、ローディング時など）
ワイヤーフレームレベルで十分。色やフォントサイズは後から調整できる。
4. AIエージェントに読ませてMVP実装
AIエージェントへの指示は極めてシンプルになる：
「screens.drawio の Page 5 のレイアウトを実装して。詳細は ai-native-mailer.md のメール詳細画面セクションを参照。」
AIは DrawIO の XML からレイアウト構造を読み取り、要件定義書から振る舞いを理解し、コードを生成する。
5. MVPを触りながら微調整
生成されたUIを実際に触り、ワイヤーフレームとのズレや使い勝手の問題を見つける。微調整時には、まず DrawIO を人間が編集し、レイアウト変更の共通認識を作ってから コードに反映させる。
ワイヤーフレームという「正解」があるので、修正指示も具体的になる：
「ワイヤーフレームではAIパネルはメール詳細の下に配置されているが、生成されたコードでは右に配置されている。修正して。」
なぜ効果的だったのか
1. 認識のすり合わせコストが激減
テキストだけの場合、「サイドバー」「メインエリア」「詳細パネル」といった言葉の解釈が人間とAIで異なることがある。ワイヤーフレームがあれば、同じ図を見て話しているので、解釈のブレがなくなる。
また、DrawIO 内で画面番号を振ることで、「〇〇をしている画面」などの抽象的な表現ではなく、「画面2を調整したから確認して」のように、コミュニケーションを省力化できる。
2. 画面の「全体像」を共有できる
テキストで画面を説明すると、どうしても部分的な記述になる。ワイヤーフレームなら、画面全体の構成が一目で分かる。AIは全体のコンテキストを把握した上で、個々のコンポーネントを実装できる。
これはレビュー時にも有効で、全画面のデータを DrawIO として持つことで、全体の整合性レビューが容易になる。「画面1に追加したボタンがあるので、画面9にもこの設定項目がないとおかしい」といった、場当たり的な実装で生まれる不整合を発見しやすい。
3. 状態遷移を明示できる
UIには多くの状態がある。SmartAM の場合：
- メール未選択時 / 選択時
- AI処理中（ローディング）/ 完了時
- 設定画面の各タブ
- メール作成モーダル（新規 / 返信 / 転送）
これらを DrawIO の別ページとして用意しておくことで、AIは各状態のUIを正確に実装できた。
4. イテレーションが速い
ワイヤーフレームの修正は、コードの修正より圧倒的に速い。UIの方向性を DrawIO 上で固めてからコードに落とすことで、手戻りが減る。
Tips
ワイヤーフレームは「構造」に集中する
色、フォント、アイコンの詳細は後回しでいい。AIエージェントに伝えるべきは レイアウト構造 と 要素の配置 。見た目（アニメーションなど）の調整はコード上で行う方が効率的。
1ページ1状態を徹底する
「メール一覧画面」と「メール詳細画面」を1ページに詰め込まない。状態ごとにページを分けることで、AIへの指示が明確になる。
AIアシスタント向けのコンテキストファイルを用意する
SmartAM では CLAUDE.md というファイルに、プロジェクト構造・コーディング規約・設計方針をまとめた。AIエージェントが最初に読むファイルとして機能し、ワイヤーフレームや要件定義書の読み方のガイドにもなる。
DrawIO のレビューもAIに任せる
ワイヤーフレームと実装コードの整合性チェックもAIエージェントに依頼できる。「screens.drawio の Page 3 と現在の実装を比較して、差分を報告して」のような指示が有効。
まとめ
AIエージェントとのUI開発で最も難しいのは、人間の頭の中にある視覚的なイメージを正確に伝えること だ。
DrawIO ワイヤーフレームをプロジェクトに含め、設計の Single Source of Truth として運用することで、この課題を大幅に軽減できた。
人間のイメージ → DrawIO ワイヤーフレーム → AIエージェントの理解 → コード
この流れを作ることで、テキストだけでは埋められなかった認識のギャップが埋まり、開発のイテレーション速度が上がった。
AIコーディングエージェントの能力が上がるほど、「何を作るか」を正確に伝える技術の重要性も増す。DrawIO のようなシンプルなツールが、その橋渡しとして驚くほど効果的に機能する。
宣伝
この記事で題材にした SmartAM は、AI をネイティブに統合したデスクトップメールクライアントです。
メールの要約、返信文の自動生成、翻訳、カレンダー登録をワンクリックで実行できます。AI はボタンを押した時だけ動作するので、トークンを無駄に消費しません。
- 📬 Gmail OAuth 2.0 認証 / 複数アカウント対応
- 🤖 要約・返信下書き・翻訳・カレンダー登録を AI でワンクリック対応
- ⌨ 便利なキーボードショートカット
- 🎨 Ollama / OpenAI / Anthropic / Gemini / AWS Bedrock 対応
技術スタックは SvelteKit + Rust（Tauri v2）。DrawIO ワイヤーフレーム駆動で開発しました。
興味があればぜひ触ってみてください。Star いただけると励みになります ⭐