experiment-launch

experiment-launch

GrowthBook の A/B テストを最初から最後まで開始します。実験を下書きとして作成し、フィーチャーフラグを準備または再利用し、新しい下書きリビジョンに experiment-ref ルールを追加してから、/start を呼び出してルールを公開し、実験を実行中に切り替えます。承認が必要な場合や、開始前チェックリストで失敗した場合にも対応します。

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

必須入力

開始前に、ユーザー（または先行するスキルの出力）から収集します。不足している項目を尋ねてください。

• フィーチャーフラグ名 — ケバブケースのキー。正規表現 [a-zA-Z0-9_-]
• 実験名 — 人が読める名前
• バリエーション — {name, value} の配列。要素数は 2 以上。最初の要素がコントロールです。値はルール内で文字列としてシリアライズされます（ブール値 → "false"／"true"、数値 → "42"、JSON → JSON エンコードされた文字列）。
• プロジェクト ID（任意）— 実験とフラグを特定のプロジェクトに固定します

任意の入力

• 仮説 — 反証可能なもの。「もし〜なら、〜になる。なぜなら〜だから」の形式
• テンプレートの説明 — /v1/experiment-templates が返す templateMetadata.name／description と照合する英語の説明。省略されていて、テンプレートが存在する場合は、ユーザーに選択するかスキップするか尋ねます。

テンプレートを使用しない場合は、次の項目も収集します（またはステップ 2 で対話形式で解決します）。

• データソース — ID または英語名
• ハッシュ属性 — ランダム化の単位（id、device_id など）。データソースで選択した割り当てクエリの identifierType と一致している必要があります。
• 割り当てクエリ — ID または英語名。選択したデータソースの assignmentQueries 内にあります
• ゴールメトリクス ID — 1 つだけ（採用または中止の判断基準となる主要 KPI）
• セカンダリメトリクス ID — 補助的なメトリクス
• ガードレールメトリクス ID — 悪化を防ぐための防御的なメトリクス

ワークフロー

次のチェックリストで進行状況を追跡します。手順を省略したり、順序を入れ替えたりしないでください。

- [ ] 1. Pick a template (or skip)
- [ ] 2. Resolve hash attribute → datasource → assignment query → metrics (no-template path only)
- [ ] 3. Create the experiment in draft
- [ ] 4. Create or reuse the feature flag
- [ ] 5. Add the experiment-ref rule on a fresh draft revision
- [ ] 6. Prompt user to QA the experiment and feature flag config
- [ ] 7. POST /start; branch to 7a (approval) or 7b (checklist) on 400
- [ ] 8. Report links and state

1. テンプレートを選択する（またはスキップする）

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

• テンプレートが 0 個 → テンプレートなしで続行し、ステップ 2 に進みます。
• テンプレートが 1 個以上 → 名前 — 説明 の形式で列挙し、最後に「スキップ」を追加します。テンプレートの説明が指定されている場合は、templateMetadata.name／description から最適なものを事前選択して確認します。テンプレートを作り上げてはいけません。

選択した場合は、id（templateId になります）、datasource、exposureQueryId、hashAttribute、goalMetrics、statsEngine、targeting を取得します。テンプレートによってこれらすべてが設定されるため、ステップ 2 は完全にスキップします。

テンプレートの type が "multi-armed-bandit" の場合は、停止してユーザーに確認します。バンディットは標準的な A/B テストとは大きく異なる動作をします（トラフィックの動的配分、勝者／敗者ではなくアームごとの確率、異なる分析）。このスキルの開始と分析に関する前提は type: "standard" を対象にしています。現時点では、UI でバンディットを設定することを推奨してください。

2. ハッシュ属性 → データソース → 割り当てクエリ → 指標を解決する

テンプレートを使わない場合のみの手順です。順序が重要です。まずハッシュ属性を選んでください。そうしないと、その属性でランダム化できないデータソースを選んでしまう可能性があります。

2a. ハッシュ属性を選びます。 hashAttribute として指定されている属性に絞り込みます。

gb-call GET /api/v1/attributes

hashAttribute === true かつ archived !== true の属性を表示します。ユーザーに選んでもらいます。絞り込んだリストが空の場合は中止し、GrowthBook の Settings → Attributes で少なくとも 1 つの属性をハッシュ属性として指定するよう伝えてください。

