インテントからアプリへ：AIがUI・ステート・APIを構築するとき

インテント：すべてを始める一文

創業者が四半期末の慌ただしさの合間に背もたれにもたれ、言う：「フィールド担当者が訪問を素早く記録してフォローアップを設定できるようにして、管理業務を増やさないでほしい」。

その一文は本当のユーザープロブレムを含んでいます：メモが遅れて記録される（あるいはまったく記録されない）、フォローアップが抜け落ちる、そして収益が静かに失われる。

AI支援による構築の約束はここにあります：インテントから出発して、すべての画面やステート更新、API呼び出しを最初から手で結線することなく、動作するモバイルアプリにより速く到達できる。魔法でも完璧でもないが、アイデアから実際に電話で動かせるものを手に渡すまでの道のりが短くなる。

この節（と続く物語）は技術的チュートリアルではありません。何を言えば良いか、早めに何を決めるか、実際のユーザーでフローを試すまで何を開けておくか、という実務的な示唆のある物語です。

「インテント」が本当に意味するもの

平たく言えば、インテントはあなたが望む成果であり、特定の対象に対して、明確な制約の下にあるものです。

• 成果： ユーザーに何が変わるか？（「訪問が記録される」「フォローアップが完了する」）
• 対象： 具体的に誰のためか？（「フィールド担当者」——「営業」ではない）
• 制約： 何が成り立っていなければならないか？（「余計な管理業務を増やさない」、場合によっては「古い端末でも動く」「月額200ドルのツール予算に収まる」「監査対応の操作ログが必要」など）

良いインテントは機能一覧ではありません。「モバイルCRMを作って」というのではなく、人間とAIの双方に成功が何かを伝える一文です。

最終目標：出荷できるMVP

インテントが明確なら、クリックだけの画面以上のMVPを目指せます。目標は実際のフローと実データを持つ出荷可能なアプリです：ユーザーがサインインし、今日のアカウントを見て、訪問を記録し、メモや写真を添付し、次のステップを設定し、よくある例外に対処できる。

以降の要件、情報アーキテクチャ、UI、ステート、バックエンド統合、反復はすべてその一文に奉仕すべきです。

チームと制約を把握する

MayaはこのプロジェクトのPMであり偶発的創業者です。彼女はモバイルアプリを再発明しようとしているのではなく、四半期の締め切りが機会を消してしまう前に出荷しようとしています。

チームはカレンダー招待に収まる小規模：Maya、週に数時間割けるデザイナー1人、すでに二つのアプリを維持しているエンジニア1人。40ページの仕様を書いたり、フレームワークを延々と議論したり、1か月のワークショップをやる余裕はありません。しかし期待は現実的です：リーダーシップはデモではなく使えるものを望んでいます。

初日の実際の所持物

Mayaの出発点は控えめです：

• アプリの一段落の説明が書かれたスマホのメモ
• ミーティング中に描かれた3画面のラフスケッチ
• 必須機能の短いリスト：サインイン、一覧表示、詳細タップ、簡単な更新の送信

彼女のメモには重要な一文もあります：「ユーザーが電話で主要タスクを2分以内に終えられなければ、正しいものを作れていない」。

初回リリースでの「完了」とは

このMVPの「完了」は、1つのユーザージャーニーがエンドツーエンドで動くことです：

1. ユーザーがログインする。
2. 個人化された一覧を見る。
3. 1件を開く。
4. 1つのアクション（記録、確認、リクエスト、更新）を完了する。
5. 成功したことがフィードバックされる。

派手なダッシュボードは不要。隠れたメニューは不要。「後で磨く」画面でフローをブロックしないこと。

すべての選択を形づくる制約

アプリは既存のバックエンドに接続する必要があります——モバイル向けに設計されておらず、ドキュメントがまちまちなAPIです。予算は厳しいので、新しい画面はすべて正当化されねばなりません。

いくつかのガードレールは交渉不可です：監査ログ、必要な同意の明示、デバイスに機密データを無造作に保存しないこと。

