experiment-analyze

experiment-analyze

結果を取得し、キャッシュデータが24時間を超えて古い場合、またはユーザーが異なるフェーズ／ディメンションでの切り分けを希望する場合にのみスナップショットを更新してから、解釈します。条件付きポーリングループと統計的な解釈を伴うため、このスキルはカタログ内で最も負荷が高いものです。ペースを落とし、各手順を慎重に進めてください。

すべての API 呼び出しは、同梱のヘルパーを経由します：${CLAUDE_PLUGIN_ROOT}/scripts/gb-call。GB_API_KEY が必要です。シェルに設定するか、/growthbook:gb-setup によって ~/.config/growthbook/.env に書き込んでください。未設定または無効の場合、gb-call のエラーメッセージに /growthbook:gb-setup への案内が表示されます。このスキルでは、ポーリング呼び出しの間に sleep も使用します。

ワークフロー

1. 結果と実験メタデータを1回の呼び出しで取得します。 /results は { experiment, result } を返します。GrowthBook UI の結果ビューと同じペイロードなので、メタデータを別途呼び出す必要はありません。

   ユーザーが ID ではなく名前（「チェックアウトのテスト」など）を指定した場合は、まず名前から解決します。q は名前、トラッキングキー、説明、仮説を対象に検索します：

   gb-call GET '/api/v1/experiments?q=checkout&sortBy=dateUpdated&sortOrder=desc&limit=10'
   

   該当する可能性のある実験が複数ある場合は、候補を一覧表示してユーザーに選んでもらってください。推測してはいけません。

   gb-call GET /api/v1/experiments/<experiment-id>/results
   # or, when the user asks for a specific phase / dimension cut:
   gb-call GET '/api/v1/experiments/<experiment-id>/results?phase=1&dimension=exp:country'
   

   phase と dimension のクエリパラメーターは、その設定で取得した最新のスナップショットに絞り込みます。デフォルトの「状況はどうですか」というビューでは、どちらも省略します。

   experiment から次の情報を取得します：

   • status — running と stopped はどちらも分析対象として適切です。draft の場合、解釈できる結果はありません。その旨をユーザーに伝えてください。
   • type — "multi-armed-bandit" の場合は処理を中止し、このスキルは標準的な A/B テストを対象としていることをユーザーに伝えてください。バンディットは異なる形式（アームごとの確率、動的なトラフィック割り当て）でレポートされるため、標準的な勝者／敗者の枠組みで解釈すべきではありません。
   • settings.statsEngine — "bayesian"（デフォルト）または "frequentist" です。以下の指標解釈手順で使用します。
   • regressionAdjustmentEnabled（CUPED）と sequentialTestingEnabled — 報告内容に影響します。

   result から次の情報を取得します：

   • id — スナップショット ID です。更新が必要な場合、手順3で使用します。
   • dateUpdated — このスナップショットが作成された日時を示す ISO タイムスタンプです。手順2で古さを判定するために使用します。
   • バリエーションごとの指標データ（リフト推定値、区間、サンプルサイズ）— 手順4で解釈する対象です。

   "No results found for that experiment" というエラーが応答に含まれる場合、実験は開始されていますが、スナップショットがまだ存在しません（自動更新が実行されていないか、スナップショットを一度も作成していないフェーズ／ディメンションで絞り込んでいます）。手順2をスキップし、手順3に進んでください。

2. 更新するかどうかを判断します。 result.dateUpdated に基づいて分岐します：

   • 24時間以内で、既存のスナップショットがユーザー指定のフェーズ／ディメンションと一致する場合 → 手順3をスキップし、手順4に進みます。
   • 24時間を超えて古い場合、またはユーザーが明示的に新しいスナップショットを依頼した場合 → 手順3に進みます。

   サーバーはデフォルトで6時間ごとにスナップショットを自動更新します（EXPERIMENT_REFRESH_FREQUENCY）。そのため、24時間以内のデータは通常、最近少なくとも1回は更新されています。24時間という基準は意図的に慎重な設定です。データが変わっていない状態で、スナップショット計算の予算を消費しないでください。