2b. データソースを選びます。

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

dataSources[].name / id に照らして、英語名または ID を解決します。DATASOURCE_ID を取得し、オブジェクト全体を保持してください。2c ではその assignmentQueries を参照します。

2c. 割り当てクエリを選びます。 dataSources[].assignmentQueries を identifierType === HASH_ATTRIBUTE のエントリに絞り込みます。

• 一致が 1 件のみ → 自動選択し、選択した内容を 1 行で表示します。
• 一致が 0 件 → 中止し、次の 3 つの修正方法を提示します。別のデータソースを選ぶ（2b を再実行）、ハッシュ属性を変更する（2a を再実行）、または GrowthBook で <HASH_ATTRIBUTE> の割り当てクエリを追加する。
• 一致が 2 件以上 → それぞれを name (identifierType=<value>) — <description> の形式で一覧表示し、ユーザーに選んでもらいます。

assignmentQueries が空の場合は、中止し、再実行する前に GrowthBook で設定するよう伝えてください。

2d. データソースで絞り込んだ指標を選びます。 API は、実験とは異なるデータソースの指標を拒否します。

gb-call GET '/api/v1/fact-metrics?datasourceId=<DATASOURCE_ID>&limit=100'
gb-call GET '/api/v1/metrics?datasourceId=<DATASOURCE_ID>&limit=100'

ユーザーが選べるように支援します。

• 目標指標（複数可）（GOAL_METRIC_IDS）。理想的には 1 つ、最大 2 つです。3 つ以上の場合は再検討を促し、残りを副次指標またはガードレールに変更するよう提案します。
• 副次指標（SECONDARY_METRIC_IDS）— 補足情報として使用します。
• ガードレール指標（GUARDRAIL_METRIC_IDS）— 防御的に使用します。何も指定されていない場合は再検討を促してください。すべての実験に少なくとも 1 つ必要です。ガードレールは設計上、多重比較補正の対象外です。

3. 実験をドラフトとして作成する

trackingKey をフィーチャーフラグ名に設定し、SDK がエクスポージャーをそのフラグに関連付けられるようにします。各バリエーションには、安定した文字列の key（"0"、"1"、...）と name が必要です。バリエーションの値は実験のペイロードではなく、フラグのルール（ステップ 5）に設定します。

テンプレートを使う場合 — datasourceId / assignmentQueryId も送信してはいけません。テンプレートがこれらを提供し、API はこの組み合わせを拒否します。

{
  "templateId": "<from step 1>",
  "trackingKey": "<flag-name>",
  "name": "<experiment name>",
  "hypothesis": "<hypothesis>",
  "variations": [
    { "key": "0", "name": "Control" },
    { "key": "1", "name": "Treatment" }
  ],
  "project": "<project id, omit if org-wide>"
}

テンプレートを使わない場合 — ステップ 2 の内容をすべて明示的に送信します。

{
  "datasourceId": "<DATASOURCE_ID>",
  "assignmentQueryId": "<ASSIGNMENT_QUERY_ID>",
  "hashAttribute": "<HASH_ATTRIBUTE>",
  "trackingKey": "<flag-name>",
  "name": "<experiment name>",
  "hypothesis": "<hypothesis>",
  "variations": [
    {"key": "0", "name": "Control"},
    {"key": "1", "name": "Treatment"}
  ],
  "metrics": ["<GOAL_METRIC_ID>"],
  "secondaryMetrics": [<SECONDARY_METRIC_IDS as JSON array>],
  "guardrailMetrics": [<GUARDRAIL_METRIC_IDS as JSON array>],
  "project": "<project id, omit if org-wide>"
}

注意事項：

• metrics は目標指標の配列です。目標指標を 1 つにするルールに従うと、常に長さ 1 になります。
• ユーザーが副次指標やガードレール指標を選ばなかった場合、secondaryMetrics / guardrailMetrics は完全に省略してください。空の配列は送信しないでください。

次を POST します。

echo '<payload-json>' | gb-call POST /api/v1/experiments -

レスポンスから次の値を取得します。

