カプストン統合：技術・プロダクトデモと「アプリパスポート」

1. 「アプリパスポート」とは何か、なぜ必要か

アプリパスポートはコンパクトながら密度の高いドキュメント（通常はMarkdownで1〜2ページ、またはREADME内のセクション）で、あなたのChatGPTアプリについて、構造、制約、収益化、プロダクション運用の方法を誰にでも素早く理解してもらうためのものです。

これはマーケティングのパンフレットではありません。ここで扱うのは「最新鋭のAI技術」ではなく、もっと地に足のついた事柄です。

• ChatGPT、あなたのウィジェット、MCPサーバー、エージェント、そしてACP/Stripeの間の境界がどこにあるか;
• どのPIIを保持し、OAuth/スコープとシークレットのローテーションをどう設計しているか;
• レイテンシと可用性のSLO、どんなダッシュボードやアラートがあるか;
• 平均して1つの成功シナリオにいくらかかり、どう課金するか;
• どんな典型的インシデントをすでに記述し、runbookがどこにあるか;
• 今後数カ月でこのアプリをどう進化させるか。

パスポートは、リンクとハイレベルな説明のアグリゲーターと考えるとよいでしょう。コードほど頻繁には変わりませんが、「投資家向けの公式プレゼン」よりは頻繁に更新されます。

ChatGPTアプリの開発者として、パスポートは成熟度チェックリストでもあります。もしどこかのセクションが空欄（「SLOは特に記述していない……」）なら、それは良いレッドフラグです。ドキュメントが足りないだけでなく、プラクティスそのものが欠けている可能性を示します。

2. GiftGeniusのパスポート基本構成

GiftGeniusでは、次のような構成が自然です（あなたのアプリに合わせて多少調整しても構いませんが、全体の考え方は同じです）。

誰が何を読むか、目的を小さな表で示します。

この後、各ブロックを解説しつつ、GiftGenius向けの実際のPASSPORT.mdのたたき台を作っていきます。

3. アーキテクチャ：全スタックを1枚で示すには

アーキテクチャのセクションはパスポートの心臓部です。200個の矩形があるUML図を描く必要はありません。ユーザーがChatGPTからあなたのDBや決済に至るまでのレイヤーとフローを示すことが重要です。Apps SDKとMCPを使うChatGPTアプリでは、この道筋は定型的です。

便利な形式は、PASSPORT.md内にそのままMermaidの図を置くことです。GiftGeniusの例を示します。

flowchart TD
  U[User in ChatGPT] --> C[ChatGPT + GPT-5]
  C --> W[GiftGenius Widget
Next.js + Apps SDK]
  W --> MCP[MCP Server
giftgenius-mcp]
  MCP --> A[Agent: GiftPlanner]
  A --> DB[(Postgres: products,gifts)]
  A --> ACP[ACP / Stripe]
  ACP --> ORD[(Orders)]

図の下では、主要シナリオを文章で説明します。

ユーザーがチャットで贈り相手の情報を記述します。モデルはMCPサーバーのtoolsuggest_giftsを呼び出すと判断します。エージェントはカタログをリソースとして読み込み、複数のtoolを実行することもあります。その後、ギフトを選ぶとStripeでACPセッションが作成され、チェックアウトはwebhook経由で進み、結果はDBに保存されます。

ここで技術スタックにも触れておくとよいでしょう。Next.js 16 + Apps SDK、MCPサーバーはNode/Python、データベースはPostgreSQL、キャッシュにRedis、決済はStripeです。

また、アーキテクチャのブロックに小さな技術断片を添えると、図中の「Widget → MCP」という抽象的な矢印がコードでどう現れるかが伝わります。例えば、requestIdとuserIdをMCPクライアントに受け渡すNext.jsのルートの断片です。

// app/api/suggest-gifts/route.ts
import { mcpClient } from "@/lib/mcpClient";