3. 新しいスナップショットを作成してポーリングし、その後、結果を再取得します。

   3a. スナップショットを POST します。 任意のリクエストボディフィールドで計算対象を指定できます。手順1でユーザーが指定したものと同じ phase／dimension を渡してください：

   • phase（整数、0始まり）：実験に複数のフェーズがある場合は、特定のフェーズを選択します。たとえば、実験が段階的に拡大された後で、拡大前のフェーズを再分析できます。デフォルトは最新のフェーズです。
   • dimension（文字列）：結果を分類します。組み込みの値は "pre:date"、"pre:activation" です。設定済みの Unit Dimension にはその ID（例："dim_abc123"）を使用します。Experiment Dimension には "exp:" を付けます（例："exp:country"）。

   echo '{}' | gb-call POST /api/v1/experiments/<experiment-id>/snapshot -
   # or with phase + dimension:
   echo '{"phase": 1, "dimension": "exp:country"}' \
     | gb-call POST /api/v1/experiments/<experiment-id>/snapshot -
   

   応答は { snapshot: { id, experiment, status } } です。snapshot.id を取得してください。

   3b. 完了するまでポーリングします。 スナップショットの作成は非同期です：

   for i in $(seq 1 60); do
     gb-call GET /api/v1/snapshots/<snapshot-id>
     # Parse snapshot.status. Stop when it is "success" or "error".
     sleep 5
   done
   

   ループは60回（5分）で打ち切ります。それまでに完了しない場合は、ポーリングを停止し、スナップショットの作成がまだ進行中であることをユーザーに伝えます。数分後にスキルを再試行できます。無限にループしないでください。

   3c. 結果を再取得するには、3aで使用したものと同じフェーズ／ディメンションの引数を指定し、手順1に記載されたフィールドを再取得します。

   gb-call GET '/api/v1/experiments/<experiment-id>/results'
   # or, if 3a passed phase/dimension:
   gb-call GET '/api/v1/experiments/<experiment-id>/results?phase=1&dimension=exp:country'
   

4. まずデータ品質チェックを実行してから、結果を解釈します。 GrowthBook には6つのヘルスチェックがあります。いずれかに失敗した場合は、結果の読み方が変わります。失敗は目立つように示し、埋もれさせないでください。

   データ品質チェック（順番どおり）：

   • SRM（サンプル比率の不一致）。 実際のトラフィック分割と設定された分割を比較します。失敗すると後続の結果は無効になります。そのことを目立つように伝え、ユーザーがバイアスのリスクを理解するまで解釈を中止してください。よくある原因：ボットトラフィック、クライアント側トラッキングをブロックする広告ブロッカー、実験途中でのターゲティング変更、アクティベーション指標のバイアス。
   • 複数バリエーションへの露出。 複数のバリエーションに割り当てられたユーザーを示します。発生率が低い場合（<1%）は通常問題ありません。高い場合は、スティッキーバケットが設定されていないか、ハッシュ属性が安定していない可能性があります。
   • データの最小しきい値。 指標ごとに設定された最小値です。指標がしきい値を下回る場合、その指標の結果はまだ信頼できません。
   • バリエーション ID の不一致。 露出データで報告されたバリエーション ID が、実験で設定されたバリエーションと一致しません。トラッキングまたは設定の不具合を示しています。
   • 不審なリフト。 指標ごとのリフトが、設定された不審値のしきい値を超えています。結果が誤りだという意味ではありませんが、このような大きなリフトが実際に発生するのはまれです。通常は、トラッキングまたは指標定義の問題が原因です。
   • ガードレール。 ドキュメントではデータ品質チェックに含まれていますが、ガードレールの失敗はリリースを中止すべき重大な警告です。それぞれについて、悪化がないか確認してください。ガードレールで統計的に有意でない悪化があった場合も、指摘する価値があります。注：設計上、ガードレールには多重比較補正が適用されません。

   検出力の確認。 実験は想定サンプルサイズに達しているか、近づいていますか？ 大幅に不足している場合（例：計画の<50%）、特に頻度論エンジンでは、途中で結果を確認することで偽陽性率がより大きく上昇するため、結論は推測にすぎないと警告してください。ベイズ結果は途中確認に対してより頑健ですが、それでも計画したサンプルサイズを確保することが望ましいです。

   主要指標 — 統計エンジンに応じて分岐：

   • ベイズ（settings.statsEngine === "bayesian"、デフォルト）： 勝つ確率（データと事前分布を前提に、処置群が対照群を上回る確率）と相対リフトの分布（点推定値＋信用区間）を報告します。GrowthBook では、勝つ確率が>95%の場合は強い正のシグナル、<5%の場合は強い負のシグナル、それ以外は判断不能とみなします。p値を捏造しないでください。
   • 頻度論（settings.statsEngine === "frequentist"）： リフトの点推定値、95%信頼区間、信頼区間がゼロをまたぐかどうかを報告します。regressionAdjustmentEnabled が true の場合（CUPED）、点推定値は生の平均値と異なることがあります。信頼区間は通常、より狭くなります。sequentialTestingEnabled が true の場合、途中確認を安全に行えるよう信頼区間が意図的に広くなっています。ユーザーが逐次検定を使用しない信頼区間と比較しないよう、その旨を伝えてください。

   副次指標。 示したうえで、探索的な結果であることを明記してください。頻度論エンジンでは多重比較のリスクがあります（GrowthBook は頻度論エンジンでのみ補正を適用します。ベイズでは事前分布によって暗黙的に補正されます）。主要指標に変化がなかった場合、副次指標について「Xで勝った」と結論づけないでください。

   ディメンション（ユーザーが求めた場合）。 スナップショット取得時に dimension を指定している場合、結果エンドポイントはディメンションごとの内訳を返します。目立った差異は示しますが、都合のよい結果を探さないでください。ディメンション分析では比較数が増加します。