• experiment.id — ステップ 5 と 6 で使用します。
• experiment.variations[].variationId — 各バリエーションの文字列 ID（例：var_abc123）です。ステップ 5 で必要です。experiment-ref ルールで必須です。

4. フィーチャーフラグを作成または再利用する

フラグがすでに存在するとユーザーが伝えていない限り、まず作成を試みてください。 フラグのデフォルト値はコントロールの値（variation 0 の値）にし、文字列としてシリアライズする必要があります。すべての環境もデフォルトでオフにしてください。

{
  "id": "<flag-name>",
  "valueType": "<boolean|string|number|json>",
  "defaultValue": "<control value as string>",
  "description": "Drives experiment: <experiment name> (<exp_id>)",
  "project": "<project id, omit if org-wide>"
}

echo '<payload-json>' | gb-call POST /api/v2/features -

• 成功 → 手順 5 に進みます。
• 409 Conflict（フラグが存在する）→ 以下の再利用時の互換性チェックに進みます。

再利用する場合 — 取得して検証する：

gb-call GET /api/v2/features/<flag-name>

レスポンスに対して、以下の互換性チェックを実行します。各行には、チェックに失敗した場合の対応が示されています。

チェック	失敗時の対応
archived === false	中止してください。 再実行する前に UI でフラグのアーカイブを解除するようユーザーに伝えます。
valueType が実験の <boolean|string|number|json> と一致する	中止してください。 両方の値を提示し、型を黙って変更しないでください。
project が実験のプロジェクトと一致する（設定されている場合）	中止してください。 別のプロジェクトのフラグを再利用すると、実験が誤った場所に振り分けられます。
defaultValue がコントロールの値と一致する（文字列として比較）	警告しますが、中止はしません。実験ルールがバリエーションの値を適用し、既存のデフォルト値はルールに一致しない場合にのみ適用されます。「続行しますか？」と尋ねてください。
既存のルールのうち、type === "experiment-ref" かつ experimentId === <exp_id> のものがすでに紐付いていない	すでに存在する場合 → この実験はすでに設定済みです。手順 5 をスキップし、手順 6 に進みます。
同じ環境において、別の 実行中 の実験を参照する競合する experiment-ref ルールが存在しない	警告しますが、中止はしません。「このフラグは現在、実験 <other_id> を動作させています。別のルールを追加しますか？」と尋ねてください。

すべてのチェックに合格したら、フラグの ID を取得して手順 5 に進みます。ここでは既存のフラグを変更しないでください。すべての変更は手順 5 のドラフトリビジョンを通して行います。

5. 新しいドラフトリビジョンに experiment-ref ルールを追加する

リテラル値 new を使用して、1 回の呼び出しでドラフトを作成し、ルールを追加します。パスセグメント new は、ライブリビジョンから分岐したドラフトをアトミックに作成する特別な値です。フィーチャーに複数の環境がある場合は、どの環境を本番稼働させるかユーザーに尋ね、その環境でルールを追加するとともに、フィーチャーフラグが有効になるようにしてください。

{
  "rule": {
    "type": "experiment-ref",
    "experimentId": "<exp_id from step 3>",
    "enabled": true,
    "allEnvironments": true,
    "variations": [
      {
        "value": "<variation 0 value as string>",
        "variationId": "<var_id from step 3, position 0>"
      },
      {
        "value": "<variation 1 value as string>",
        "variationId": "<var_id from step 3, position 1>"
      }
    ],
    "description": "Experiment: <experiment name>"
  }
}

echo '<payload-json>' | gb-call POST /api/v2/features/<flag-name>/revisions/new/rules -

variations[] には、手順 3 と同じ順序で、実験のバリエーションごとに 1 つのエントリを指定する必要があります。各エントリには value（文字列としてシリアライズ）と variationId（手順 3 で取得した文字列 ID）の両方が必要です。variationId は v2 features バリデーターで必須であり、省略すると 400 が返されます。ドラフトリビジョンの返された version を取得してください。

ここではリビジョンを公開しないでください。手順 7 の /start 呼び出しで、実験を実行中に切り替える際にドラフトが自動的に公開されます。

6. /start の前に QA で確認する