ここに緊張があります：Mayaには良いアイデアが10個あり、作業日が10日あるかもしれない。選択肢を議論して過ごす時間は、コアのジャーニーをユーザーの手に届ける時間を奪います。

長い仕様無しでインテントを要件に落とす

目標は完璧な仕様を書くことではなく、テスト可能な明快さに速く到達することです——我々が解く問題、誰のためか、成功をどう知るか。

最初のAIとの対話：明確なインテントと測定可能な成果

あなたはまず一つの雑然とした文を持っています：

“I want an app that helps our field reps log visits and follow up.”

次にAIに練り直してもらいます：

Prompt: “Rewrite this as a problem statement and add 3 success metrics. Keep it short.”

AIの出力（編集済み）：

Problem statement: Field reps lose follow-ups because visit notes and next steps are captured late (or not at all), leading to missed revenue and inconsistent customer experience.

Success metrics:

• 80% of visits logged within 10 minutes
• 30% increase in follow-ups completed within 48 hours
• Reduction in ‘no next step’ visits from 40% to under 10%

これでチームが目指せるターゲットが得られ、単なる機能要求ではなくなります。

もしあなたが vibe-coding ワークフロー（例えば、チャットでプロダクトを記述し反復的に動くアプリを生成する Koder.ai のような）を使っているなら、この段階が多大な価値を生みます：明確なインテント＋指標が次に生成される全ての「真実のソース」になります。

役割、最重要タスク、ユーザーストーリー

次に役割とタスクを抽出します：

ユーザー役割：

• 主：フィールド担当者
• 従：セールスマネージャー
• 管理（軽度）：オプス

トップタスク：

• 主：訪問を記録、メモ／写真添付、次のステップ設定
• 従：チームの活動をレビュー、停滞アカウントを発見

それらを受け入れ基準付きのいくつかのユーザーストーリーに変えます：

• 担当者として、60秒以内に訪問を記録できるようにしたい。
  • 受け入れ基準：顧客選択、タイムスタンプ保存、メモ必須 OR 次のステップ必須。
• 担当者として、フォローアップを予定できるようにしたい。
  • 受け入れ基準：期限＋リマインダー；“Today”一覧に表示される。

範囲外にするもの（意図的に）

初回リリースを守るために：

• カスタムダッシュボードは無し
• 複雑なテリトリープランニングは無し
• 深いCRMへの書き戻しは無し（読み取りインポートのみ）

北極星フロー

すべての決定はひとつのフローに紐づけます：

アプリを開く → “Log Visit” → 顧客を選ぶ → メモ／写真を追加 → 次のステップ＋期限を選ぶ → 保存 → フォローアップが“Today”に表示される。

このフローをサポートしない要求は次のリリースまで待ちます。

AIがフローを情報アーキテクチャに変える

北極星フローが明確になれば、AIはそれを情報アーキテクチャ（IA）に翻訳できます。ワイヤーフレームや図に飛び込まずに誰でも読める形で提示されます。

3～7のコア画面から始める

多くのMVPでは、主要な仕事を完全にサポートする少数の画面が望ましい。AIは通常、次のような簡潔なリストを提案します（必要に応じて調整可能）：

• Welcome / onboarding（本当にセットアップが必要な場合のみ）
• Home（出発点、ゴミ置き場ではない）
• Search / browse（項目の見つけ方）
• Detail（意思決定の場）
• Create / log（コンバージョンステップ）
• Profile / settings（アカウント、設定）

そのリストが骨格になります。外側のものは後回しか二次フローです。

ナビゲーションを平文でマップする

抽象的なパターンを議論する代わりに、IAはナビゲーションを検証可能な文で明記します：

• 「ログイン後、ユーザーはHomeに着地する。」
• 「タブバーでHome、Search、Profileにアクセスできる。」
• 「詳細はスタックで開き、戻るで元の位置に戻る。」

オンボーディングがあるなら、どこから始まりどこで終わるか（「OnboardingはHomeで終わる」）を定義します。

各画面の階層と空状態を定義する

各画面に軽量のアウトラインを与えます：