5. 結果を提示します。 以下の形式を使用します（該当しない行は省略します）。

   ## Experiment: <name> (<id>)
   - Status: <running|stopped>
   - Type: <standard|multi-armed-bandit>
   - Stats engine: <bayesian|frequentist>
   - Adjustments: <CUPED on/off, sequential testing on/off>
   - Phase: <phase name or index>
   - Dimension: <none | dimension id used>
   - Sample size: <total users> across N variations
   - Snapshot timestamp: <when this snapshot ran>
   
   ### Data-quality checks
   - SRM: <pass / fail with detail>
   - Multiple Exposures: <pass / rate>
   - Minimum Data Thresholds: <met / not met, per metric>
   - Variation ID Mismatch: <pass / fail>
   - Suspicious Uplift: <none / per-metric flags>
   
   ### Primary metric: <name>
   - Variation 0 (Control): <baseline value>
   - Variation 1 (Treatment): <value>
   - **Bayesian:** Chance to Win <X%>, relative lift <±Y%>, 95% CrI [a, b]
   - **Frequentist:** lift <±Y%>, 95% CI [a, b]<note if CIs are sequential>
   - Verdict: <won / lost / inconclusive>
   
   ### Guardrails
   - <metric>: <safe / regressed by Y%>
   
   ### Secondary metrics
   - <metric>: <lift / no movement> <multiple-comparison caveat if frequentist>
   
   ### Recommendation
   <one paragraph: ship, kill, extend, or investigate>
   

6. 実験へのリンクを示してから、次のステップを提案します。 /results が返す内容に加えて、ライブ結果、ディメンションごとの内訳、過去のスナップショットをユーザーが確認できるよう、実験の直接リンクを必ず示してください。

   View in GrowthBook: <host>/experiment/<exp_id>
   

   GB_API_URL の api. を app. に置き換えて <host> を導出します（experiment-launch の規則に合わせています。デフォルトのクラウドホストでは https://app.growthbook.io になります）。

   次に、ステップ 1 の experiment.status に基づいて次のアクションを提案します。

   • running かつ結論が出ている場合 → 選択したバリエーションで experiment-stop を提案します。
   • running かつ結論が出ていない場合 → 待機または期間延長を提案します。
   • stopped の場合 → flag-targeting を使って、リンクされたフラグ上の experiment-ref ルールを更新または削除するフラグのクリーンアップを案内します。

ガードレール

