feature-flags

feature-flags

GrowthBook のフィーチャーフラグ用ドメインルーターです。各フラグのワークフローは、references/ 内のリファレンスファイルにあります。このルーターを読み、ユーザーの意図に合ったワークフローを選んでから、そのファイルを1つだけ読み、手順に従ってください。

フラグでは v2 API（/api/v2/features）を使用します。環境、プロジェクト、保存済みグループは v1 です。

すべての API 呼び出しには、同梱のヘルパーを使用します。Claude Code プラグインのインストールでは ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call（プラグインのルート）にあります。npx skills install では、このスキルのディレクトリを基準とした scripts/gb-call にあります。このパスを一度解決し、リファレンスの例で gb-call と記載されている箇所では、そのパスに置き換えてください。gb-call が PATH にあると想定しないでください。ヘルパーは、まず環境変数から GB_API_KEY を読み取り、次に ~/.config/growthbook/.env（gb-setup によって書き込まれます）へフォールバックします。環境変数が優先されます。

ワークフローで GrowthBook の UI リンクを提示する必要がある場合、シェルを実行できるランタイムでは、会話ごとに一度 gb-call app-origin を呼び出し、返された信頼できるオリジンをワークフローやドメインをまたいで保持し、リファレンスファイル内のルート相対 UI パスの先頭に付けてください。オリジンがすでにコンテキストにある場合は、それを再利用してください。リンクごとにコマンドを呼び出さないでください。信頼できるアプリのオリジンをすでに認識している埋め込みアダプターや MCP アダプターでは、同じパスを直接解決できます。GB_API_URL からアプリのオリジンを導出しないでください。セルフホスト設定が不完全なため app-origin が拒否された場合は、gb-setup に案内してください。

ワークフローを選ぶ

ユーザーが行おうとしていることに基づいて、以下から1つだけ読んでください。2つが当てはまりそうな場合は、より具体的な方を読んでください。

こちらを読む	ユーザーの目的
references/flag-create.md	新しいフラグを作成する
references/flag-search.md	プロジェクト、タグ、オーナー、環境の状態、古さを基準にフラグを検索、一覧表示、監査する（読み取り専用）
references/flag-graph.md	フラグの依存先、依存元、および関連付けられた実験やホールドアウトを追跡する（読み取り専用）
references/flag-toggle.md	環境内でフラグを有効または無効にする（キルスイッチ）
references/flag-targeting.md	強制ルール／ロールアウトルール、条件、保存済みグループ、ルールレベルの前提条件を追加、編集、削除する
references/flag-rules.md	ルールを一覧表示、並べ替え、削除する、または適切なルールタイプのワークフローに案内する
references/flag-experiment.md	A/B テストをフラグ経由で実行するため、experiment-ref ルールを追加する
references/flag-schedule.md	開始日時や終了日時を設定して、ルールに時間制限を設ける
references/flag-ramp.md	複数段階のランプスケジュール（時間経過に伴う段階的な対象範囲の拡大）を作成、または進める
references/flag-monitoring.md	監視付き／安全なロールアウトを設定する（ランプにガードレール指標と任意の自動ロールバックを組み合わせる）
references/flag-prerequisites.md	別のブール値フラグを前提条件として、フラグ全体に制限をかける
references/flag-default-value.md	どのルールにも一致しない場合に返される値を変更する
references/flag-metadata.md	説明、オーナー、プロジェクト、タグ、カスタムフィールド、JSON スキーマを変更する
references/flag-revisions.md	開いているドラフト、所有者を確認し、ドラフトを開始または破棄する
references/flag-review.md	レビューを依頼する、またはドラフトを承認、変更依頼、コメントする
references/flag-publish.md	ドラフトを公開する、マージ競合を解決する、元に戻す、または破棄する
references/flag-cleanup.md	古くなったフラグをアーカイブまたは削除する（先にコード内の値をインライン化する）

読み始める前に確認すべき曖昧さ：「フラグをオフにする」が環境全体を指す場合は flag-toggle、1つのルールを指す場合は flag-rules です。「これをロールアウトする」が一度限りの割合指定を指す場合は flag-targeting、スケジュールを指す場合は flag-ramp、ガードレール指標による制御も必要な場合は flag-monitoring です。