• 主要コンテンツ（最上位に何があるか）
• 主要アクション（最も重要なボタン）
• 二次アクション（控えめなもの）
• 空状態（データがないときにユーザーが見るもの）と次にできること

空状態はアプリが壊れて見えるポイントなので意図的に設計します（例：「今日の訪問はまだ記録されていません」＋次にやるべきことを明示）。

権限やパーソナライゼーションがUIを変える場所

IAは条件付きビューを早めに示します：「マネージャーは追加タブを見る」「Opsだけがアカウント詳細を編集できる」など。これにより、権限とステート実装時の驚きを防げます。

レビュー可能な“フロードキュメント”

出力は通常、1ページのフローと画面ごとの箇条書きです——非技術系の利害関係者が迅速に承認できるもの：どの画面があるか、どう遷移するか、データがないときに何が起きるか。

UIが現れる：画面、コンポーネント、コピー草案

フローが合意されると、AIは各ステップを「画面契約」として扱い、ユーザーが見るべきもの、次にできること、収集・表示すべき情報を定義してファーストパスのワイヤーフレームを出します。

フローからワイヤーフレームへ

出力は粗く始まることが多い——グレースケールのブロックにラベル——しかしコンテンツニーズに沿った構造になっています。比較が必要なステップはグリッドやカードレイアウト、進行性が重要なら明確な主要アクションと軽量のサマリが提示されます。

コンポーネント選択はタスクに基づきます：

• 多数の項目を素早く閲覧するためにリスト（検索結果、履歴）
• メタデータ付きでスキャンしやすいカード（アカウント、訪問、フォローアップ）
• コミットの瞬間のためのフォーム（訪問の記録、フォローアップの予定）

AIはインテントの動詞（browse、choose、edit、confirm）に基づいてこれらの決定を出す傾向があります。

使いやすさを保つデザイン制約

この段階でも良いジェネレータは基本的な制約を適用します：

• アクセシビリティ基礎：タップターゲット、カラ―コントラスト、読みやすい文字サイズ
• プラットフォーム慣習：ナビゲーションパターン、戻る動作、ネイティブ入力コントロール
• 可読性：短い行長、明確な見出し、予測可能な余白

コピー草案もUIと並行して出ます。「Submit」ではなく「Save visit」や「Schedule follow-up」のように、ユーザーの仕事に即した文言に変わります。

人間によるレビューの瞬間

ここでプロダクトオーナー、デザイナー、マーケターが介入します——すべてを描き直すのではなく、トーンと明確さを調整するために：

• マイクロコピーをブランドボイスに合わせる
• 曖昧さを取り除く（「Continue」→「Choose follow-up date」）
• 空状態やエラーメッセージを親切にする

終わりに得られるもの

単なる画像で終わりではありません。通常のハンドオフはクリック可能なプロトタイプ（タップして試せる画面）か、チームがビルドテストループで反復できる生成された画面コードです。

Koder.aiのような環境では、この段階は素早く具体化します：UIは動くアプリの一部として生成され（webはReact、バックエンドはGoとPostgreSQL、モバイルはFlutterなど）、実画面を一か所でレビューしつつフロードキュメントをガードレールとして保持できます。

次はステート：アプリの記憶とルール

UIがスケッチされたら次の問いは単純です：アプリは何を「覚える」必要があり、何に「反応」すべきか？その“記憶”がステートです。画面があなたの名前で挨拶し、カウンタを保ち、半分書いたフォームを復元し、結果を好みの並びで表示する理由がここにあります。

コアとなるステートオブジェクト

AIは通常、アプリ全体を通る少数のステートオブジェクトから始めます：

• User：プロフィール、設定、役割（例：manager vs. rep）
• Session：認証トークン、有効期限、isLoggedIn、リフレッシュルール
• Items：ドメインデータ（accounts、visits、follow-ups）＋ページネーション情報
• Filters：検索クエリ、選択タグ、ソート順、日付範囲
• Drafts：未送信メモ、未完のフォーム、「後で保存されたもの」

鍵は一貫性：同じオブジェクトと名前が複数の画面で使われ、各画面が独自の小さなモデルを勝手に作らないことです。

