AIが文章指示を実際の機能と画面に変える仕組み

書かれた指示から構築するとはどういうことか

「書かれた指示」とは、あなたが作ってほしいことを説明するために既に使っている言葉—AI（とチーム）が実行できる形で書かれたものです。

実務では、完璧な文章が目的ではありません。重要なのは明確な意図（何を達成したいか）と明確な境界（何が許されるか／許されないか）です。こうしておけばシステムが推測する必要が減ります。

「書かれた指示」に該当するもの

形式は問いません。例：

• メモやメッセージ：「確認メールを再送するボタンを追加して」
• ユーザーストーリー：「顧客として、配送先住所を保存してチェックアウトを速くしたい」
• 受け入れ基準：「ログイン済みで『保存』を押すと、住所が一覧に追加され既定として使われる」
• エッジケースと制約：「私書箱は許可しない」「モバイルで動作すること」「データはGDPR準拠のリージョンに保存する」

重要なのはテキストが成果と制約を記述していることです。両方あれば、AIはビジネスルールを勝手に作らずにスクリーン、フロー、実装の詳細を提案できます。

「動作する機能と画面」が意味するもの

動作する機能はモック以上のものです。通常含まれるのは：

• UI画面：レイアウト、フォームフィールド、ボタン、エラー状態
• ナビゲーションとフロー：ユーザーがどこから始め、次にどこへ行くか、成功・失敗時の挙動
• ロジックとルール：バリデーション、権限、計算、ステータス変更
• データ：何を保存し、取得し、更新するか（いつ行うか）

例として「保存された住所」は単なるページではなく、一覧・追加/編集といった複数画面、必須項目・既定住所などのルール、API呼び出しや状態更新の配線を含みます。

AI支援のビルドループ

多くのチームはシンプルなサイクルに落ち着きます：

記述 → 生成 → レビュー → 改善

あなたが仕様を記述すると、AIがUI/UXと実装を提案し、あなたは正確性やプロダクトとしての適合性をレビューして、結果が意図したものになるまで仕様を洗練します。

Koder.aiのようなvibe-codingプラットフォームを使うと、このループはさらに短くなります。チャットで機能を説明してアプリ変更を生成し、ターゲットを絞ったフォローアップで素早く反復し、必要ならロールバックもできます。

期待値の設定

AIは画面のドラフト、フローの提案、コード生成を加速できますが、人がやることは依然として残ります：

• プロダクト上の意思決定とトレードオフの判断
• 要件に対する正確性の検証
• 実際の挙動のテスト（特にエッジケース）
• 品質、安全性、既存プロダクトとの整合性の担保

AIはテキストを最初（と二回目）のドラフトに変える加速装置です。最終結果の責任は人間が負います。

AIが使える入力（と何が明確さを生むか）

AIはフォーマットに寛容ですが、明確さには厳格です。1段落、箇条書き、PRDの抜粋、または一連のユーザーストーリーからでも動作しますが、意図と制約が明示されている必要があります。

良い入力（「原料」）

最も有用な出発点は通常次の要素を含みます：

• ユーザーストーリー：誰が何をなぜ必要とするか（例：「ストアマネージャーとして、返金を承認したい。損失をコントロールするため」）
• ターゲット：内部チーム、課金ユーザー、管理者、初回ユーザーなど
• 制約：モバイル優先、ダークモード対応、オフライン対応、既存のデザインシステム準拠、パフォーマンス制限
• 成功基準：完了をどう測るか（例：「返金承認は30秒以内で行われ、監査エントリが記録される」）

これらはAIに何を作るかと「良い」の基準を伝え、やり取りを減らします。

AIに推測させないための重要な詳細

要件が欠けていると、AIはデフォルトで補完しますが、それが事業ルールに合わないことがあります。以下は明示するべきです：

• 役割と権限：誰が表示・作成・編集・削除・承認できるか
• データフィールド：保存する情報、バリデーション、必須か任意か
• ステートと遷移：draft → submitted → approved → rejected のような遷移と、誰が移行できるか
• エッジケース：重複、空状態、ネットワーク遅延、部分的データ、エラー処理

曖昧 vs 具体例

曖昧：「チェックアウト画面を追加してシンプルにして」

