AI Catalog — デザイン原則とビジョン

目的

このドキュメントでは、AI Catalog とは何か、何ではないか、そしてその中で行うすべてのデザインとエンジニアリングの意思決定を導く原則を定義します。カタログに貢献するすべての人が、トレードオフを判断する前に意図をすり合わせるための参照点となることを目的としています。

カタログとは

AI Catalog は、ユーザーが GitLab 上で AI 搭載オブジェクトを発見、評価、設定、有効化するための中心的な場所です。これらのオブジェクトを作成するビルダーと、それらを活用したいユーザーやチームをつなぐレイヤーです。

カタログは、次の 4 つの異なる役割を果たします。

カタログに含まれるもの

カタログには 3 種類のオブジェクトがあります。それぞれに独自の詳細ページがあり、エージェントやフローの構築と実行において独自の役割を持ちます。

1. エージェント — 定義された役割、ツール、システムプロンプトを持つ自律型 AI エンティティです。ユーザーはエージェントとチャットしたり、フローに追加したりでき、エージェントは目的に特化した出力を生成します。
2. フロー — 複数のエージェントを調整し、エージェント間でコンテキストを受け渡すオーケストレーターです。トリガーされると実行され、GitLab の他の機能と連携できます。
3. MCP（Model Context Protocol サーバー）— エージェントが読み取りまたは書き込みできる外部サービスです。エージェントがアクセスできる範囲を拡張します。

カタログではないもの

設定パネルではない

カタログは、一般的な管理設定エリアではありません。ユーザーが AI 搭載アイテムを発見、評価、有効化、管理する場所です。GitLab インスタンスやグループの管理設定は別の場所にあります。

ドキュメントハブではない

カタログは、有効化を判断するために十分な情報を表示します。関連する場合はドキュメントへのリンクを提供しますが、ドキュメントを置き換えたり複製したりはしません。詳細なリファレンス資料は別の場所にあります。

モニタリングダッシュボードではない

利用メトリクスと実行データは、主要な可観測性ツールとしてではなく、評価を支援するためにカタログに表示されます。詳細な運用状況を把握する必要があるユーザーは、Sessions または専用の可観測性ツールを利用してください。

デザイン原則

これらの原則は、カタログ内で行われるすべてのデザインとエンジニアリングの意思決定に適用されます。提案された変更が原則と矛盾する場合、その矛盾についてチームで議論し、解決する必要があります。

1. 発見可能性を最優先する

• ユーザーがカタログを探そうと決める前から、カタログにアクセスでき、理解できるようにする必要があります。発見は評価の一部ではなく、評価とは異なるデザイン上の問題です
• 積極的に宣伝する前に、カタログには関連性が高く質の高いアイテムが揃っている必要があります。品質を伴わない宣伝は、発見の促進ではなくスパムと受け取られます
• 空またはアイテムが少ないカタログビューでは、スペースを人為的に埋めるのではなく、何が存在し、どのように貢献できるかをユーザーが理解できるようにすることを優先します
• ここでの成功は、欲しいものをすでに知っているユーザーが検索できるかどうかだけではなく、既存のアイテムから恩恵を受けられるユーザーが実際にそれを見つけて利用できたかで測定します

2. 有効化の前に評価する

カタログは、有効化をできるだけ速くするためではなく、ユーザーが適切に有効化を判断できるようにするために存在します。すべてのページは「どう使うのか」に答える前に、「これを使うべきか」に答える必要があります。

• ユーザーが最初に抱く疑問は「これは何をするのか」です。アイテムの目的と動作を理解できるようにすることは、どのような信頼性のシグナルよりも優先されます
• 信頼性のシグナル（誰が構築したか、何にアクセスするか、どのように機能するか）は、有効化の操作前に表示する必要があります
• 設定の詳細は評価シグナルよりも優先度が低く、判断を先導するものではなく、支援するものです
• 有効化の操作は、偶発的ではなく意図的なものだと感じられる必要があります

3. 洗練より透明性を優先する