ルール：バリデーションとフォーム挙動

フォームは単なる入力ではなく、可視化されたルールです。AIは繰り返し使えるバリデーションパターンを生成できます：

• 必須項目は送信前にヘルパーテキストを表示（「Next step is required」）
• エラーは具体的に（「Due date can’t be in the past」）し、修正後はクリアされる
• 入力には妥当なデフォルト（今日が既定、日付ピッカーの制約）

読み込み・成功・失敗——毎回定義する

各非同期アクション（サインイン、アイテム取得、訪問保存）でアプリはよくある状態を循環します：

• Loading： 送信ボタンを無効にして「Saving…」を表示
• Success： トーストで確認し、一覧を即時更新
• Failure： ユーザー入力を保持し、親切なエラーを表示して「Try again」を提案

これらのパターンが画面間で一貫していると、実ユーザーが予期せぬ操作をしてもアプリが壊れにくくなります。

バックエンド統合：実データを体験に結びつける

フローは実データの読み書きができて初めて本物になります。画面とステートルールが出来上がったら、AIはユーザーの操作をバックエンドが何をサポートすべきかに翻訳し、生成された配線によりプロトタイプがプロダクトになります。

フローから推定されるバックエンドニーズ

典型的なユーザージャーニーから、バックエンド要件は次の具体的なバケットに落ちます：

• Auth & identity： サインアップ、サインイン、セッションリフレッシュ、役割管理
• Data CRUD： コアレコード（visits、follow-ups）の作成・取得・更新・削除
• Search & filtering： キーワードやステータス、日付範囲でのクエリ
• Notifications： プッシュトークン、設定、トリガー（例：「フォローアップが今日のもの」）

AIはUIの意図からこれらを引き出せます。たとえば「Save」ボタンはミューテーションを暗示しますし、一覧画面はページネーション付きのフェッチを意味します。

UIアクションをAPI呼び出しにマッピングする

エンドポイントを孤立して作る代わりに、マッピングは画面の操作から導出されます：

• Tap Log Visit → POST /visits
• Open list screen → GET /accounts?cursor=...
• Edit details → PATCH /visits/:id
• Mark follow-up done → PATCH /followups/:id

既にバックエンドがある場合、AIはREST、GraphQL、Firebase/Firestore、社内カスタムAPIに適応します。ない場合はUIニーズに合わせた薄いサービス層を生成します（余分なものは作らない）。

スキーマは推測され、そして確認される

AIはUIコピーとステートからモデルを提案します：

• Visit { id, accountId, notes, nextStep, dueAt, createdAt }

ただし人間が確認するべきです：どのフィールドが必須か、何がNULL可か、どこにインデックスが必要か、権限はどう働くか。早めの確認が「ほぼ正しい」データモデルが製品に固まるのを防ぎます。

エラー、リトライ、実運用の信頼性

統合は故障パスを一等地として扱わなければ完結しません：

• タイムアウトとオフライン対応
• 安全なリクエストのバックオフ付きリトライ
• 親切なユーザーメッセージとサイレントな診断ログ
• 競合（stale updates）処理

ここでAIは面倒な部分を加速します——一貫したリクエストラッパー、型付きモデル、予測可能なエラーステート——チームは正しさとビジネスルールに集中できます。

ビルド・テストループ：混乱なく高速フィードバックを得る

最初の「実際の」テストはシミュレータのスクリーンショットではありません——実際の電話で、誰かの手に、完璧でないWi‑Fi状況で動かすことです。そこが早く脆弱性を露呈する場所です。

実機でまず壊れるもの（とその理由）

多くの場合、機能の本体ではなく継ぎ目が壊れます：

• キーボードとレイアウトの不一致： キーボード表示でボタンが画面外に落ちる
• 遅い／不安定なネットワーク： ローディングが止まらない、データが即来る前提の画面
• 権限とOSの挙動： 通知やカメラ、ストレージの許諾プロンプトがフローを中断する

これは有用な失敗です。アプリが実際に何に依存しているかを教えてくれます。