具体：「ログイン済みユーザー向けのチェックアウトフローを追加。ステップ：住所 → 配送 → 支払い → 確認。カード + Apple Pay をサポート。ユーザーは最大3件の住所を保存可能。支払い前に税と送料を表示。支払い失敗時はカートを保持し再試行オプションを表示。成功条件：注文作成、領収メール送信、在庫を減算。」

詳細化が手戻りとサプライズを減らす理由

明確な入力はAIにスクリーン、文言、バリデーション、ロジックを実務的な制約に沿って生成させます。その結果、想定と異なる前提が減り、設計変更の回数が減り、初案から実際にレビュー・テスト・出荷できるプロダクトに至る時間が短くなります。

ステップ1：意図と要件を理解する

AIが画面やコードを生成する前に、あなたの意味するところを把握する必要があります。これはプロダクトマネージャーが仕様を読むように、目標、関係者、正しい機能にするためのルールを抽出するプロセスです。

AIが平文から意図を抽出する方法

多くの仕様は次の共通要素を含みます：

• ゴール：成功が何か（例：「サインアップでの離脱を減らす」）
• アクター：操作する人（例：「ゲストユーザー」「管理者」「チームメンバー」）
• アクション：「作成」「編集」「承認」「エクスポート」など
• オブジェクト：アクションの対象（例：「アカウント」「請求書」「プロジェクト」「コメント」）
• ルール：「メールはユニークであること」「管理者は投稿を削除できる」など

これらが明確なら、AIは文章を構造化された理解に翻訳できます。後続のステップでフロー、画面、データ、ロジックに変換されます。

フレーズをプロダクト概念にマッピングする

AIは一般的なプロダクトパターンを認識し、日常的な言い回しを実装要素にマップします。例：

• 「アカウント作成」は一般に認証フロー（サインアップフォーム、メール確認、パスワードリセット）を意味します。
• 「ダッシュボード」は概して概要画面（指標の要約、最近のアクティビティ、ショートカット）を示唆します。
• 「チームに招待」は役割/権限と招待システムを想起させます。

このマッピングにより、曖昧な名詞をデザイナーやエンジニアが使う具体的なビルディングブロックに変換できます。

欠落情報を見つけ、適切な質問をする

良い仕様でもギャップは残ります。AIは不足を指摘し、次のような確認質問を提案できます：

• 「どの役割が存在し、各役割は何にアクセスできますか？」
• 「ユーザーが既にアカウントを持っている場合はどうなりますか？」
• 「どのフィールドが必須で、バリデーションはどうしますか？」

不確定な場合のデフォルト扱い（と明示的な仮定）

回答が得られないまま進めたい場合、AIは妥当なデフォルト（標準的なパスワードルールやよくあるダッシュボードウィジェットなど）を選べます。ただし仮定は明示してレビュー用に一覧にするべきです。仮定が可視化されていれば、人が確認・修正してからリリースできます。

ステップ2：テキストを機能計画に変える

意図が明確になったら、次は書かれた仕様を実際に作れる形—つまり「機能計画」に落とし込みます。まだコードを求める段階ではなく、構造を作る段階です。

要件を画面とジャーニーにマッピングする

良い計画は文章を画面、ナビゲーション、ユーザージャーニーに翻訳することから始まります。

例：「ユーザーがアイテムをウィッシュリストに保存して後で見る」は通常、(1) 商品詳細の操作、(2) ウィッシュリスト画面、(3) メインナビからの到達手段を意味します。

AIに画面を列挙させ、ハッピーパスと一般的な迂回（未ログイン、アイテムが削除された、空のリスト）を説明させてください。

作業をビルド可能なタスクに分解する

次にAIに機能をタスクに分割させます：

• UIコンポーネント（ボタン、フォーム、空状態、読み込み状態）
• APIエンドポイント（例：作成/削除/一覧）
• バリデーションとルール（制限、必須フィールド、権限）
• エッジケース（重複、オフライン、競合）

ここで仕様の曖昧さが露出します。例えば「同じアイテムを二度保存する場合」を仕様が言及していなければ、計画の段階でその質問が浮上します。

受け入れ基準（完了の定義）を定義する

受け入れ基準はわかりやすい言葉で書いてください。例：

