motherduck-build-cfa-app

顧客向け分析アプリの構築

まず確認すること：MotherDuck サーバーは稼働していますか？

稼働中のリモート MotherDuck MCP サーバーまたはローカルの MotherDuck サーバーを使い、対象データベース、スキーマ、粒度、キー、関連するメトリクスを調査します。既知のコンテキストを再利用し、調査範囲を依頼された作業に絞ります。デフォルトではワークスペース全体をスキャンしないでください。実際のデータモデルに合わせて結果を作成してください。

依頼内容またはアクティブなコンテキストから対象を特定します。曖昧さが結果に大きく影響する場合に限り、確認してください。サーバーがない場合は、提供されたスキーマと明示した前提に基づいて計画し、実環境で検証済みであるかのように示さないでください。

デフォルトの提供方式

• 3 層 CFA がデフォルトです：
  • ブラウザー -> バックエンド API -> MotherDuck
• 顧客のルーティング、接続の選択、サービスアカウントの使用、埋め込みセッションの作成はバックエンドで行います。
• Embedded Dives は、次の条件を満たす場合に利用できます：
  • 要件が読み取り専用である
  • 製品でライブ Dive サーフェスをアプリに組み込む必要がある
  • アプリ側でのポリシーと UX の制御が限定的である
  • バックエンドで埋め込みセッションを作成でき、管理者トークンをサーバー側で保持できる
• DuckDB-Wasm は、小規模なブラウザー側の読み取り専用ワークロードに限り利用できます。
• 単一の共有 tenant_id フィルタリングは推奨方式ではなく、代替手段です。
• フィルタリングされた Share では、厳選したテーブル／ビューのサブセットが公開されます。Share 上のセキュアビューでは、コンシューマーの ID（顧客ごとのサービスアカウントでは current_user）に基づく行フィルター、非表示列、マスキングを追加できます。これにより、1 つのデータベースから一定数の顧客にサービスを提供できます。テナントごとに独立したコンピュート、データライフサイクル、または契約上の分離が必要な場合は、顧客ごとにデータベースを用意することをデフォルトとしてください。
• connection_timeout を設定してバックエンドの接続時間を制限し、コールド状態の Duckling がリクエストをハングさせずにフェイルオーバーできるようにします。
• Embedded Dives は読み取り専用で、Flights を実行できません。アプリ内のアクションはバックエンド API を通じて実行します。
• Embedded Dives では、postMessage のオリジン／タイプ／ペイロードを検証し、initial_state は JSON シリアライズ可能な UI 状態にのみ使用します。ナビゲーション、エクスポート、永続化のポリシーはホストアプリケーションで管理します。

ワークフロー

1. 利用可能な MotherDuck サーバーまたは提供されたスキーマのコンテキストを確認します。
2. 関連する Guides を読み、実際のデータモデルを調査し、アプリを支える統制済みの定義を検証します。
3. 提供方式を選択します：
   • 3 層アプリ
   • 埋め込み Dive
   • ブラウザーのみのプロトタイプ
4. 分離モデルを設計します：
   • 顧客ごとのデータベース
   • ワークロードごと、またはサービスアカウントの境界ごと
5. 許可リストに登録したメトリクス、ディメンション、フィルター、顧客境界を含む API コントラクトを定義します。
6. 接続経路と読み取りスケーリングの方針を選択します。
7. 実装計画、API コントラクト、段階的なロールアウト手順を作成します。

実行内容は依頼に合わせてください。回答、レビュー、計画の依頼では、求められたアーキテクチャ成果物を返します。構築や変更の依頼では、対象範囲内で求められたファイルやサービスを作成し、検証します。破壊的な操作、依頼に含まれていない外部への書き込み、または対象範囲の大幅な拡張を行う前に確認してください。

このスキルでネイティブ DuckDB（md:）接続を作成する場合は、custom_user_agent=agent-skills/2.6.0(harness-<harness>;llm-<llm>) を設定します。メタデータが不足している場合は、harness-unknown と llm-unknown にフォールバックします。

出力

依頼に関連する範囲で、包括的な作業では次の項目を扱います：

• 推奨する提供アーキテクチャ
• 分離モデル
• 接続戦略
• 最初の実装スライス
• 検証およびロールアウト計画

明示的に構造化 JSON を求められた場合は、出力コントラクトを参照してください。それ以外の場合は、求められた成果物に適した形式を使用します。

参考資料

タスクに関連するセクションのみを読みます。これらはガイダンスであり、必須の手順ではありません。

• references/CFA_IMPLEMENTATION_GUIDE.md -- バックエンドの実装、サービスアカウント、ルーティング、読み取りスケーリングの例
• references/CFA_ARCHITECTURE.md -- アーキテクチャの比較、分離モデル、接続経路の詳細

例

同梱の例を実行する場合、またはその検証を再現する場合に限り、実行リファレンスを参照してください。

• customer_routing_example.py
• customer_routing_example.ts

関連スキル

不足している機能を補う場合に限り、関連スキルを読み込み、確立済みのコンテキストを再利用してください。

• motherduck-connect -- 適切なPGエンドポイントまたはネイティブDuckDBの経路を選択します
• motherduck-explore -- アーキテクチャを選択する前に、稼働中のデータベースとスキーマを調査します
• motherduck-model-data -- 顧客ごとの分析に適したテーブルを設計します
• motherduck-query -- クエリの提供とレイテンシーに敏感な集計を検証します
• motherduck-load-data -- 顧客向けデータ更新のための取り込み経路を構築します