共通規約

以下は、すべてのフラグワークフローに共通します。参照ファイルでは、これらを前提としています。

• すべての書き込みはドラフトリビジョンを介して行います。 ルール、メタデータ、デフォルト値、トグルはすべてドラフトを作成または更新し、その後に公開する必要があります。公開手順は flag-publish が担当し、書き込みワークフローはそこに引き継ぎます。
• 一連の処理ではドラフトのバージョンを引き継ぎます。 1つのセッションで複数の書き込みワークフローを続けて実行する場合は、new を再送信せず、前のステップから返された version を引き継ぎます。new はドラフトを自動作成または再利用するため、処理の途中でチームメイトの並行作業中のドラフトが黙って選ばれる可能性があります。new（または /revisions/latest?mine=true）を使うのは、新たに作業を開始するときに限ります。
• rules の POST は配列全体を置き換えます。 v2 のルール配列はトップレベルにあり、environments または allEnvironments によってスコープが指定されます。一部だけを編集する場合は、まず現在のルールを GET してください。
• defaultValue は、フラグの値型にかかわらず、常に文字列です。
• ユーザーにはフラグキー（id）を表示し、内部の Mongo id は表示しないでください。 UI のパス /features/<key> にリンクします。
• UI リンクはルート相対パスです。 GB_API_URL から GrowthBook の UI オリジンを推測しないでください。API と UI のオリジンが同じホスト名とは限りません。信頼できるアプリのオリジンがある実行環境ではパスを解決してもかまいませんが、それ以外の場合は推測せず、ルート相対パスをそのまま提示してください。
• ディープリンクは表示し、開かないでください。 このスキルには意図的にブラウザー権限がありません。パスを提示し、実行環境で解決できる場合はユーザーにクリックしてもらいます。

失敗時の動作

バックエンドのハンドラーで確認済みの動作です。以下を混同しないでください。

• 公開エンドポイントの 400 は、承認が必要であることを意味します（This revision requires approval before publishing）。ポリシーゲートは想定どおり機能しています。references/flag-review.md に引き継いでください。
• 副作用として公開するパスでの 403 も、異なるコードパスから同じ状況を示します。環境トグルと {archived} を使った POST /v2/features/<id> はどちらも createAndPublishRevision を経由し、不正なリクエストエラーではなく権限エラーを発生させます。レスポンス本文を確認してください。レビューに触れていない場合、トークンに必要な権限がなく、問題は GB_API_KEY にあります。
• 公開時の 409 は、ドラフトのベースが古くなっていること、つまりライブフラグが更新されたことを意味します。自動でリベースしないでください。処理を止めて競合を示し、ユーザーに解決してもらいます。
• 公開時の 422 は、公開ゲートによってブロックされていることを意味します。本文には、ignoreWarnings だけを使った再試行で解除できるゲートと、権限が必要なゲートが記載されています。

読み取り専用と書き込み

flag-search と flag-graph は読み取り専用であり、その状態を維持する必要があります。これらが POST、PUT、DELETE を実行することはありません。それ以外のワークフローはすべて書き込みを行い、それぞれ確認の要件を明示しています。flag-cleanup のアーカイブ、検証、削除というゲートは、プロダクトの安全性を守るための一時停止であり、変更の確認ではありません。ユーザーが確信しているように見えても、省略しないでください。

予算

GrowthBook は 60 rpm でレート制限を行います。flag-search と flag-graph はページ分割されたリストに対してファンアウトするため、ループの上限を明示し、わかりにくい場合は呼び出し予算に触れてください。

引き継ぎ

• A/B テストの設計、開始、分析、停止は experiments スキルに引き継ぎます。フラグの実験参照ルールはこのスキルの担当ですが、実験そのものは担当外です。
• プロダクトデータのグラフ化、またはメトリクスやファクトテーブルの参照は analytics スキルに引き継ぎます。
• gb-call が GB_API_KEY の欠落または無効を報告した場合は gb-setup に引き継ぎます。