motherduck-create-dive

MotherDuck Dive の作成と管理

信頼できる情報源

• まず、最新の MotherDuck Dive ドキュメントを優先してください。
• 必須の順序： MotherDuck MCP が利用可能な場合は、Dive のコードを書く前、および save_dive または update_dive を呼び出す前に、必ず get_dive_guide を呼び出してください。ガイドには、現在のコンポーネント API とランタイムライブラリが記載されています。
• get_dive_guide では、予約済みの dives ガイドトピックにある関連規約も確認できます。ユーザーの明示的な要件と矛盾しない場合は、それらの規約を適用してください。
• ローカルプレビュー、コードとして管理する Dives の構成、メタデータ、CI プレビュー、デプロイスクリプトについては、公式の Dives サンプルリポジトリを参照実装として使用してください。
• ユーザーが MCP ツールではなく、スクリプト可能な SQL ネイティブの作成・読み取り・更新・削除ワークフローを希望する場合は、Dives の SQL 関数を使用してください。
• 通常の Dives と埋め込み Dives は別々に扱ってください。埋め込みを展開できると約束する前に、現在のプランの利用条件を確認してください。プラン名や提供状況に関する記憶上の情報をそのまま使わないでください。

デフォルトの方針

• まず作業の種類を分類します。新しい Dive、既存の Dive の編集、Dives-as-code のワークフロー、チームでの共有、または埋め込みです。
• まず motherduck-explore と motherduck-query を使って、基盤となる SQL とスキーマを検証します。優れた Dive は、正しいクエリから始まります。
• Dive のクエリは完全修飾し、SQL を中心に構成します。React はデータの再構成ではなく、表示を担当します。
• コンポーネントの契約では、React と useSQLQuery、デフォルトエクスポート、サポート対象のランタイムライブラリ、明示的な読み込み・空・エラー状態、ブラウザー側に秘密情報を置かないことを必須とします。
• 新しい Dive は Draft から始めます。依頼された納品内容に公開が含まれる場合に限り、検証済みの Dive を Ready に昇格させます。Dive を Endorsed にできるのは管理者だけです。エージェントが作成した Dive を自ら承認してはいけません。
• 既存の作業を再利用する場合は、まず Endorsed、次に Ready の Dive を優先します。Archived の Dive は廃止済みのため、明示的に依頼された場合を除き、エージェントのデフォルトの一覧から除外します。
• ローカルプレビューで REQUIRED_DATABASES を使う場合は、エクスポートを1行に保ち、実際の共有依存関係をメタデータまたは保存・更新時の入力値に反映します。既存のデータベース名と衝突するエイリアスは避けます。
• 範囲を限定した編集では、既存の Dive のビジュアルシステムを維持します。新しい Dive では、対象ユーザーに合った具体的なテーマの方向性を選びます。
• 1つの巨大な汎用クエリではなく、ビジュアルのセクションまたは操作領域ごとにクエリを1つ用意することを優先します。
• 環境が対応している場合は、保存前にローカルでプレビューします。
• 既存の Dive では、上書きする前に現在の内容とバージョンメタデータを確認します。MCP の list_dives は current_version を返し、read_dive では過去のバージョンを取得できます。部分的な編集には edit_dive_content（テキストの完全一致置換）を使い、全面的な書き換えには update_dive を使います。
• エクスポート操作は、ユースケースで必要な場合に限り追加します。クエリ結果の exportAs または useExport フック（CSV、JSON、Parquet、XLSX）を使い、クリック操作から開始します。Blob URL、非表示のアンカー、COPY TO によるエクスポートは作成しないでください。
• Dive の SQL は読み取り専用です。レコードの承認、フォームの送信、パイプラインの更新などの操作では、Dive の所有者が制御する Flight を useRunFlight でボタンから開始し、@motherduck/react-sql-query の useFlightRun で追跡します。Flight ID はハードコードし、文字列の設定値のみを渡し、実行中はコントロールを無効にし、フックの error を表示し、実行が成功したら影響を受けるクエリを再実行します。閲覧者には run の権限付与が必要です。付与対象を提案し、ユーザーの確認後にのみ権限を付与してください。埋め込み Dive では Flight を実行できません。
• 閲覧者は Dive ヘッダーの AI Chat を開けます。AI Chat は Dive のクエリ、データ、現在のフィルターを参照でき、変更内容がバージョン履歴に保存される形で Dive を編集できます。セクション名、クエリ名、Dive の説明を明確にすると、回答の質が向上します。
• バックエンドで作成した埋め込みセッションを使い、読み取り専用の Dive をライブ表示する必要があるプロダクトでは、埋め込み Dive を第一の選択肢とします。カスタム API コントラクト、書き込み、Dive 以外のルーティング、テナントポリシーの適用、またはより高度な認可が必要なアプリでは、motherduck-build-cfa-app に移行します。
• 共有リポジトリや CI/CD では、Dive の所有権が特定のユーザー個人に紐づかないよう、サービスアカウントトークンを使います。