ユーザーは、自分で確認できるものを信頼します。カタログでは、昇格された権限を必要としたり別の場所へ移動したりすることなく、アイテムが何を行い、何にアクセスでき、実行時に何が起きるかを簡単に確認できるようにする必要があります。

• システムプロンプト、ツールリスト、データアクセススコープは、詳細ページでデフォルトで表示する必要があります
• 利用状況とパフォーマンスのデータ（実行回数、成功率、有効化されたスコープ）は、主要なシグナルとして表示する必要があります
• ユーザーが表示されると期待するデータがある場合があります。そのデータを非表示にする場合は、理由を説明する必要があります。
• AI Catalog のアイテムがクレジットやコンピューティングリソースなどの従量制リソースを消費する場合、その消費量を表示する必要があります

4. 用語には重みがある

ユーザーは他のプラットフォームの用語にすでに慣れていることが多いため、AI Catalog のすべてのラベル、セクション見出し、説明文は、ユーザーの理解を調整する機会にも混乱させる原因にもなります。AI Catalog は、多くの場合 DAP の概念モデルとの最初の接点となるため、用語を慎重に選ぶ必要があります。DAP 用語の正式な定義については、DAP Glossaryを参照してください。

• 用語が誤解される可能性がある場合は、ラベルに短い説明を添える必要があります
• 「Flow」「Agent」「Trigger」「MCP」「Skill」は、近くにコンテキストを示さず、単独のラベルとして表示してはいけません
• 「workflow」と「user flow」という用語は、AI Catalog のコンテキスト内で使用してはいけません。GitLab Flows と混同されるためです
• 「Flow」は GitLab の Flow オブジェクトだけを指すために使用し、それ以外の意味での使用は避ける必要があります

5. スコープを常に明示する

AI Catalog は、GitLab の 3 つの領域、Explore エリアと、ユーザーがメンバーになっている Group および Project で提供されます。AI Catalog の機能では、Project でアイテムを有効化するときなど、ユーザーが影響を与えるスコープを明示する必要があります。

• 技術的要件やセキュリティ要件によって、ユーザーにとっての使いやすさが損なわれる場合があります。こうした制約は、操作する場所のできるだけ近くで、ユーザーの視点から伝える必要があります

6. 装飾より情報密度を優先する

カタログの対象者はビルダーです。ページには有用な情報を密に配置し、それ以外の要素を最小限に抑える必要があります。

• ステータス表示は状況に自然に溶け込むものにします。必要なときには表示し、不要なときには表示しません（例: エージェントがアクティブな場合は「最終実行: 2 分前」バッジを表示し、一度も実行されていない場合は非表示にします）
• 空の状態でも情報を提供する必要があります。「0 セッション」という表示は、セクションが存在し、追跡が機能していることを確認できるため有用です。セクションを完全に省略すると、何も追跡されていないように見えます

7. 責任の共有をデザイン上の課題として扱う

カタログは、すべての関係者が責任の所在を理解できるように、来歴の全体像を示す必要があります。

• 誰が構築し、誰が管理し、どこで有効化され、何にアクセスできるかをすべて表示する必要があります
• 有効化では責任の範囲を明確にする必要があります。Group レベルでの有効化は、Project レベルでの有効化とは異なる影響を持ちます
• 監査情報とアクセス情報は、ビルダーだけでなく、関連する役割のユーザーがアクセスできる必要があります

8. エージェントの構築と保守は個人ではなくチームの活動である

カタログの「設定」という役割は、時間の経過とともに複数の人がアイテムを保守することを前提としています。これはこれまでカタログのデザインに暗黙的に含まれていましたが、明示する必要があります。

• 所有権と編集権限では、エージェントやフローごとに 1 人の所有者だけでなく、名前が明示された複数のコラボレーターをサポートする必要があります
• バージョン履歴と変更の帰属は、元のビルダーだけでなく、すべてのコラボレーターが確認できる必要があります
• カタログでは、他に誰がアイテムを編集または保守できるかを明確にする必要があります。

ページのソースコードを見る - ページの編集 - please contribute.