export async function POST(req: Request) {
  const { occasion, budget } = await req.json();
  const requestId = crypto.randomUUID();      // ログ用のトレースID
  const userId = req.headers.get("x-user-id") ?? "anonymous";

  const result = await mcpClient.callTool("suggest_gifts", {
    occasion, budget, requestId, userId,
  });

  return Response.json({ requestId, result });
}

このような断片は、図上の抽象的な矢印「Widget → MCP」と実際のコードを結びつけるのに役立ちます。

4. Security & Privacy：何を確定しておくべきか

パスポートにおけるセキュリティは「HTTPSを使っていて、バックエンドはTypeScriptだから大丈夫」という話ではありません。セキュリティ、コンプライアンス、法務の問いに具体的に答える必要があります。

GiftGeniusでは、次を簡潔に記述するとよいでしょう。

認証・認可モデル:
コマース系シナリオではMCP Auth Server経由のPKCE付きOAuth 2.1を使用。トークンはuser_idとtenant_idに紐づき、チェックアウト関連のtool呼び出しはscopecommerce.checkoutを必須とします。

何がPIIで、どう取り扱うか。
例：メールと氏名はPII、ギフトの嗜好は仮名化データ。ログにはハッシュ化したメールのみを記録。配送先住所は保存せず、Stripeとwebhookにのみ受け渡します。

保持期間（retention）と削除の設計:
ツールのログは30日、コマースイベントは1年。ユーザーのリクエストに応じて、注文と関連する分析イベントを削除可能とします。

シークレット管理:
OpenAI API key、Stripeのシークレット、OAuth client secretをどこで保管しているか（例：マネージドなシークレットストア）、どの頻度でローテーションするか、stagingでどうテストするかを簡潔に記述します。

パスポートには「最小権限の原則」を示すための小さな技術断片を載せてもよいでしょう。

// config/scopes.ts
export const TOOL_SCOPES = {
  suggest_gifts: ["read:products"],
  get_gift_details: ["read:products"],
  create_checkout_session: ["read:products", "write:orders", "stripe:checkout"],
} as const;

続いて、ツールの説明やMCP認可で同じスコープに言及します。単なる「最小権限」というスローガンではなく、具体的なコントラクトになります。

5. ObservabilityとSLO：アプリの健全性を可視化する

次のブロックは監視性についてです。アプリが生きていて健全かをどう把握するか。ここでは構造化ログ、メトリクス、SLO、ダッシュボードへのリンクが結びつきます。

GiftGeniusでは、次を記述するのが自然です。

主要SLO。
例：MCPの可用性 ≥ 99.5%、suggest_giftsのp95レイテンシ < 5秒、チェックアウトの成功率 ≥ 99%。

SLOの可視化場所。
GrafanaやDatadogなどのダッシュボード名とURL（パスポートには「Dashboard: GiftGenius / SLO」といった記述でも可）。

構造化ログのフォーマット。
前の監視モジュールで、 request_id、tool_name、user_id/tenant_id、 tokens_in/tokens_out、cost_estimate、duration_ms、error_code といったフィールドを設計しました。パスポートでは小さなJSON例を示すのも有用ですが、ここではさらに一歩進めて、コードでも使っているTypeScriptの型として示します。

// lib/logging.ts
export type ToolInvocationLog = {
  level: "info" | "error";
  timestamp: string;
  requestId: string;
  userId?: string;
  toolName: string;
  tokensIn?: number;
  tokensOut?: number;
  costEstimateUsd?: number;
};

そしてヘルパー関数:

export function logToolInvocation(event: ToolInvocationLog) {
  console.log(JSON.stringify({ type: "tool_invocation", ...event }));
}

これで、この型がコードとパスポートの橋渡しになります。Observabilityセクションでは、すべてのtool呼び出しがToolInvocationLog形式でログに記録されること、そしてそれらを集約するダッシュボードへのリンクを記します。

簡単なテキストの流れ図も添えられます。

イベントログ → ログストア → SLOダッシュボード → アラート → インシデント／Runbook。