• ログイン済みユーザーが「保存」をタップすると2秒以内にウィッシュリストに表示される。
• ログアウト時はサインインを促し、同じアイテムに戻る。
• ウィッシュリストが空のときはブラウズに戻るリンクを表示する空状態を示す。

スコープを管理する

AIに項目を必須とあると良いにラベル付けさせてください（例：「ウィッシュリストを共有する」はあると良い）。これにより仕様が知らず知らずに拡大するのを防げます。

ステップ3：画面、レイアウト、UXフローを生成する

機能計画が整ったら、AIはテキストから具体的な「画面マップ」と初期のUIドラフトを作成できます。初回でピクセルパーフェクトを目指す必要はなく、共通認識を作るための検査可能なモデルを目標にします。

画面一覧とユーザーフローを草案化する

まずハッピーパスを短い物語として描写します：ユーザーは何を求め、どこから始め、何をタップし、成功はどう見えるか。そこからAIは最小限の画面セット（各画面に何が必要か）を提案できます。

次に一般的な代替パスも求めてください：「未ログインなら？」「結果がないなら？」「途中でやめたら？」といった質問です。これによりデモだけで動くUIを避けられます。

説明からワイヤーフレームやUIドラフトを生成する

説明にレイアウトのヒント（例：「ヘッダーに検索、結果リストにフィルタ、主要CTAは下部」）が含まれるなら、AIは次のような構造化ドラフトを出せます：

• ワイヤーフレームのアウトライン（セクションと階層）
• コンポーネントの提案（カード、テーブル、タブ、モーダル）
• サンプル文言（ボタンラベル、補助テキスト、空状態メッセージ）

良いプロンプトはコンテンツ優先度（例：「価格と在庫を説明より上に表示」）、インタラクションルール（例：「フィルタはセッションを跨いで保持」）、制約（例：「モバイル優先；片手操作を想定」）を含みます。

重要なUI状態を設計する（仕様が曖昧になりやすい箇所）

動くプロダクトには「通常時」以上の設計が必要です。AIに実装する状態を列挙・定義させてください：

• 読み込み：スケルトンかスピナーか、何がクリック可能か
• 空状態：表示するメッセージと次のアクション
• エラー：フレンドリーな文言、リトライ挙動、フォールバック
• 成功：確認、次のステップ、トースト表示かリダイレクトか
• 権限：いつ要求し、拒否されたらどうするか

これらの状態決定は開発工数とユーザー信頼に直接影響します。

シンプルなデザインシステムで一貫性を保つ

AIは再利用可能なコンポーネントとルール（タイプスケール、間隔トークン、ボタンスタイル、フォームパターン）を提案して一貫性を強制できます。

既にコンポーネントがある場合は内部ガイド（例：/design-system）にリンクしてAIにそれを再利用させ、新しいパターンを勝手に作らないようにしてください。

ステップ4：機能をデータとルールに翻訳する

次に「アプリが何をするか」を「アプリが何を保存するか」と「何を許容するか」に翻訳します。ここで仕様は具体的なデータモデルとビジネスルールになります。

主要なエンティティを特定する

AIはまず文章中の“名詞”を抽出し、それらをエンティティとして扱います。例：「ユーザーはプロジェクトを作成しタスクを追加でき、マネージャーが工数を承認する」は User, Project, Task, TimeEntry のようなエンティティを示唆します。

フィールド、関係、制約を提案する

各エンティティについてAIは必要なフィールドを提案し（欠けている箇所を指摘します）：

• フィールド：名前、ステータス、日付、金額、メモ、添付
• リレーション：Project は多くの Task を持つ、Task は Project に属する、User は多くの Project を所有する
• 制約：必須/任意、ユニーク性（例：email）、フォーマット（ISO日付）、許容値（例：status = Draft/In Review/Approved）

また暗黙のエッジケース（例：「アクティブなサブスクリプションはアカウントにつき1つのみ」）や計算検証（例：「注文合計は明細の合計に等しい」）なども指摘させてください。

ビジネスルールとバリデーションを平易な言葉で定義する

良い出力はルールを読みやすく保持します。例：

• 「タスクは担当者が割り当てられていないと完了にできない」
• 「返金は支払日から30日以内に許可（注文が争われている場合を除く）」
• 「マネージャーは自分が監督するプロジェクトの工数のみ承認できる」

