flag-create

flag-create

GrowthBook に新しいフィーチャーフラグを作成します。ペイロードでは、すべての環境に対して常に明示的に {enabled: false} を設定します。そのため、組織の新しい環境のデフォルト状態の設定にかかわらず、フラグは無効な状態で作成されます。有効にするには、作成後にユーザーが操作する必要があります。フラグキーは恒久的なものなので、名前は慎重に選んでください。

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

ワークフロー

1. 意図を確認します。 このフラグで何を制御するのかを一文で言い換えます。ユーザーが A/B テストを実行しようとしている場合は、すでに対象になっている内容に応じた適切な実験スキルを案内して中止します。既存のフラグにルールを設定しようとしている場合は、flag-rules を案内します。

2. キーが使用済みでないことを確認します。

   gb-call GET /api/v2/feature-keys
   

   返された一覧に、提案されたキーがすでに含まれていないことを確認します。含まれている場合は別の候補を提案してください。API はキーの重複を拒否し、作成後にキーの名前を変更することはできません。

3. 値の型を選びます。 string、number、boolean、json のいずれかを指定します。オン／オフを切り替えるフラグには、デフォルトで boolean を使用します。string または json は、フラグに設定値（バリアントのコピー、しきい値、構造化ペイロードなど）を持たせる場合にのみ使用します。

4. プロジェクトを特定します（任意）。 ユーザーがプロジェクト名を挙げた場合は、プロジェクト一覧を取得して ID を選びます。

   gb-call GET /api/v1/projects
   

   プロジェクトにスコープを設定したフラグは、デフォルトの組織全体の領域に置くよりも管理しやすくなります。不明な場合はユーザーに確認してください。

5. 環境を特定します。 GrowthBook では、作成ペイロードにすべての環境を列挙した environments マップを含める必要があります。環境を取得します。

   gb-call GET /api/v1/environments
   

   各環境を無効にしたマップを作成します。

6. 名前を確認します。 v2 エンドポイントの正規表現では [a-zA-Z0-9_.:|-] が許可されていますが（ユーザー向けのドキュメントやエラーメッセージでは、より限定的な [a-zA-Z0-9_-] が推奨されています）、デフォルトでは kebab-case（new-checkout-flow、dark-mode、pricing-experiment-2026-q2）を使用します。ドキュメントの推奨に沿い、チーム間でキーの一貫性を保てるうえ、将来正規表現が厳しくなった場合も問題が起きません。作成前に、提案するキーをユーザーに提示してください。

7. ペイロードを作成してフラグを作成します。 JSON オブジェクトを作成します。

   {
     "id": "<kebab-case-key>",
     "valueType": "boolean",
     "defaultValue": "false",
     "description": "<short description>",
     "environments": {
       "production": { "enabled": false },
       "staging":    { "enabled": false }
     },
     "project": "<project-id, omit if org-wide>"
   }
   

   次に POST します。

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

8. 次に起こることを伝えます。 フラグはすべての環境で無効で、まだルールが設定されていないことをユーザーにはっきり伝えてください。次の 2 つの操作を案内します。

   • 環境で有効にする、またはターゲティングルールを追加するには、flag-targeting を使用します。
   • A/B テストのバリエーション切り替えにこのフラグを使うには、フラグの ID を指定して experiment-design を使用します。

ガードレール

• フィーチャーキーは変更できません。 GrowthBook では、作成後にフラグの id を変更できません。API を呼び出す前に、提案する名前をユーザーに確認してください。
• owner のデフォルトはトークンのユーザーです。 作成ペイロードから owner を省略してください。API は、GB_API_KEY が属するユーザーにフラグを割り当てます。ユーザーが別の人にフラグを割り当てたい場合に限り、owner（メールアドレスまたは u_... 形式の userId）を明示的に設定してください。
• ID の文字セットには、ケバブケースを推奨します。 v2 エンドポイントの正規表現では引き続き [a-zA-Z0-9_.:|-] を使用できますが、ユーザー向けのドキュメントとエラーメッセージでは [a-zA-Z0-9_-] が推奨されています。.、:、| を含む ID は提案しないでください。将来のバージョンで使用できなくなる可能性があります。これらの文字を含む既存のレガシーキーは、そのままにしてかまいません。
• 環境ごとに、必ず {enabled: false} を明示的に設定してください。 組織の「新しい環境のデフォルト状態」設定に依存しないでください。この設定は変更可能で、有効がデフォルトになっている場合があります。フラグがすべての環境で無効であることをユーザーに伝えてください。評価が何も返さない状態に気付かない（あるいは、さらに悪いことに、誤って有効な状態で評価される）のは、GrowthBook で特によくある落とし穴です。
• defaultValue は常に文字列としてシリアライズしてください。 boolean のオフには "false"、数値には "0"、json には JSON エンコードされたテキストを指定します。API は文字列以外の値を拒否します。
• v2 の環境マップでは、各環境に {enabled: bool} のみを指定します。 ルールは各環境の中にネストされなくなりました。フラグのトップレベル配列として、後から flag-targeting（または v2 revision エンドポイントから直接）追加します。各環境の中に rules: [] を含めないでください。
• ユーザーが実験を希望する場合は、作成前に中断してください。 experiment-design に引き継いでください。対応する実験を作成せずにフラグを作成すると、孤立したフラグが生まれ、混乱を招くことがよくあります。
• 推測せず、質問してください。 valueType、defaultValue、またはプロジェクトが曖昧な場合は、質問してください。フラグは変更できません。

使用するエンドポイント

• GET /api/v2/feature-keys — すべてのフィーチャーフラグキーを一覧表示します（ページネーションの上限なし）
• GET /api/v1/projects — プロジェクトを一覧表示します。プロジェクト名を ID に解決するために使用します
• GET /api/v1/environments — 環境を一覧表示します。environments マップの作成に使用します
• POST /api/v2/features — フラグを作成します

作成後

レスポンスには、フラグの完全な設定が含まれます。フラグ ID と、すべての環境で無効になっていることを改めて伝え、GrowthBook UI 上のフラグへのリンクをユーザーに提示してください。GB_API_URL から api. → app. に置き換えて <host> を導出します（クラウドのデフォルト：https://app.growthbook.io）。リンク：<host>/features/<flag-id>。

引き継ぎ先

• flag-toggle — 環境内でフラグを有効にします
• flag-rules — ルールを追加します（適切なルール種別のスキルにルーティングします）
• flag-default-value — ルールが一致しない場合に提供されるフォールバック値を変更します
• flag-metadata — 作成後にプロジェクト、タグ、説明、または所有者を設定します
• flag-experiment — このフラグを A/B 実験に接続します
• experiment-design — ユーザーが実際に完全な A/B テストを希望している場合に使用します（先に実験を作成し、その後にフラグを作成します）