6. Economics & Product Metrics：お金とユーザー行動

ここでは、前のエコノミクス（M19）で扱ったコストメトリクス、プライシング、プロダクト分析を結びつけます。

GiftGeniusではパスポートに次を固定するとよいでしょう。

主要シナリオのユニットエコノミクス（仮に「1つの完了タスクの経済性」）。
例：「平均cost_per_successful_task（ギフト選定＋決済成功）＝ $0.13（LLM＋インフラ）。1タスクあたりの平均売上＝ $0.80（パートナーからのCPA）。」

主要なマネタイズモデル。
要点：「購入なしの基本的な選定は無料。マネタイズはパートナー店舗への送客によるCPA＋拡張フィルタやギフト履歴を備えたプレミアムサブスクリプションをオプション提供。」

主要なプロダクトメトリクス。
例：activation rate＝少なくとも1回workflow_completedがあったユーザーの割合。repeat rate＝月内に少なくとも1回戻ってきたユーザーの割合。workflow_completed → checkout_success のコンバージョン。

実験。
進行中のA/Bの一覧：「モデルA（高コスト） vs モデルB（低コスト）」「長いウィザード vs 高速インライン」。各実験でexperiment_id、バリアント、ターゲット指標（コンバージョン、cost_per_task、quality score）を保持します。

パスポートを机上の空論にしないため、コード側にも表れを持たせます。たとえば分析イベント用の共通ヘルパーです。

// lib/analytics.ts
export function trackEvent(
  name: string,
  payload: Record<string, unknown>,
) {
  console.log(JSON.stringify({
    type: "analytics",
    name,
    ts: new Date().toISOString(),
    ...payload,
  }));
}

そして、ワークフロー完了時の呼び出し例。

trackEvent("workflow_completed", {
  userId,
  requestId,
  experimentId: "model_ab_01",
  variant: "A",
  costUsd: 0.13,
  checkoutSuccess: true,
});

パスポートでは、どのイベントがキーで、どのKPIをそこに紐づけるかを説明します。コードは「測っている」という証拠になり、単なる約束で終わらないようにします。

ただし、メトリクスやエコノミクスが意味を持つのは、アプリがプロダクションで安定稼働している場合に限られます。次のセクションでは、GiftGeniusの運用面（インシデント、オンコール、runbook）をパスポートにどう固定するかを見ていきます。

7. Ops & Incidents：プロダクションでどう生きるか

このセクションは、物事が計画通りに進まない時にどう反応するかについてです。

GiftGeniusのパスポートでは、少なくとも次の2つの典型インシデントを列挙するのがよいでしょう。

決済の問題。
例：チェックアウトの成功率がSLOを下回る、Stripeのwebhookでエラーが多発する。パスポートには、runbook「Checkout Failures」があると記し、症状、調査場所（エラーダッシュボード、webhookエンドポイントのログ）、迅速な緩和策（問題のあるフィーチャーフラグを無効化、一部トラフィックをsandboxへ、または一時的にギフト券のみ提案）とフォローアップ（ポストモーテム、新しいアラートの追加）を明記します。

MCP/LLMの問題。
例：suggest_giftsのp95レイテンシが9秒まで上昇、または多くのリクエストで「Error talking to app」。ここには別のrunbookがあり、OpenAIのステータス、トンネル/Vercel、MCPのヘルスチェックを確認し、劣化モードへ切り替えます。劣化モードでは、エージェントはカタログにアクセスせず（コマース無し）、モデルの一般的な知識だけで回答を試みます。

同セクションで、運用カレンダーも簡潔に記載します。SLOの見直し頻度、コストレビューの頻度、セキュリティログの確認とシークレットのローテーション頻度などです。

また、オンコール担当（1人だけでも）と、アラートの送信先Slackチャンネルやメールアドレスも記します。

8. Roadmap & Risks：前向きで正直な見通し

最後のブロックは将来についてです。長文は不要です。アプリの現実的な次の3〜5歩と、既知の制約をいくつか挙げれば十分です。