ここまでは、ドラフトの変更と実験を元に戻せます。ステップ 7 の /start でルールが公開され、実験が実行中に切り替わります。

ユーザーが機能フラグもコードベースに埋め込みたいと考えているようなら、今がその作業を行うよいタイミングです。

いったん停止し、GrowthBook UI でフラグのデフォルト値、ルールのバリエーション値、実験のターゲティングと指標を QA で確認できるよう、UI のリンクをユーザーに提示します。

• 実験：<host>/experiment/<exp_id>
• 機能：<host>/features/<flag-name>（ドラフトのリビジョン <version>）

ステップ 8 と同様に、GB_API_URL の api. を app. に置き換えて <host> を導き出します。ユーザーから明示的な許可を得るまで、ステップ 7 に進まないでください。

7. 実験を開始する

gb-call POST /api/v1/experiments/<exp_id>/start '{}'

/start エンドポイントは、サーバー側で次の 2 つの処理を行います。

1. ステップ 5 の機能ドラフトのリビジョンを公開します（publishPendingFeatureDraftsForExperiment）。
2. 組織のローンチ前チェックリストを適用します。

どちらも 400 エラーになる可能性があります。次のように分岐します。

• 本文が "This revision requires approval before publishing" で始まる → ステップ 7a。
• 本文に未完了のチェックリスト項目が列挙されている → ステップ 7b。
• 2xx → ステップ 8。

7a. 承認が必要

実験とフラグは作成されています。ルールのリビジョンだけがドラフトのままです。処理を中断し、次の具体的な 3 つの方法をユーザーに提示します。

組織では、この機能フラグのルールを有効にする前に承認が必要です。ルールが公開されるまで、/start で実験を実行中に切り替えることはできません。<flag-name> のリビジョン <version> はドラフト状態です。次のいずれかを選んでください。

A. 標準のレビュー手順（推奨）— ただちにレビューを依頼します。チームメイト（ドラフトを作成した本人は不可）が、GrowthBook UI の <host>/features/<flag-name> で承認します。その後、もう一度実行すれば、/start から再開します。

B. 組織全体のバイパス — 管理者が Settings → General → Approvals で「REST API always bypasses approval requirements」を有効にします。その後、もう一度実行してください。

C. トークン単位のバイパス — このプロジェクトで bypassApprovalChecks が許可されたロール（Admin またはカスタムロール）を持つ Personal Access Token を使います。GB_API_KEY を更新してから、もう一度実行してください。

ユーザーが A を選んだ場合は、ドラフトのレビューを依頼して停止します。

echo '{"comment":"Auto-requested by experiment-launch for <exp_id>"}' \
  | gb-call POST /api/v2/features/<flag-name>/revisions/<version>/request-review -

自分で作成したドラフトの承認は API に拒否されるため、自分で submit-review を実行しないでください。停止し、承認後にもう一度実行するようユーザーに伝えます。

ユーザーが B または C を選んだ場合は、1 行のメモを残して停止します。既存のドラフトは新しい権限を反映し、再試行時に公開されます。

ポリシーを回避するために、/start を黙って再試行したり、エラーを無視したり、ドラフトを破棄して作り直したりしないでください。

7b. チェックリストが未完了

REST API には、個別の start-checklist エンドポイントはありません。/start の失敗レスポンス本文が正規の情報源です。内容を解析し、未完了の項目をそのまま提示します。

ローンチ前チェックリストが未完了です。/start の呼び出しで次の内容が返されました。

<full error body>

GrowthBook UI の <host>/experiment/<exp_id> で記載された項目を修正してから、もう一度実行してください。/start からすぐに再開します。

ユーザーがバイパスを明示的に要求した場合に限り、本文に {"skipChecklist": true} を指定して /start を再試行します。デフォルトでバイパスしてはいけません。チェックリストは意図的に設けられています。

8. 結果を報告する

次の概要を出力します。

• 実験名と id
• 機能フラグの ID と公開済みリビジョンのバージョン
• 使用したテンプレート（ある場合は名前と ID）
• ランダム化の単位（hashAttribute）
• バリエーションとその値
• ローンチ前チェックリストの状態（allRequiredComplete=true である必要があります）
• 実験の状態（正常に /start が完了した後は running である必要があります）
• 直接開ける UI リンク（GB_API_URL の api. を app. に置き換えてホストを導き出します）：
  • 実験：<host>/experiment/<exp_id>
  • 機能：<host>/features/<flag-name>

