experiment-design

experiment-design

実際にリリースできる実験仕様をユーザーが作成できるよう支援します。仮説、バリエーション、指標、サンプルサイズの妥当性確認を順を追って進めます。このスキルは GrowthBook への書き込みは行いません。experiment-launch に渡せる、すぐにリリース可能な仕様を作成して完了します。

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

ワークフロー

1. 仮説をまとめます。 反証可能な「もし／ならば／なぜなら」形式にします。

   X を変更すれば、Z だから、Y が改善します。

   仮説が曖昧な場合は、具体化を促します。「ユーザーに気に入ってもらえると思います」では、どの指標を指すのかが分かりません。エンゲージメントには、異なる意味が 5 つも考えられます。「CTA をファーストビューに移動すれば、ユーザーはスクロールする前にエンゲージメントを判断するため、クリック率が上昇します」であれば、予測を具体的に検証できます。

2. バリエーションを定義します。 デフォルトは 2 つです。コントロール（現状）とトリートメント（変更）を設定します。3 つ以上のバリエーションも有効ですが、統計的検出力が低下するため、3 つ目が本当に必要かユーザーに確認してください。バリエーションには、0（コントロール）から N まで番号を付けます。

3. 目標指標を選びます（理想は 1 つ、最大 2 つ）。 利用可能なテンプレートと指標を一覧表示します。

   gb-call GET /api/v1/api/v1/experiment-templates
   gb-call GET /api/v1/metrics
   gb-call GET /api/v1/fact-metrics
   

   該当するテンプレートがあれば、ユーザーがそれを選べるように支援します。該当するものがなければ、仮説から変化が予測される指標をユーザーが選べるように支援します。指標の種類（比率、平均、比、分位点）にも留意してください。サンプルサイズの計算に影響します。目標指標が 3 つ以上ある場合は再考を促し、残りを副次指標またはガードレールに振り分けます。GrowthBook の意思決定フレームワークでは、目標指標は複数設定できる設計になっていますが、目標指標を追加するたびに検出力が低下し、リリース可否の判断も複雑になります。

4. ガードレールを選びます（1～3 個）。 悪化してはならない指標です。一般的な例として、サインアップ率、ページのエラー率、レイテンシがあります。ユーザーがガードレールを省略する場合は再考を促してください。通常、実験ではガードレールが少なくとも 1～2 個あると適切です。ガードレールは設計上、多重比較補正の対象外となるため、設定しすぎないようにしてください。

5. サンプルサイズを見積もります。 ユーザーから次の 3 つの情報を得る必要があります。

   • 主要指標のベースライン率（または平均値）
   • ユーザーが重要と考える最小検出効果（MDE）。相対値で指定します（「コンバージョンが 2% 向上」など）。
   • 影響を受けるサーフェスの日次トラフィック

   まず概算で妥当性を確認し、その後、実際の数値については GrowthBook のアプリ内 Power Calculator を案内します。GrowthBook がドキュメントで示している一般的な目安は、比率指標の場合、バリエーションあたり ≥ 200 件のコンバージョンです。バリエーションあたりの式 n ≈ 16 × p × (1 - p) / (p × MDE)^2 も、80% の検出力ではおおむね同程度の値になります。どちらも推定値なので、有効数字を 3 桁にして提示しないでください。切り上げて、入力値も提示します。

   実験の予想期間を計算します：2 × n / daily_traffic。期間が次のどちらに該当するかを明示してください。

   • > 4 週間 — 実用上、検出力が不足する可能性が高いです。MDE を大きくする、より感度の高い指標を使う、またはトラフィックの多いサーフェスを選ぶことを検討してください。
   • < 1 週間 — 曜日や週末の影響で結果が偏るリスクがあります。少なくとも週次サイクルを 1 回含めることを推奨します。

6. プロジェクトとデータソースを特定します。 ユーザーが特定のプロジェクトに言及した場合、その ID を取得します。

   gb-call GET /api/v1/projects
   

   データソースも一覧表示して、選択肢を示します（リリースの手順で選択しますが、利用可能なものをユーザーに示すと役立ちます）。

   gb-call GET /api/v1/data-sources
   