GiftGeniusの例:

• 選定品質に対するLLM評価（LLM-evals）の導入で、品質とコンバージョンを紐づける;
• もう1つロケールを追加し、ツール説明のローカライズをテストする;
• 一部トラフィックで低コストモデルを試す実験;
• Stripe障害へのレジリエンス強化（webhookと遅延承認の堅牢な処理）;
• Apps SDKまたはMCPの新バージョン移行への備え（ツールコントラクトのバージョニング）。

制約: API上限、ChatGPT UIの制限（例：カード表示数の制限）、現在のアーキテクチャの弱点（単一リージョンDB、MCPのホットスタンバイ欠如など）。

実験計画：pricing/UX/モデルに関する仮説を何で検証し、どのメトリクスで意思決定するか。

9. パスポートの所在と更新方法

実務的に最も便利なのは、GiftGeniusリポジトリのルートまたはdocs/配下にPASSPORT.mdを置き、ドキュメンテーションシステム（Confluence、Notion等）にコピー／リンクを用意することです。

10〜15分で読める軽さと、以下の質問に答えられるだけの濃さを両立すべきです。

• 「これはそもそもどんなアプリで、どういう構造なのか？」
• 「Xが落ちたらどうなる？」
• 「1ユーザーあたりのコストはいくらか？」
• 「今もっとも懸念しているリスクは何か？」

パスポートの更新タイミング:

• アーキテクチャ境界の変更（新サービス、新決済、別スタックへの移行）;
• 主要SLOやセキュリティポリシーの変更（例：保持期間の変更）;
• マネタイズモデルの変更;
• 重要なインシデントとポストモーテムからの示唆。

コードの些細な変更は即時の更新対象にしないほうがよいでしょう。そうしないと、パスポートが陳腐化するドキュメントの一種になってしまいます。

パスポートは、あなたが自分のアプリについて知っていることの凝縮です。次の自然なステップは、これをもとに技術者とビジネスの双方に向けて製品を語れるようにすることです。

10. 技術・プロダクトデモ：2つの「語りのバージョン」が必要な理由

GiftGeniusを見せるとき、ほぼ常に2種類の聴衆（しばしば同じ部屋に混在）に向き合います。

• 技術者（CTO、アーキテクト、セキュリティ、開発リード）;
• プロダクト／ビジネス（CEO、投資家、プロダクト、マーケティング）。

技術者が重視する点:

• アーキテクチャが明確でレイヤー分離ができており、拡張ポイントがある;
• 信頼性と監視性が練られている（ログ、トレーシング、SLO、アラート）;
• レジリエンスのストーリー（OpenAI、MCP、Stripeが落ちたらどうするか）がある;
• 進化計画（SDK/MCP/モデルの移行）がある。

ビジネスが重視する点:

• ユーザーの課題（例：「ギフト探しに40分かかる」）は何か;
• GiftGeniusがChatGPT内でそれを数分でどう解決するか;
• マネタイズ、ユニットエコノミクス、成長メトリクスはどうか;
• 顧客獲得コストを下げ、コンバージョン／売上を伸ばせるか。

したがって、同じデモの物語を2つの「層」として考えるのがよいでしょう。成熟したプロダクトの兆候は両方に見せつつ、強調点は変えます。

11. GiftGeniusの技術デモ（5〜7分）

技術者向けにGiftGeniusをプレゼンすると仮定します。

まず短いコンテキスト。
30秒で十分。「GiftGeniusはACPチェックアウトを備えたギフト選定用のChatGPTアプリです。ChatGPT内で動作し、Apps SDK、MCP、計画用のエージェントを使っています。」

続いてアーキテクチャのスライド／パスポートの抜粋。
Mermaidで描いたような図を開き、ChatGPT（LLM部分）、ウィジェット、MCP、Stripeを使うコマース層の責任境界を説明します。toolはすべてMCPにカプセル化され、ウィジェットは薄いUI層であることを示すと有益です。