ガードレール

• 目標指標はできれば1つ、最大でも2つにしてください。 GrowthBook の意思決定フレームワークでは目標指標を複数設定できるようになっており、検出力計算ツールは最大5つをサポートしていますが、目標指標を1つ追加するごとに検出力が低下し、リリースするか中止するかの判断が複雑になります。3つ以上の場合は再検討を促し、残りは副次指標に格下げしてください。
• ガードレールを少なくとも1つ設定してください。 ユーザーがガードレールを省略しようとした場合は、再検討を促してください。
• hashAttribute と assignmentQuery.identifierType は一致している必要があります。 不一致は実際に発生し、修復可能なエラーです。ステップ2cで修正方法を提示してください。
• 指標は実験のデータソース上に存在する必要があります。 ステップ2dでは、/v1/metrics と /v1/fact-metrics を datasourceId でフィルタリングしてください。
• templateId と datasourceId／assignmentQueryId を混在させないでください。 テンプレートを使う場合はこれらが指定され、使わない場合は明示的に指定します。混在させると 400 が返されます。
• フラグのデフォルト値はコントロール値です。 フラグに紐づく実験では、バリエーション値はルール上の文字列になります。ブール値には "false"／"true"、数値には "42"、json には JSON エンコードされたテキストを使用してください。
• 再利用は慎重に行ってください。 既存のフラグを再利用する前に、必ずステップ4の互換性チェックを実行してください。valueType が違うフラグ、project が異なるフラグ、または競合するルールがあるフラグに、確認せず実験を紐づけると、実験が壊れたり、チームメイトが進行中のテストに影響したりします。
• リビジョンを手動で公開しないでください。 ステップ5のドラフトは、ステップ7の /start によって公開されます。公開エンドポイントを別途呼び出さないでください。承認に失敗した場合、自分で承認しないでください。 API は、自分が作成したドラフトの承認をブロックします。代わりにステップ6aの手順をユーザーに案内してください。
• 通常、チェックリストの失敗を回避してはいけません。 ユーザーが明示的に希望した場合に限り、skipChecklist: true を設定してください。

使用するエンドポイント

• GET /api/v1/experiment-templates — テンプレートを一覧表示します
• GET /api/v1/attributes — hashAttribute=true でフィルタリングします
• GET /api/v1/data-sources — データソースと割り当てクエリを選択します
• GET /api/v1/fact-metrics?datasourceId=…、GET /api/v1/metrics?datasourceId=… — 目標指標／副次指標／ガードレールを選択します
• POST /api/v1/experiments — ドラフトの実験を作成します
• POST /api/v2/features — 紐づけるフィーチャーフラグを作成します（再利用しない場合）
• GET /api/v2/features/<id> — 再利用時の互換性チェック用にフラグを取得します
• POST /api/v2/features/<id>/revisions/new/rules — ドラフトの作成と実験参照ルールの追加をアトミックに行います
• POST /api/v2/features/<id>/revisions/<version>/request-review — 6aの「レビューをリクエスト」するフローでのみ使用します
• POST /api/v1/experiments/<id>/start — ドラフトのリビジョンを公開して実験を開始します。ユーザーが明示的に希望した場合、起動前チェックリストを省略するために {"skipChecklist": true} を本文に指定できます。失敗時のレスポンス本文には正規の理由が含まれます。照会用の別個の start-checklist GET はありません。

引き継ぎ先

• experiment-design — 仕様がない場合は、まずこちらに戻します。
• flag-search — 名前または説明しかわからない場合に、既存のフラグ ID を探します。
• experiment-analyze — 実験の実行開始後、トラフィックが蓄積したときに使用します。
• experiment-stop — 結果が確定したときに使用します。
• 指標の手動作成 — 必要な指標がまだ存在しない場合は、このスキルを再実行する前に、ユーザーが GrowthBook UI の <host>/metrics（ファクト指標の場合は <host>/fact-tables）で作成する必要があります。そのためのスキルはまだありません。