flag-experiment

flag-experiment

GrowthBook の機能フラグに experiment-ref ルールを追加します。これにより、フラグのルールを、別途管理されている GrowthBook の実験オブジェクトに関連付けます。バリエーション、メトリクス、分析の信頼できる情報源は実験です。

すべての API 呼び出しは、同梱のヘルパー ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call を経由します。環境変数に GB_API_KEY を設定するか、/growthbook:gb-setup によって ~/.config/growthbook/.env に書き込む必要があります。

ワークフロー

パス A — experiment-ref ルールを追加する

既存の GrowthBook 実験がある場合や、フラグを使って実験を開始したい場合に使用します。

1. フラグを取得し、実験が存在することを確認します：

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

valueType を控えてください。これはバリエーション値を対応付ける際に必要になります。

gb-call GET /api/v1/experiments/<experiment-id>

実験の variations 配列を控えてください。各バリエーションには id（例：var_abc123）と name があります。これらを使ってルールを設定します。

ユーザーがまだ実験を持っていない場合は、experiment-launch に案内してください。実験の作成とフラグの設定をエンドツーエンドで処理します。重要なのは、フラグがすでに存在する場合、experiment-launch は作成時の 409 と、その後の再利用パスを通じて既存のフラグを検出し、新しいフラグを作成するのではなく、実験を既存のフラグに関連付ける点です。ユーザーには次のように伝えてください：「experiment-launch は既存のフラグを検出します。同じフラグキーを指定してください。」

2. バリエーション値を対応付けます：

各実験バリエーションについて、配信するフラグ値を確認します。フラグの valueType によって形式が決まります。

• boolean：通常、トリートメントには "true"、コントロールには "false" を指定します
• string ／ number ／ json：各バリエーションの値をユーザーに確認します

3. ペイロードを作成します：

{
  "rule": {
    "type": "experiment-ref",
    "experimentId": "<exp-id>",
    "variations": [
      { "variationId": "<var_control_id>", "value": "false" },
      { "variationId": "<var_treatment_id>", "value": "true" }
    ],
    "description": "<optional>",
    "enabled": true,
    "allEnvironments": false,
    "environments": ["<env-id>"]
  }
}

variations 配列内の順序は、実験のバリエーション順と一致させる必要があります。ユーザーがすべての variationId フィールドを省略すると、サーバーが実験から自動入力します。ただし、明示的に指定するほうが安全で、気付かないまま不一致が生じるのを防げます。

4. ルールを投稿します：

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

返された version を控えてください。flag-publish に引き継ぎます。

パス B — 既存の experiment-ref ルールのターゲティングを編集する

サーバーでは、experiment-ref ルールの enabled、condition、savedGroups、prerequisites、スコープ（allEnvironments／environments）、description をパッチで変更できます。完全な条件判断ツリーと、慎重に扱うフィールドに対する警告・確認のガードレールを備えている flag-targeting を使用してください。

experiment-ref ルールの experimentId や variations を直接編集しないでください。 実験が信頼できる情報源です。フラグルールだけでこれらのフィールドを変更すると、フラグと実験の間に気付かないまま差異が生じます。ユーザーが実験を変更する必要がある場合は、experiment-launch または GrowthBook の UI に案内してください。

ガードレール

• ドラフトのバージョン管理。 このセッションで前の書き込みスキルによってバージョン番号がすでにコンテキストにある場合は、new ではなく、そのバージョンを明示的に使用します。新しく開始する場合は new を使用します。
• variations の順序は、実験のバリエーションの順序と一致させる必要があります。 順序が誤っていると、バリエーションの割り当てがずれ、コントロールのユーザーに処置値が表示され、その逆も起こります。ペイロードを作成する前に、実験を読み込んで必ずバリエーションの順序を確認してください。
• variationId の自動入力は利用できますが、リスクがあります。 すべての variationId フィールドを省略すると、サーバーが実験から値を入力します。この方法を使用するのは、実験のバリエーション数がユーザー指定の値の数と完全に一致する場合に限ってください。それ以外の場合、サーバーによって気付かないうちに対応関係がずれる可能性があります。
• 既存の experiment-ref ルールの experimentId または variations を編集する場合は、警告して確認を求める必要があります。 これらのフィールドは API で許可されていますが、フラグと実験の不整合を引き起こします。パッチを適用する前に、必ずリスクを伝え、明示的な確認を得てください。
• experiment-ref ルールでサーバーに拒否されるパッチ： value、coverage、controlValue。これらはフラグルールではなく、実験の属性です。ユーザーがこれらの設定を試みた場合は、早い段階で処理を中止してください。
• 実験は同じデータソースに属している必要があります。 実験で使用されているデータソースが組織のデフォルトと一致しない場合、メトリクスの検索に失敗することがあります。インラインルールでメトリクスが指定されている場合は、データソースが一致していることを確認してください。
• フラグごとに、実験あたり experiment-ref ルールを1つだけ設定するのが標準的な運用です。 同じ実験を参照するルールを複数作成すると、バケット分けが重複し、分析結果が損なわれます。

使用するエンドポイント

• GET /api/v2/features/:id — フラグの状態、valueType、現在のルールを取得します
• GET /api/v1/experiments/:id — 実験とそのバリエーションを取得します
• POST /api/v2/features/:id/revisions/new/rules — experiment-ref ルールを追加します

引き継ぎ先

• flag-search — 名前または説明しかない場合に、フラグ ID を検索します
• experiment-launch — 新しい実験を作成し、フラグに一貫して接続します
• flag-targeting — 既存の experiment-ref ルールのターゲティング条件、スコープ、保存済みグループを編集します
• flag-rules — 実験ルールの順序を変更または削除します
• experiment-stop — 実験を停止します。停止後、flag-rules を使用して experiment-ref ルールを整理します
• flag-publish — ドラフトを公開します