ログ付きのライブデモ。
次に分割画面：左にGiftGeniusを有効化したChatGPT、右にログまたはMCP Inspector。自然なリクエストとして「ゲーマー向けで50ドル以下のプレゼントを探して」と入力。実行の過程で、次を示します。

• tool呼び出しsuggest_giftsとrequest_id;
• tool_invocationという構造化ログで、tokens、cost_estimate、duration_msが見えること;
• ACPセッションを開始し、注文を作成する二次的なtool。

可能なら即座にダッシュボードを開きます。「これが過去24時間のこのシナリオのp95レイテンシ、これがチェックアウトの成功率です」。この瞬間、技術者は「これはペットプロジェクトではなく、監視性があるシステムだ」と理解します。

障害注入（オプションだが効果的）。
システムに十分自信がある（または事前に準備している）なら、例えば一時的にカタログ（DB）へのアクセスを無効化して同じリクエストを繰り返します。示すべきは次です。

• MCPがエラーを正しく記録し、アラートが発火する;
• エージェントが劣化モードへ切り替わり、ユーザーに「カタログは現在利用不可だが一般的なアイデアは提案できる」と正直に伝える;
• このモードではチェックアウトは不可。

最後に、運用と進化を簡潔に。
SLO、インシデント、ロードマップのスライドで締めます。どの指標を目標とし、どう監視し、どんなインシデントにrunbookがあるか、v2で何をするか（スケール、モデルの更新、新市場など）。

聴衆へのメインメッセージは、「美しいUIだけではなく、プロダクションに耐える設計のプラットフォームである」ということです。

12. プロダクトデモ（ビジネス視点）

同じGiftGeniusでも、今度はプロダクトとして語ります。

ユーザーストーリーから始める。
例：「カーチャは今日中に同僚へのプレゼントを選ぶ必要がある。普段はECサイトを行き来して30〜40分かかっている」。

ChatGPTでGiftGeniusを見せる。
カーチャはマーケットプレイスのフィルターではなく自然文で書く。「ボードゲームが好きな同僚向け、予算は50ドルまでのプレゼントを選んで」。ChatGPTがGiftGeniusの利用を提案し、ウィジェットを開く。GiftGeniusは2〜3の詳細を確認して、候補リストを表示する。

結果と価値に移る。
ギフトカード（商品カード）を提示し、保存や即購入への導線、ACP/Stripeでのチェックアウトを示す。重要な一言：「これらはユーザーが普段時間を過ごしている場所、つまりChatGPTの中で、3〜5分で完了します」。

次に1〜2分でマネタイズと指標。
CPAや店舗からのコミッションで収益化し、ヘビーユーザー向けにプレミアムモードを提供することを説明。パスポートの数字に言及：1成功シナリオあたりのコスト、購入コンバージョン、確保しているマージンの余地。

少し成長戦略を。
ユーザー獲得の計画（ChatGPTストアのリスティング、コンテンツ、パートナー連携）を話しつつ、プロダクト指標に紐づける。「リスティングの変更が新規app_opened数とactivation rateにどう影響するか、記事や動画がリテンションやworkflow_completedが2回以上あるユーザーの割合にどう効くかを見ています」。

最後はリスクと計画で締める。
OpenAI/Stripeの上限制約への依存や、ロケール対応の弱さなど現在の制約を正直に述べ、パイプラインにある実験と改善のロードマップを示します。

丁寧に実施すれば、ビジネスの聴衆には「また新しいAIウィジェット」ではなく、経済性と成長計画を備えた明快なプロダクトとして映ります。

13. 実践：GiftGeniusのパスポートとデモを組み立てる

本講義の実践として、GiftGeniusのリポジトリにPASSPORT.mdを作成し、少なくとも5ブロック（アーキテクチャ、セキュリティ、observability/SLO、エコノミクスとプロダクトメトリクス、インシデント／運用）を埋めましょう。新しいrunbookを追加したりSLOを変更したら、都度パスポートに反映します。

