analytics

アナリティクス

GrowthBook のプロダクトアナリティクス、アナリティクスダッシュボード、メトリックカタログのドメインルーターです。ワークフローは references/ にあります。このルーターを読み、ワークフローを1つ選んでから、そのファイルを読み、手順に従ってください。

アナリティクスでは v1 API を使用します。探索には /api/v1/product-analytics/search、/columns、/column-values、チャートにはメトリック、ファクトテーブル、データソース、ファネルの各 /api/v1/product-analytics/*-exploration エンドポイント、ポーリングには /api/v1/product-analytics/explorations/:id、チャートを保存するページには /dashboards（作成のみ例外で POST /api/v2/dashboards を使用します。v1 の作成エンドポイントは非推奨です）、カタログには /fact-metrics と /fact-tables を使用します。API では SQL エクスプロレーションも利用できますが、このスキルでは任意の SQL エクスプロレーションのペイロードを作成または実行しません。

すべての API 呼び出しは、同梱のヘルパーを経由します。Claude Code プラグインのインストールでは、ヘルパーは ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call（プラグインのルート）にあります。npx skills install では、このスキルのディレクトリを基準とする scripts/gb-call にあります。このパスを一度解決し、リファレンスの例で gb-call と記載されている箇所では、そのたびに解決したパスに置き換えてください。gb-call が PATH 上にあるとは限りません。まず環境変数から GB_API_KEY を読み取り、次に ~/.config/growthbook/.env（gb-setup によって書き込まれます）にフォールバックします。環境変数が優先されます。

ワークフローでルート相対パスから GrowthBook の UI リンクを作成する必要がある場合、シェルを実行できるランタイムでは、会話ごとに gb-call app-origin を一度呼び出し、返された信頼できるオリジンをワークフロー間およびドメイン間の引き継ぎを通じて保持し、各パスの先頭に付加してください。オリジンがすでにコンテキストにある場合は再利用し、リンクごとにコマンドを呼び出さないでください。信頼できるアプリのオリジンがすでにわかっている組み込みアダプターや MCP アダプターでは、パスを直接解決できます。GB_API_URL からアプリのオリジンを決して導出しないでください。セルフホストの設定が不完全なために app-origin が拒否された場合は、gb-setup に誘導してください。API から返される explorationUrl の値はすでに完全な URL なので、変更せずに使用してください。

ワークフローを選ぶ

こちらを読む	ユーザーが望んでいること
references/metric-search.md	指標やファクトテーブルを閲覧、検索、監査すること — 一覧の確認、特定の定義の確認、または「何をグラフ化できるか」という初期調査（読み取り専用）
references/metric-create.md	ファクト指標を作成すること。必要に応じて、まず基盤となるファクトテーブルを作成します（設定を書き込みます）
references/analytics-explore.md	実際にグラフを実行し、数値と詳細リンクを報告すること
references/dashboard-create.md	新しいダッシュボードを作成すること — 複数のグラフを1ページにまとめて保存します（ダッシュボードを書き込みます）
references/dashboard-edit.md	既存のダッシュボードを変更すること：グラフの追加や削除、指標の切り替え、期間の変更、名前の変更
references/sql-query.md	指標や探索では質問に答えられない場合に、ウェアハウスに対してアドホックな SQL を実行すること（最後の手段）

まだ解決していない指標の名前をユーザーが挙げた場合は、まず metric-search.md を読んでください。これにより、analytics-explore または metric-create に安定した定義を渡せます。具体的なものがすでに指定されていて、数値だけを求めている場合は、直接 analytics-explore.md に進んでください。

グラフは1つですか、それとも複数ですか？質問が1つなら、analytics-explore でグラフを1つ作成します。「追跡」「監視」「レポート」や、監視対象を2つ以上まとめて扱う場合は、ダッシュボードを使います。ダッシュボードが存在するかどうかで振り分けます。まだ ID がない場合は dashboard-create、ID がある場合は dashboard-edit です。

既存の指標や探索設定では質問に答えられない場合に限り、sql-query.md を使ってください。たとえば、独自の結合、モデル化されていないテーブル、探索では表現できない集計などの場合です。

共通の規約

• 事実メトリクスのチャートのみです。 fact__... ID は Product Analytics で使用できます。/api/v1/metrics の旧形式の met_... メトリクスは実験メトリクスとしては有効ですが、チャートにはできません。チャートを作成できると約束しないでください。
• 探索はデータソースごとに実行され、データソースは SQL ウェアハウスである必要があります。 Mixpanel と Google Analytics のデータソースでは探索を実行できません。
• ワークフロー間では表示名ではなく ID を渡してください。 名前は一意ではありません。事実メトリクス ID は必ず fact__ で始まります。事実テーブル ID は通常 ftb_... で始まりますが、カスタム ID も使用できるため、このプレフィックスで絞り込まないでください。
• すべての ID は検索で取得するか、ユーザーの @ メンションから取得してください。決して自分で作らないでください。 fact__demo-d7-purchase-retention のように読みやすく、fact__AverageOrderValue のように推測したくなる ID もありますが、そのような ID は何も見つからず、失敗が遅れて分かりにくい形で表面化します。
• 構築する前に調べてください。 Product Analytics の検索とカラムを使用し、具体的なフィルター値や内訳値を使う前に column-values を呼び出してください。値を決して推測しないでください。
• 作成する前に確認してください。 同じ意味のメトリクスを重複して追加するより、既存の official: true メトリクスを優先してください。
• 探索 POST の 200 は必ずしも成功を意味しません。 exploration.status に基づいて処理を分岐してください。running 状態の探索は ID を指定してポーリングし、error を表示してください。また、cache=required では exploration: null が返される場合があることに注意してください。
• ワークフローエンドポイントの 404 は慎重に扱ってください。 /product-analytics/search の 404 は、サーバーがこれらのエンドポイントより古いことを意味します。/columns、/column-values、または /explorations/:id では、リソースが見つからないかアクセスできないことを意味する場合もあります。失敗を表示して停止してください。アクセス制御を回避するために調べたり、文書化されていないエンドポイントで代用したり、実行中の探索を再度 POST したりしないでください。
• 数値の分析には、返された完全な結果行を使用してください。 チャートのプレビュー、切り詰められた概要、または設定から値を推測しないでください。
• ユーザーの 1 回のターンで成功させるチャートは最大 1 つです。 検索、ポーリング、結果が空だった場合の再試行 1 回は可能です。空でない探索が 1 つ成功したら、ユーザーが後のターンで別のチャートを明示的に求めない限り、その結果に基づいて回答してください。
• すべての dataset.values[] エントリで unit を必ず明示してください。 unit を指定できるのはこの階層のみです。設定自体に unit を指定すると拒否されます。メトリクスの場合は /columns の内容に厳密に従ってください。metrics[].needsUnit が true の場合は、返された userIdTypes の値を選択し、false の場合は null を既定値とします。unit は識別子の種類であり、currency のような値の形式ではありません。サーバーが不足している unit を補うことはありません。
• 日付範囲の predefined は、どこに指定する場合でも次の固定リストから選択してください。 today、yesterday、last7Days、last30Days、last90Days、last12Months、lastCalendarYear、customLookback、customDateRange。それ以外の名前は拒否されます。リストにない期間はすべて lookbackValue と lookbackUnit（hour、day、week、month）を指定した customLookback にしてください。
• dimensionType に指定できる値は固定されており、"dimension" は含まれません。 date、dynamic、static、slice のみです。最初の 2 つだけがサポートされています。日付軸には { "dimensionType": "date", "column": null, "dateGranularity": "auto" } を使用し、カラムによる内訳には { "dimensionType": "dynamic", "column": "browser", "maxValues": 5 } を使用してください。グループ化したい対象の名前をそのままフィールド名にするのは推測とみなされ、バリデーターに拒否されます。
• 拒否された呼び出しを、変更せずに再送信しないでください。 400 は決定的です。同じ本文を送れば同じエラーが返るため、メッセージで示されたフィールドを変更せずに再試行しても、ユーザーのターンを無駄にするだけです。body.message を読み、そこに示された内容だけを修正して、もう一度だけ送信してください。有効な値がメッセージに示されていない場合、または同じフィールドが 2 回拒否された場合は、そこで停止してください。どのフィールドで失敗したか、何を試したかを伝え、推測で 3 回目を試さずにユーザーに尋ねてください。尋ねるのはそのフィールドについてです。検証エラーは拒否したフィールドを示します。別のフィールド（カラム名やメトリクスの選択など）について質問しても問題は解決されず、回答を得た後に同じ呼び出しが再び失敗します。
• チャートのスタイル変更は無料です。 キャッシュ照合では chartType が無視されるため、同じクエリで別のチャートタイプを指定するとキャッシュヒットになります。スタイル変更だけのために再クエリしないでください。
• ダッシュボードのチャートブロックに含まれるのは結果ではなく config です。 作成と更新の呼び出しではすべてのチャートがサーバー側で実行されるため、タイル用の ID を取得する目的で、先に探索を POST しないでください。
• 更新すると、ダッシュボードのブロックリスト全体が置き換えられます。 読み取りと書き込みは同じターン内に行い、残すタイルをすべて列挙してください。ただし、変更しないタイルは全体をコピーして戻すのではなく、{ "id": "dshblk_…" } として渡してください。同じ ID を複数回列挙しないでください。
• ダッシュボードの owner を変更するのは、ユーザーが依頼した場合のみです。 ユーザーが別の所有者を指定しない限り、owner を含めずに POST /api/v2/dashboards で作成してください。既定では API キーのユーザーが所有者になります。ダッシュボードの所有者変更をユーザーが依頼しない限り、更新本文に owner や ownerEmail を含めないでください。管理者の場合、誤って owner を指定すると、ダッシュボードが別のユーザーに黙って譲渡されます。
• ダッシュボードは、メトリクスや探索のようにデータソース単位ではありません。 ただし、ダッシュボード上のすべてのチャートはデータソースに紐づきます。

読み取り専用と書き込み

metric-search は厳密に読み取り専用です。analytics-explore はデータウェアハウスのクエリを実行しますが、GrowthBook の設定は変更しません。指標、ファクトテーブル、ダッシュボードは作成しません。sql-query も同様にデータウェアハウスのデータを変更しませんが、コストがかかる可能性のあるクエリを実行し、その結果から GrowthBook の探索オブジェクトを保存します。metric-create は組織内で表示されるファクトテーブルとファクト指標の定義を書き込み、dashboard-create と dashboard-edit はダッシュボードを書き込みます。この3つはすべて、変更内容を平易な言葉で要約し、書き込みの前に毎回確認を得る必要があります。

探索では実際のデータウェアハウスクエリが実行されるため、何も書き込まなくてもユーザーにコストと時間がかかります。また、ダッシュボードへの書き込みでは、チャートブロックごとに1つのクエリが実行されます。推測で対象を広げず、リファレンスファイルの説明に従って範囲を設定してください。

引き継ぎ

• experiments スキル — 質問が A/B テストの分析結果に関する場合、またはチャートからテストする価値のある事柄が見つかった場合。
• feature-flags スキル — ユーザーがデータの対象となっているもののリリースやゲーティングに話題を移した場合。
• gb-setup — gb-call が GB_API_KEY の欠落または無効を報告した場合。