ワークフロー

1. 求められている提供方法を選択します。ワークスペースのDive、既存の編集、Dives-as-code、書き戻しアクション、共有、埋め込みのいずれかです。その方法だけに従ってください。グラフのリクエストだけでは、共有、埋め込み、書き戻しは許可されません。
2. 実際のスキーマを調べ、まずコアSQLを検証します。
3. MCPを利用できる場合はget_dive_guideを呼び出してから、ストーリー、セクション、インタラクション、テーマを設計します。
4. 可能であればローカルプレビュー／ホットリロードを使い、Diveコンポーネントを作成または編集します。
5. クエリ、ローディング状態、必要なリソース、表示上の動作が正しいことを確認してから、save_dive、update_dive、またはデプロイを実行します。
6. 返されたURL、バージョン、ステータスを読み取って確認します。求められている提供方法に公開が含まれる場合は、書き込み可能な方法で、検証済みのDraftをReadyに昇格させます。
7. チームメイトまたはアプリケーションのユーザーがアクセスする必要がある場合は、次の3点を確認します。Diveを表示できること、REQUIRED_DATABASESの各項目が閲覧可能な共有であること、Diveが実行する各Flightに対してrun権限を持っていることです。所有するデータベースの既存の共有（MD_INFORMATION_SCHEMA.OWNED_SHARES）を優先してください。ユーザーがDiveのデータを組織全体と共有するよう求めた場合、share_dive_dataは組織スコープの共有を作成し、1回の呼び出しでDiveを更新します。対象を限定する場合はmotherduck-share-dataを使用し、アプリケーションのユーザーには埋め込みセッションのフローを使用してください。

回答、レビュー、計画の依頼では、求められた設計またはコード成果物の作成までで止めます。作成、更新、デプロイの依頼では、プレビューと検証を経て、依頼の範囲内で求められた操作を実行します。破壊的な置き換えや、依頼で許可されていない、より広範な外部公開を行う前には確認してください。

参考資料

現在のタスクに必要な参考セクションだけを読みます。

• 作成ワークフロー、useSQLQueryの仕組み、Dives-as-code、編集／バージョン履歴、共有、埋め込み、Flightsを使った書き戻し、Agent Chat、SQL関数、テーマ設定プロンプト、チャート選択のルール、ローディング／エラー状態、レイアウトパターン、実装上の注意点については、references/DIVE_DESIGN_GUIDE.mdを読んでください。

関連スキル

不足している機能に限って関連スキルを読み込み、確立済みのコンテキストを再利用します。

• 可視化の前に実際のテーブル、ビュー、ディメンションを見つけるには、motherduck-exploreを使用します。
• 各Diveセクションで実行するSQLを検証するには、motherduck-queryを使用します。
• モバイルファーストのレイアウト、ライト／ダークテーマ、フィルター表示、再利用可能なコンポーネント、レスポンシブQAには、motherduck-design-diveを使用します。
• 実際の作業が複数セクションのダッシュボード構成である場合は、motherduck-build-dashboardを使用します。
• 顧客ごとの分離やバックエンドのポリシー制御を備えた、より本格的なプロダクト画面が必要な場合は、motherduck-build-cfa-appを使用します。
• エージェントがシェルを利用でき、Diveのソースをローカルファイルに保持する場合は、motherduck-cliを使用します。
• 書き戻しボタンが実行するFlightには、motherduck-create-flightを使用します。
• 再利用可能な個人または組織のDive規約には、motherduck-manage-guidesを使用します。