AI支援のデバッグ：故障を層を跨いでたどる

何かが壊れたとき、AIは層を跨いだ探偵役として最も役立ちます。UI・ステート・APIを別々に追う代わりに、終端から終端へ経路をたどらせられます：

• フィールド不一致： UIは profile.photoUrl を期待しているがバックエンドは avatar_url を返す
• 欠落ステート： 「success」「error」は扱っているが「empty」「offline」「partial data」を扱っていない
• 重いコール： UIが重いエンドポイントにブロックされ、段階的に読めるようにできる

AIはフロー、画面マップ、データ契約を文脈として持っているため、フィールド名変更、フォールバック状態追加、エンドポイント応答調整といった横断的な単一修正案を提案できます。

成功に紐づく分析でループを計測

各テストビルドは「指標に近づいているか？」に答えるべきです。成功基準に結びついた少数のイベントを追加します。例：

• signup_started → signup_completed
• first_action_completed（活性化の瞬間）
• error_shown と理由コード（timeout、validation、permission）

これでフィードバックは単なる意見ではなく、計測可能なファネルになります。

1つのペース、1つの範囲：振り回されずに反復する

単純なリズムで安定を保ちます：毎日ビルド＋20分レビュー。各サイクルは1〜2件の修正を選び、UI・ステート・エンドポイントを同時に更新します。これにより画面だけ直って実運用で回復しない「中途半端に直された」機能を防げます。

実務的な詳細：オフライン、権限、エッジケース

ハッピーパスが動いたら、アプリはトンネル、低電力モード、拒否された権限、予測不能なデータを生き延びねばなりません。ここでAIは「壊さない」を具体的な振る舞いに変える手助けをします。

オフライン挙動：誇張しない実用性

各アクションを オフライン安全 か 接続必須 かでラベリングします。例：以前読み込んだアカウントの閲覧、下書きの編集、キャッシュされた履歴の表示はオフラインで可能にし、全文検索や同期、パーソナライズ推奨は接続が必要とみなす。

良い既定は：キャッシュから読む、アウトボックスに書く。UIは「ローカルに保存済み」と「同期済み」を明確に示し、接続回復時にシンプルな「再試行」を提供します。

権限：遅く聞き、早く代替を示す

権限は必要な瞬間に尋ねます：

• カメラ： 「写真を追加」をタップしたときに尋ね、拒否されたら「ライブラリからアップロード」や「手動入力」を提示
• 位置情報： 「近隣アカウント」を有効にするときに尋ね、拒否なら市区町村や郵便番号入力を許容
• 通知： 起動直後ではなく、リマインダーをオンにしたときに尋ねる。拒否でもアプリ内リマインダーを提示

目的は優雅な代替を用意してフローを塞がないこと。

エッジケース：地味だが品質を倍増させる要素

AIはエッジケースを素早く列挙できますが、製品姿勢はチームが選びます：

• 空結果： なぜ空なのか説明し、次の手を提案（フィルタ変更、検索範囲拡大）
• 重複： 安全にマージできれば自動で、そうでなければ作成前に警告
• タイムゾーン： タイムスタンプはUTCで保存し、表示はローカル時刻で。日付境界は明示
• 遅いネットワーク： スケルトン表示、タイムアウトとリトライ、永遠に回るスピナーを避ける

セーフティチェック：セキュリティとアクセシビリティ

セキュリティの基本：トークンはプラットフォームのセキュアストレージに保存、最小権限のスコープを使う、安全な既定（暗号化なしでの「ログイン状態の保持」を避ける）で出荷する。

アクセシビリティチェック：コントラスト、最小タップターゲット、動的テキスト対応、スクリーンリーダー向けのラベル（特にアイコンのみのボタンやカスタムコンポーネント）を検証します。

MVPを出荷する：ビルドからストア提出まで

出荷は有望なプロトタイプが実際のプロダクトになるか、静かに止まるかを分ける瞬間です。AIがUI・ステート・API配線を生成したら、その動くビルドをレビュアーと顧客が自信を持ってインストールできる形にします。

