motherduck-manage-guides

MotherDuck Guides の管理

信頼できる情報源

• 最新の MotherDuck Guides ドキュメントと MCP ツールの説明を優先してください。
• MCP を介して分析クエリを実行する場合は、SQL を作成する前に get_query_guide を呼び出し、その後、関連するトピックと Guides のみをたどってください。
• get_dive_guide と get_flight_guide には、予約済みの dives と flights トピックの概要が自動的に含まれます。より詳しい情報が必要な場合を除き、それらのトピックを個別に読み込まないでください。

基本方針

• ガイダンスが広く適用される場合に限り、短いルートオリエンテーション Guide を 1 つ維持してください。ドメイン固有の知識は、階層の浅い説明的なトピックに配置してください。
• 新しい Guides は、デフォルトで access = 'user' にしてください。組織での公開には明示的なリクエストと必要な管理者権限が必要です。set_guide_access（MCP）または motherduck guide push の --access で変更してください。
• Flights が作成するテーブルについては、作成規約を扱う flights ではなく、data-sources トピックに記載してください。ソース、目的、粒度、主要な列、変換、更新の動作、注意事項を含め、テーブル、それを生成する Flight、利用する Dive への参照を記載してください。テーブルのデータベースに所有する共有がある場合は organization アクセスを、それ以外の場合は user アクセスを使用してください。
• 各 Guide には一貫したテーマを 1 つだけ扱い、内容を区別できるタイトルと説明を付けてください。ルール、検証済みの SQL、名前付きの落とし穴を先に記載してください。
• エージェントが適切なタイミングで見つけられるよう、内容の対象となるデータベース、共有、スキーマ、テーブル、列、Dives、Flights、Guides への参照を付けてください。
• Guide を信頼できるものとして提示する前に、参照先のオブジェクトと実行可能な SQL をライブワークスペースで検証してください。
• ガイダンスを変更した理由は、バージョンコメントで説明してください。更新前に内容を読み、同時に行われる変更を上書きしないようにしてください。
• シェルを利用でき、Guides を Git で管理する場合やコードのようにレビューする場合は、motherduck guide（motherduck-cli を参照）を使用してください。guide.md をローカルで編集し、--version-description を指定して push し、各バージョンが変更にたどり着けるよう、コミット SHA を --external-id に渡してください。

ワークフロー

1. get_query_guide または list_guides を確認し、表示されるトピックツリーを把握して重複を避けます。
2. 変更案を作成する前に、関連する Guide のバージョンと参照先オブジェクトを読みます。
3. 役立つ範囲で最も限定的なトピックを選びます。トピックを空のままにするのは、組織全体のオリエンテーションに限ります。
4. ビジネス用語と正確なカタログオブジェクトおよび検証済みの SQL を対応付けた、簡潔な Markdown を作成します。
5. 作成または更新のリクエストでは、MCP または文書化された SQL 関数を使って変更を適用し、読み戻して確認します。
6. メタデータ、アクセス権、参照、現在のバージョン、変更コメントを検証します。クエリ作業では Guide に従い、さらに生成された SQL をライブスキーマに照らして検証します。

回答、レビュー、計画のリクエストでは、Guide を作成または変更せずに調査し、草案を作成してください。明示的な作成・更新のリクエストでは、対象範囲内の変更を実行して検証してください。削除や、許可された対象を超える公開範囲の拡大については、事前に確認してください。組織への公開を明示的にリクエストされた場合、その対象への公開は許可されています。ただし、管理者権限が必要です。

参考資料

現在のタスクに必要な参考資料のセクションのみを読んでください。

• トピック設計、アクセスガバナンス、参照、MCP／SQL の操作、バージョン管理、品質チェックについては、references/GUIDES_PLAYBOOK.md を読んでください。

関連スキル

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

• 参照先のカタログオブジェクトを検証するには motherduck-explore
• SQL をテストし、Guide に沿った分析を適用するには motherduck-query
• 予約済みトピックの規約については motherduck-create-dive と motherduck-create-flight
• 組織での公開範囲と権限の境界については motherduck-security-governance