同時に5〜7分のデモ台本を用意するのも有効です。最初の2〜3分はユーザーシナリオと価値、次の2〜3分はアーキテクチャと運用（SLO、コスト、インシデント）。この台本は、ビジネスと技術の両方の言葉で話す訓練になり、乾いたコード説明や空虚なマーケティングに偏らない助けになります。

これらのアセットは「提出用の紙」ではなく、最終のカプストンデモの土台です。実際、このパスポートとシナリオに基づいて、仮想のCTO/CEOにあなたのアプリを説明・防衛することになります。

14. パスポートとデモ準備の典型的な誤り

誤り №1：パスポートをマーケティング冊子にしてしまう。
パスポートがランディングページのようになりがちです。「革新的AI」の一般論が多く、アーキテクチャ、SLO、コスト、インシデントの具体性が乏しい。これでは誰の役にも立ちません。技術者は内部でどう生きているのか分からず、ビジネスはリスクをコントロールしていると感じません。パスポートには事実、図、メトリクス、リンクが必要です。

誤り №2：コードだけを列挙し、データフローと責任分界を記さない。
開発者にありがちな偏りは、全サービスやライブラリ、フレームワークを列挙しつつ、「ユーザー → ChatGPT → ウィジェット → MCP → エージェント → ACP/DB」という高レベル図を忘れることです。その結果、新しい人は誰の責務がどこで、境界がどこかを理解できません。アーキテクチャのセクションで重要なのは、レイヤーとデータフローであって、すべてのnpmパッケージ名ではありません。

誤り №3：パスポートをobservabilityとコスト計測に結びつけない。
「SLOがある」と誇らしげに書いてあるのに、どこで測っているのか、ログはどこで、JSONイベントにどんなフィールドを書くのかが見えないことがあります。または「LLMコストを管理している」と書くのに、cost_per_taskのようなメトリクスが一つもない。実ログ、実メトリクス、実ダッシュボードとの結びつきが弱いほど、SLOやコストがGoogle Docsの中だけで生き、監視システムには存在しないリスクが高まります。

誤り №4：美しいUIだけを見せ、アーキテクチャと可用性を見せないデモ。
「見てください、このギフトカードのUIが最高です」とショーに寄りがちです。技術者はその瞬間、「Stripeが落ちたら？」「tool呼び出しはどうログする？」「スケールできるの？」と考えています。ログ、SLO、インシデントについて最低1〜2のストーリーを見せないと、技術者にはおもちゃにしか見えません。

誤り №5：技術者だけ向けのデモで、ユーザーストーリーと経済性がない。
逆の偏りです。p95レイテンシやMCPハンドシェイク、ツールのJSON Schemaを10分語っても、ユーザーの課題、誰が支払い、1シナリオいくらかを一度も言わない。ビジネスやプロダクトには「ビジネスケースのないすごいエンジニアリング」に映ります。常にエンジニアとプロダクトマネージャーの最低2つの帽子を被る意識を持ちましょう。

誤り №6：パスポートとデモの内容が乖離している。
パスポートではこう、デモでは別のことを言う──ドキュメントで約束したSLOとダッシュボードの数値が違う、パスポートには3つのインシデントとrunbookがあるのに、ライブでは最初の障害で皆が右往左往。パスポートをデモの台本として使い、同じSLO、同じダッシュボード、同じrunbookを参照するよう努めましょう。そうすれば、聴衆にはバラバラのアセットではなく「一貫したシステム」に映ります。

誤り №7：パスポートを単発の課題提出物だと考える。
最大の落とし穴は、モジュール提出のためにPASSPORT.mdを書いて放置すること。現実世界では、この手のドキュメントが「頭の中にだけある知識の動物園」を防いでくれます。パスポートをコードの生きた一部として扱い、重大なアーキテクチャ、運用、ビジネス上の決定に合わせて更新しましょう。数カ月後、きっと自分に感謝するはずです。