AIフレンドリーなアプリケーション設計のチェックリスト

最近は AI Agent や MCP (Model Context Protocol) を使って既存システムを操作するケースが増えています。

しかし、多くの既存アプリケーションは「人間が画面を操作すること」を前提に作られており、AI から利用しようとすると意外と苦労します。

一方で、最初から少しだけ設計を意識しておくと、将来的に Tool 化や MCP 化が非常に楽になります。

ポイントは 「人間向けUI」とは別に、「AIが安全かつ確実に操作できる面」を用意しておくこと です。

ただしこれは、人間用とAI用に 別々のシステムを二重に作る という意味ではありません。むしろ逆で、人間向けUIも、AIが叩くのと同じAPI（を直接、またはラップした関数）経由で動かす ——つまりAIと人間で操作の入り口を共通化することが、良いコードを保つ鍵になります（詳しくは「人間用UIとAI用APIのロジックを分離しない」を参照）。

以下は、AIフレンドリーなアプリケーション設計のためのチェックリストです。

UI操作だけに依存しない

  • 主要操作は必ず API / CLI / SDK から実行できるようにする
  • ブラウザ操作やDOM操作を前提にしない
  • AIが画面をクリックしなくても処理できる構造を目指す

APIは小さく、明確に、冪等にする

責務を明確に分離する。

  • create
  • update
  • delete
  • get
  • list
  • execute

また、

  • 同じリクエストを何度実行しても壊れにくくする
  • 副作用のある操作は明示する

状態を持ちすぎない

  • セッション依存を減らす
  • 長いウィザード形式を避ける
  • 可能な限り単発のAPI呼び出しで完結させる
  • 必要な状態はリクエストとして明示する

認証情報をAIに持たせない

  • APIキーは環境変数で管理する
  • Secret Managerを利用する
  • AIには認証済み実行環境だけを渡す
  • プロンプトに秘密情報を埋め込まない

権限を細かく分離する

例えば以下のような権限を用意する。

  • Read
  • Create
  • Update
  • Delete
  • Execute
  • Admin

また、

  • AIには最小権限のみ付与する
  • 本番環境と開発環境の権限を分離する

危険操作には確認ステップを用意する

削除や送信などは即実行させない。

  • dry-run
  • preview
  • confirm

を用意する。

対象例:

  • メール送信
  • 請求処理
  • データ削除
  • 本番デプロイ
  • 権限変更

API仕様を機械可読にする

以下のような形式を整備する。

  • OpenAPI
  • JSON Schema
  • MCP Tool Schema
  • Typed SDK

AIは自然言語より構造化された仕様の方が扱いやすい。

エラーを構造化する

人間向け文章だけではなく、機械が処理しやすい形式で返す。

{
  "error_code": "USER_NOT_FOUND",
  "retryable": false,
  "suggested_fix": "Create user first"
}

推奨項目:

  • error_code
  • retryable
  • suggested_fix
  • missing_fields

入出力を構造化する

自由文よりも以下を優先する。

  • JSON
  • JSON Lines
  • CSV
  • Protocol Buffers

レスポンスには可能な限り以下を含める。

  • ID
  • 状態
  • 次に可能な操作

ログと監査証跡を残す

記録すべき内容:

  • 誰が実行したか
  • どの権限で実行したか
  • 何を変更したか
  • 成功したか失敗したか
  • AI経由か人間経由か

後から検証できることが重要。

人間用UIとAI用APIのロジックを分離しない

よくある失敗は、

  • UI専用ロジック
  • AI / API専用ロジック

が別実装に分かれてしまうこと。AIと人間で「操作の入り口」を二重に作ると、片方だけ仕様が古くなったり挙動がズレたりして、バグの温床になる。

理想は、人間向けUIも、AIが叩くのと同じAPIを使うこと。 UIはそのAPIを直接、または薄くラップした関数を経由して呼び出す。こうすれば操作の入り口が一本に共通化され、AIと人間がまったく同じロジックを通る。

人間向けUI ─┐
            ├─→ 共通API（またはそのラッパ関数）─→ Domain Logic
AI / MCP ───┘

ポイント:

  • AIと人間で 別々のAPIを作らない（共通化する）。これが結果的にコードを健全に保つ
  • UIから直接DBやドメインロジックを叩かず、必ずこの共通APIを経由させる
  • 共通APIを unit test で固めておくと、人間・AI どちらの経路も同時に品質が保証され、安心してリファクタリングできる

イベント駆動を意識する

操作結果をイベントとして記録する。

例:

  • UserCreated
  • InvoicePaid
  • TaskCompleted

メリット:

  • AIが履歴を追いやすい
  • 状態変化を説明しやすい
  • Rollbackしやすい

フロントエンドもAI操作を意識する

  • URLで状態を再現できる
  • hidden stateを減らす
  • 状態管理をシンプルにする
  • Form Schemaを定義する

後からAgentが利用しやすくなる。

テスト環境を整備する

  • Sandbox環境
  • Fixtureデータ
  • Mock API
  • テストアカウント

を用意する。

AIが安全に試行錯誤できる環境は重要。

ドキュメントをAI向けに書く

最低限必要な情報:

  • 目的
  • 入力
  • 出力
  • 副作用
  • エラー
  • サンプル
  • 注意事項

長文の解説よりも、短く正確な説明の方がAIは扱いやすい。

既存アプリは「AI用操作レイヤー」から始める

全面改修する必要はない。

まずは以下から整備する。

  • 読み取りAPI
  • 検索API
  • 作成API

内部関数を少しずつ Tool 化していく方が現実的。

まとめ

AI時代のアプリケーション設計は、必ずしも「AI専用アプリを作る」ことではありません。

むしろ、

  • APIファースト
  • 最小権限
  • 構造化データ
  • Dry Run
  • 監査ログ
  • 機械可読な仕様

といった従来からの良い設計を徹底することが重要です。

これらを意識しておけば、将来的に MCP Server や AI Tool として公開したくなったときも、大きな作り直しをせずに対応できます。

言い換えると、

AIフレンドリーな設計とは、人間にも機械にも扱いやすい設計である。

合わせて読む