トラブルを避けるリリース手順

「リリース」を英雄的スプリントではなく小さなチェックリストとして扱います：

• ビルド署名： 本番署名キー／証明書を作成し安全に保管、CIが秘密を漏らさずアクセスできるようにする
• 環境設定： dev/staging/prodのエンドポイントとキーを分離。本番向けの分析・エラーレポート・決済が本番を指すことを確認
• バージョニング： ビルド番号とマーケティングバージョンを一貫して上げ、リリースごとにチェンジログを紐づけて何が出たか追えるようにする

ストア用アセット（誇張した約束は避ける）

MVPがシンプルでもメタデータは期待値を設定するため重要です。

• スクリーンショット： コアフローをデバイスの代表的サイズでキャプチャ。AI生成の画面を使った場合はタイポや空状態、最終コピーを必ず確認
• 説明文： 主なジョブを平易に説明。検証できない主張は避ける
• プライバシー注記： 収集するデータと理由を記載。具体的に、しかしまだ正式なポリシー準拠を暗示しすぎない

ロールアウト、監視、ロールバック

ローンチは実験として計画します。

まず内部テスト、その後段階的リリース（ステージドロールアウト）でリスクを限定。クラッシュ率、オンボーディング完了率、主要アクションのコンバージョンを監視します。

ロールバックのトリガーを事前に決めておきます——例：クラッシュフリーセッションがしきい値を下回る、サインイン失敗が急増する、主要ファネルの割合が急落するなど。

ビルドシステムがスナップショットと素早いロールバックをサポートすれば（たとえばKoder.aiがデプロイとホスティングと共にスナップショット／ロールバックを含む場合）、“取り消し”を正常な出荷プロセスの一部として扱えます。

もしあなたがMVPチェックリストを反復可能なリリースパイプラインに変える手助けが欲しければ、/pricing を見てください、あるいは /contact で連絡してください。

これが変えるもの：役割、オーナーシップ、次のリリース

AIが画面を草案化し、ステートを配線し、API統合をスケッチできると、仕事は消えるのではなくシフトします。チームはインテントをボイラープレートに変える時間を短縮し、何を作るべきか、誰のためか、どの水準で作るかを決める時間を増やせます。

AIが得意に扱うこと

AIはフローが明確になれば層間で一貫した出力を出すことに長けています：

• UIの一貫性： ヘッダー、リスト、空状態の繰り返しが整い、コピーの草案はレビューに十分なレベルで出る
• ステートパターン： ローディング、成功、エラー、リトライといった予測可能な振る舞いが画面に現れる
• 統合の足場： リクエスト／レスポンスモデル、エンドポイントラッパー、プレースホルダーエラーハンドリングが早期に出ることで実データへの配線が速くなる

人間が引き続き担うこと

AIは提案を出す。決めるのは人です。

• プロダクト判断： 何を切るか、何を遅らせるか、何を磨くか
• 優先順位付け： 価値を証明する最小の機能集合を選ぶ
• ユーザー理解： 実ユーザーにしか見えないエッジケース、信頼の問題、ユーザーが躊躇する瞬間
• QAの承認： デバイス上、弱いネットワーク下、本物のアカウントで振る舞いを検証する

保守性を保つために

スピードはコードが読めるままであるときだけ価値があります。

• 画面名、イベント、APIメソッドの命名規則を明確にする
• コンポーネントを重複ではなく再利用可能に保つ
• 統合レイヤーの近くにドキュメント化されたエンドポイント（目的、パラメータ、サンプルレスポンス）を保持する

Koder.aiのようなプラットフォームで最初のバージョンを生成する場合、実用的な保守性の解除はソースコードのエクスポートです：“高速生成”から“チームが所有するコードベース”へ書き直しなしで移行できます。

次のリリースの考え方

MVPが出荷された後、次のイテレーションは通常 パフォーマンス（起動時間、リストレンダリング）、パーソナライゼーション（保存済み設定、賢い既定）、より深い自動化（テスト生成、分析計装） に焦点を当てます。

さらに例や関連読み物は /blog を参照してください。