• 6 つすべてのデータ品質チェックを、解釈より先に行います。 SRM、複数の露出、最小データしきい値、バリエーション ID の不一致、不審なリフト、ガードレールです。いずれかに失敗した場合、結果をどのように解釈するか（または解釈するかどうか）が変わります。主要指標の見出しの下に埋もれさせないでください。
• settings.statsEngine に基づいて解釈を切り替えます。 ベイズ法（デフォルト）では、勝つ確率と信用区間が報告されます。頻度論法では、リフトと信頼区間が報告されます。API が返していない p 値を捏造したり、ベイズ法の結果に「95% CI」と記載したりしないでください（これは信頼区間ではなく、信用区間です）。
• 多重比較補正は頻度論法でのみ行い、ガードレールは対象外です。 副次指標を報告する際は、補正の状況を記載してください。ベイズ法では事前分布による暗黙の縮小があるため、補正は適用されません。
• CUPED と逐次検定は、信頼区間の読み方を変えます。 regressionAdjustmentEnabled が true の場合、点推定値は生の平均値と異なることがあり、信頼区間は通常、より狭くなります。sequentialTestingEnabled が true の場合、信頼区間は意図的に広くなっています。その旨を伝え、逐次検定を行っていない結果と単純に比較しないようにしてください。
• 途中経過を見て判断しないでください。 検出力が不足している実験では、途中の数値は不安定です。頻度論法では途中経過を確認すると偽陽性率が上がります。ベイズ法はより頑健ですが、それでも計画されたサンプルサイズに達することが望ましいです。
• バンディットは対象外です。 type === "multi-armed-bandit" では、アームごとの確率が報告され、トラフィックが動的に再配分されます。処理を中止し、UI でバンディットの結果を確認するようユーザーに伝えてください。
• アクティベーション指標によるバイアスは、「SRM 合格」の陰に隠れることがあります。 バリエーション間の違いより下流にあるアクティベーション指標（例：バリエーションが登録完了に影響する場合の「登録完了」）を実験で使っていると、全体の割り当てに問題がないように見えても、アクティベートされたコホートにはバイアスが生じている可能性があります。ダッシュボードにはこの問題が表示されるため、メタデータにこのパターンが見られたら指摘してください。
• 副次指標を主要指標に昇格させないでください。 主要指標に変化がなければ、実験にも変化はありません。副次指標は探索的なものです。
• ポーリングには上限があります。 60 回 × 5 秒 = 5 分です。それまでにスナップショットが完了しなければ、停止して報告してください。何時間も実行しないでください。
• スナップショットのタイムスタンプは重要です。 結果を報告する際は、必ず result.dateUpdated を提示してください。ステップ 2 で更新が必要か判断するための情報であり、トラフィックの少ない実験に変化があったかをユーザーが判断する手がかりでもあります。古いスナップショットはよくあるため、隠さないでください。
• 24 時間は意図的に設けられた上限であり、自動更新の間隔ではありません。 サーバーはデフォルトで 6 時間ごとに自動更新するため、24 時間以内のスナップショットは、ほぼ必ず少なくとも 1 回更新されています。このスキルで 24 時間を基準としているのは、変化していないデータのスナップショット計算を避けつつ、ユーザーに実用的で保守的な時間幅を示すためです。「1 分以上前のデータはすべて」といった基準に変えないでください。そうすると、トラフィックの多い組織が 60 rpm の上限に達してしまいます。
• レート制限に注意してください。 通常は /results を 1 回呼び出すだけです。最悪の場合（スナップショットがない、または古いスナップショットに対し、60 回ポーリングして再取得する場合）でも、5 分間に約 63 回（約 13 回／分）であり、60 rpm を大きく下回ります。同じ組織で複数のユーザーが同時に実行すると、制限に達する可能性はあります。gb-call が 429 を返した場合は、明確に伝えてください。
• 読み取り専用です。 このスキルが実験を停止したり、変更したりすることはありません。ユーザーが操作を希望した場合は、experiment-stop に引き継いでください。
• q では否定や演算子が拒否され、400 エラーになります。 リストエンドポイントの q パラメーターはアプリの検索構文（status:running tag:checkout とフリーテキスト）を受け付けますが、!、~、^、>、<、= は明示的に拒否します。field:value 形式のトークンとフリーテキストのみを送信してください。
• 名前で検索する場合は、type ではなく bandits でバンディットを除外してください。 レスポンスの type フィールド（standard ／ multi-armed-bandit）はリスト検索のパラメーターではないため、type= を送ると 400 エラーになります。このスキルではバンディットが見つかると処理を中止するため、候補からバンディットを除外するには bandits=false を使ってください。（implementationType は別の軸で、リンクされた変更の種類を示します。）

使用するエンドポイント

• GET /api/v1/experiments?q=<text> — ユーザーが名前やキーワードだけを指定した場合に、実験 ID を解決します。q は名前、トラッキングキー、説明、仮説に一致します。アクティブな実験が先に表示されるように、sortBy=dateUpdated&sortOrder=desc を併用してください。
• GET /api/v1/experiments/<id>/results — 主なエントリーポイントです。{ experiment, result } を返すため、ステップ 1 ではメタデータ、ステータス、スナップショットのタイムスタンプ（result.dateUpdated）を 1 回の呼び出しで取得できます。phase / dimension クエリパラメーターを受け付けます。
• POST /api/v1/experiments/<id>/snapshot — 結果が 24 時間以上前のもの、またはキャッシュされたスナップショットに含まれないフェーズ／ディメンションの結果をユーザーが求めている場合に、新しいスナップショットを生成します。本文では phase（整数）と dimension（文字列）を受け付けます。
• GET /api/v1/snapshots/<snapshot-id> — スナップショットの完了を確認します（5 秒間隔、最大 60 回）。{ snapshot: { id, experiment, status } } を返します。

引き継ぎ

• experiment-stop — ユーザーが確定的な結果に基づいて行動する準備ができたときに引き継ぎます。
• flag-targeting — 勝者が決まって実験を停止した後、関連付けられたフラグがある場合は、その experiment-ref ルールを更新または削除する必要があります。
• experiment-brainstorm — 次のテストのアイデアを、過去の実験結果に基づいて検討するときに引き継ぎます。
• experiment-statistics（提供開始後）— CUPED、逐次検定、多重比較、ディメンション分析に関する詳細な質問に対応します。