データのライフサイクルを計画する

最後にレコードが時間経過でどう変わるかをマップします：作成、更新、削除、そして削除の代わりにソフトデリートを行うか。AIは監査トレイル（誰がいつ何を変更したか）や履歴/バージョン管理が必要かも提案できます。

ステップ5：UIとロジックのコードを生成する

ここで「最初の動作するドラフト」のコードを生成できます：ユーザーがクリックするUIと、それを正しく振る舞わせるロジックです。

Koder.aiを使っている場合、通常はチャット駆動の仕様からフルスタックの実装（Web、バックエンド、DB）を生成し、必要ならソースコードをエクスポートして従来のワークフローに移行できます。

フロントエンド：コンポーネント、フォーム、ルーティング、状態

「名前、オーナー、可視性を持つ『プロジェクト作成』画面を追加する」のような仕様から、AIはスキャフォールドできます：

• ページコンポーネント（レイアウト、見出し、補助テキスト）
• バリデーションルールを持つフォーム（必須フィールド、文字数制限）
• ルーティング（例：/projects/new）とナビゲーションリンク
• 状態管理（読み込み、成功、エラー、送信不可）

再利用可能なビルディングブロック（例：Create と Edit で共有する <ProjectForm />）も生成してコードの一貫性を保てます。

バックエンド：エンドポイント、サービス、権限チェック

サーバー側ではAIが機能に対する基本的な「契約」を下書きします：

• エンドポイント（POST /api/projects、GET /api/projects/:id）
• ビジネスルールを適用するサービスメソッド（例：ワークスペース内でのユニーク名）
• 権限チェック（誰が作成でき、誰が編集できるか）

重要なのはUIが送るものをそのまま保存するのではなく、仕様のルールに結びついたバックエンドロジックを作ることです。

UIとデータの接続：API呼び出し、キャッシュ、エラー

AIはUIを既存のAPIクライアント（fetch/Axios/React Query など）に接続し、適切なキャッシュとリトライも組み込みます。フィールドレベルのバリデーションエラーやネットワーク障害に対するユーザーフレンドリーなエラーハンドリングも生成すべきです。

// Example: submit handler with loading + error state
async function onSubmit(values) {
  setStatus({ loading: true, error: null });
  try {
    await api.post('/api/projects', values);
    router.push('/projects');
  } catch (e) {
    setStatus({ loading: false, error: 'Could not create project. Try again.' });
  }
}

（上のコードブロックはそのまま保持してください）

コードを保守しやすくする

生成されたコードが有用なのは既存の規約に従うときです：命名が明確、フォルダ構成が予測可能、小さな関数、共有ユーティリティ（バリデータ、APIクライアント、権限ヘルパー）を使うこと。

スタイルガイドや好みのパターンがある場合は明示的に参照し、/engineering/frontend や /engineering/api-guidelines などの内部ドキュメントをリンクしてください。

ステップ6：すべてを繋いで動く機能にする

この時点で画面、UIコンポーネント、データ形、ビジネスルールがあります。"繋ぐ"作業はこれらを実際に連携させることです：ボタンがアクションを起こし、アクションがバックエンドを呼び、レスポンスがUIを更新し、権限が見えるものを決定します。

ナビゲーション：画面を到達可能にする

AIは仕様に従って画面をルート（URLやアプリパス）で接続したり、主要アクション後の遷移を定義したり、ページ間で適切なコンテキストを渡すことができます。

例：「保存後に一覧へ戻り新規アイテムをハイライトする」は具体的なフローになります—フォーム送信→成功を待つ→一覧へ遷移→トースト表示と新しい行にフォーカス。

認証、役割、アクセス制御

仕様にはしばしば「Adminは編集できる、Viewerは読み取りのみ」といった記述があります。これを実装するには複数箇所で強制する必要があります：

• UIルール：できない操作を隠すか無効化する
• APIルール：権限を満たさないリクエストは拒否する
• データスコーピング：見せられる項目だけを返す

AIは一貫したチェックをアプリ全体に生成できるため、「見た目はロックされているがエンドポイントは動く」といった不整合のリスクを減らせます。