7. 仕様を作成します。 ユーザーが確認し、experiment-launch に渡せる構造化ブロックを出力します。

   ## Experiment spec — <short name>
   
   **Hypothesis:** If <change>, then <outcome>, because <mechanism>.
   
   **Variations:**
   - 0: Control — <description>
   - 1: Treatment — <description>
   
   **Primary metric:** <name> (<type>) — baseline <value>
   **Guardrails:** <metric a>, <metric b>
   **MDE:** <X%>
   **Estimated sample size:** <N> per variation
   **Estimated duration:** <D> days at <T> visitors/day on the affected surface
   **Project:** <project id>
   **Tracking key suggestion:** <kebab-case-name>
   

   experiment-launch に引き継ぐ前に、ユーザーに確認を求めてください。

ガードレール

• 目標指標はできれば1つ、最大でも2つにします。 GrowthBook の意思決定フレームワークでは、目標指標は複数を前提としており、検出力計算ツールは最大5つまで対応していますが、目標指標を追加するたびに検出力が低下し、リリース／中止の判断も複雑になります。3つ以上の場合は再検討を促し、残りは副次指標にします。
• ガードレールを少なくとも1つ設定します。 ユーザーがガードレールを省略した場合は再検討を促します。複数比較の補正はガードレールには適用されません（ガードレールのシグナルはリリースを止めることを意図しているためです）。ただし、ガードレールを設定しすぎないようにします。1〜3個が適切です。
• 反証可能な仮説を、もし／ならば／なぜなら、の形式で示します。 結果を照らし合わせて解釈できるほど具体的な予測にするよう促します。「ユーザーのエンゲージメントが高まる」だけでは、どの指標を指すのか分かりません。
• サンプルサイズの計算は概算です。 目安として使い、正確な数値はアプリ内の Power Calculator で確認するよう案内します。数値は切り上げ、ユーザーが確認できるよう使用した入力値を明示します。
• アクティベーション指標の偏りに注意します。 バリエーションの違いによって影響を受ける下流のアクティベーション指標は、SRM を発生させずに結果に偏りをもたらします。ユーザーがそのような指標を選んだ場合は、リスクを明示します。
• 初めて実験を行うユーザーには A/A テストを提案します。 組織に停止済みの実験がない場合（flag-discovery または experiment-brainstorm で確認します）、実際の実験を始める前に実装を検証する A/A テストを GrowthBook は推奨しています。
• 曜日による影響は重要です。 期間が1週間に満たない実験には再検討を促します。週末のトラフィックや行動は平日とは異なります。
• このスキルから実験を開始しないでください。 最終仕様を作成したら、ユーザーの確認を得て、experiment-launch に引き継ぎます。スコープの拡大は避けます。
• トラッキングキーの命名は後から変更できません。 実験名から導出したケバブケースを提案します。開始手順でこの値を trackingKey として使用します。イベントデータに記録されるため、後から簡単に変更できません。

使用するエンドポイント

• GET /api/v1/metrics と GET /api/v1/fact-metrics — 主指標およびガードレール指標の候補を一覧表示します
• GET /api/v1/metrics/<id> — サンプルサイズの推定に使うベースライン値を取得します
• GET /api/v1/projects — プロジェクト名を ID に解決します
• GET /api/v1/data-sources — 利用可能なデータソースを一覧表示します（開始時に使用します）

引き継ぎ

• experiment-launch — 仕様を受け取り、GrowthBook に下書きの実験を作成します。
• 指標の手動作成 — 主指標がまだ存在しない場合は、開始前にユーザーが GrowthBook UI の <host>/metrics（ファクト指標の場合は <host>/fact-tables）で作成する必要があります。現時点ではそのためのスキルはありません。GB_API_URL の api. を app. に置き換えて <host> を導出します。
• experiment-brainstorm — 具体的な仮説を持たずにユーザーが訪れた場合は、過去の結果を踏まえて新しいアイデアを練るため、こちらに戻します。