環境設定とシークレットの漏洩防止

多くの機能は設定（APIベースURL、分析キー、機能フラグ、ストレージバケット）に依存します。AIはdev/staging/prod向けに別の設定を準備しつつ、シークレットをコードベースに含めないようにできます。

典型的な出力例：

• .envテンプレート（安全なプレースホルダ）
• 環境変数を読むコンフィグローダ
• デプロイ時に設定すべき項目の明記（コミット禁止のもの）

E2E挙動の検証

目標は「クリック → リクエスト → レスポンス → UI更新」のフルループです。AIは不足している接着コード（読み込み状態、エラーハンドリング、リトライ）や簡単なチェック（「Saveをクリックしたら期待するペイロードが送信される」「成功でUIとキャッシュが更新される」「エラーはユーザーに分かる表示になる」）を生成できます。

ここで機能はモックから実際に振る舞うプロダクトへと変わります。

ステップ7：AI支援によるテストとデバッグ

機能が「動く」ようになったら、実際のユーザー（と現実の混乱）と同じやり方でテストします。AIは受け入れ基準から具体的なチェックケースを作り、デバッグの単純作業を高速化します。

受け入れ基準から直接テストを生成する

仕様に「ユーザーはパスワードをリセットでき、確認メッセージを見る」とあるなら、AIはその文言にマッチするテストケースを複数レベルで提案できます：

• ユニットテスト：小さなルールを検証（パスワード長、トークン有効期限）
• 統合テスト：システム間のやり取りを確認（リセットメールリクエストでデータベースにトークンが作られる）
• UIチェック：挙動を確認（成功トーストが表示され、ボタンは送信中に無効化される）

コツはAIに正確な受け入れ基準と最小限の文脈（機能名、主要画面、既存のテスト慣行）を与えることです。

ユーザーより先にエッジケースを洗い出す

仕様は通常ハッピーパスを説明します。AIはサポートチケットにつながる「もしも」のシナリオをブレインストーミングするのに役立ちます：

• 無効入力：空フィールド、特殊文字、非常に長いテキスト、過去日付
• 遅い/不安定なネットワーク：リトライ、タイムアウト、二重送信、オフライン対応
• 競合更新：複数タブ、複数管理者の同時編集、古いキャッシュデータ

すべてをすぐに実装する必要はありませんが、プロダクトのリスクレベルに応じてどれを優先するか決めるべきです。

AIを使った障害解析の高速化

テストが失敗したら、開発者が通常確認するもの（失敗アサーション、関連ログ、スタックトレース、再現手順）をAIに渡してください。AIは：

• 可能性の高い原因を推測（レースコンディション、モックデータ不足、タイムゾーン問題）
• 疑わしいコード経路を指摘
• 最小限の修正案と再発防止のための追加テストを提案

ただしAIの提案は仮説として扱い、テストの再実行とUIでの挙動確認で確かめてください。

非技術的レビュワー向けの簡単なQAチェックリスト

短いレビューサイクル用にチェックリストを用意してください：

1. 主タスクをエンドツーエンドで完了できるか？
2. エラーメッセージは次に何をすべきか説明しているか？
3. 遅い回線で合理的に動くか（重複やデータ消失がないか）？
4. 権限は正しく見えるか（誰が何を見れる/編集できるか）？
5. リフレッシュや別デバイスで結果が保持されるか？

ステップ8：初稿から本番準備までの反復

AI生成の初稿は「反応できる」程度であり「出荷準備ができている」ことは稀です。反復では仕様を厳密にし、エッジケースを補い、小さなレビュー可能な変更で信頼性を高めます。

フィードバックループ（プロンプト、差分、ターゲット変更）の仕組み

良いループは：生成 → レビュー → 特定の変更依頼 → 何が変わったか比較 → 繰り返し、です。

全アプリを再プロンプトするのではなく、ターゲットを絞った更新を目指してください。AIに1つの部分（画面、コンポーネント、バリデーション、クエリ）だけを修正させ、差分や明示的な「前/後」を返してもらうとよいです。これにより他を壊していないか確認しやすくなります。

ワークフローが許すなら、小さなコミットにして同僚のプルリクと同様に差分をスキャンし、アプリを実行して挙動を検証してください。

Koder.aiのようなプラットフォームでは、まず計画モードでスコープとフローに合意し、その後狭いスライスで生成→反復し、スナップショット/ロールバックを活用すると安全です。

変更依頼の最適な方法

曖昧な依頼（「もっと良くして」や「フローを直して」）は曖昧な結果を生みます。強い変更依頼は次を含みます：

• 画面：「Checkout → Payment screen」
• 状態：「カード拒否時」や「カートが空の時」
• 期待挙動：「インラインエラーを表示し、同じ画面に留まりフォーム値を保持する」

可能なら受け入れ基準を付けてください：「必要なフィールドが有効になるまで『支払う』ボタンは無効」「配送国が変わったら税を即時再計算」など。

バージョニングとレビュー：何が変わったか、なぜ変えたか

AIの出力はあなたが所有するコードです。更新時には何が変わったか、なぜ変えたか、何をテストするべきかを短く添えさせてください。

AIがリファクタを勧める場合は意図の説明と潜在的リスク（例：「検証タイミングが変わる」「APIレスポンス処理が変わる」）を求めてください。

反復をやめる判断

反復を終える基準を明確にします：

• スコープ：このリリースで含めるもの／後回しにするもの
• 品質基準：主要フローが検証済み、エラー状態がカバーされている、必要なイベントが計測されている
• 安定性：重大な既知バグなしで改善による効果がもはや僅少

この時点で仕様を凍結し出荷し、次の反復を新しいスコープの変更として計画します。

制限、セーフティ、ベストプラクティス

AIは書かれた仕様を驚くほど完全な機能に変えられますが、判断の代替にはなりません。特にユーザーデータ、決済、権限に関わる部分は人間が必ずレビューしてください。

プライバシーと扱ってはいけない機密データ

プロンプトに貼り付けたものは保存・レビューされる可能性があると仮定してください。以下は含めないでください：

• APIキー、プライベートトークン、パスワード、.envのシークレット
• 実際の顧客データ（メール、住所、電話番号）、サポートチケット、チャットのやり取り
• 共有不可の社外秘コード、内部財務データ、法的文書

現実味が必要なら匿名化してください：名前をプレースホルダに置換、IDをスクランブルし、パターン（"1万人、3つの役割"）で説明する等。

AIが補助できるセキュリティの基本

AIはベースラインのセキュリティチェック生成に有用ですが、必ず検証してください：

• 入力検証：必須フィールド、フォーマット、サーバー側チェック（UIだけに頼らない）
• 認可チェック：各リソースに誰が何をできるかを明示し、すべてのエンドポイントで強制する
• 最小権限：役割は最初は最小で始め、必要に応じて権限を付与する。AIに役割ごとのパーミッション一覧を作らせ、アクションにマップさせてください。

注意すべき一般的な制限

• 幻覚するAPI：AIは存在しないエンドポイントやSDKメソッド、DBテーブルを言及することがある。実際のスタックと突合してください。
• 一貫性のない要件：文言の微妙な違いが矛盾を生む（例：「管理者は全て編集できる」 vs 「オーナーのみ」）。真の単一ソースを持つこと。
• デザインのブレ：画面間でUIが変わる。デザインシステム（間隔、色、コンポーネント）を固定し、プロンプトで再度明示してください。

より良いプロンプトと安全な結果のための実用チェックリスト

プロンプトを投げる前に含めるべき項目：

1. ゴールと非ゴール（成功基準）
2. ユーザーロールと権限
3. データモデル：主要エンティティ＋必須フィールド
4. エッジケース（空状態、エラー、読み込み）
5. 制約：技術スタック、ルーティング、スタイリング、アクセシビリティ要件
6. 受け入れ基準：テスト可能な「完了」定義

次のステップ

ドラフトプロトタイプができたら素早くレビューをスケジュールしてください：ロードマップと比較し、今出荷するものと後回しにするものを決め、変更を文書化します。

ドラフトをプランに変える手助けが必要なら /pricing を確認するか、関連記事を /blog で参照してください。チャット駆動開発を試す場合は、Koder.aiがこのワークフロー向けに設計されています：書かれた仕様を動くWeb/バックエンド/モバイル機能に変え、素早く反復し、準備ができたらソースコードをエクスポートできます。