flag-search

flag-search

GrowthBook のフィーチャーフラグを検索、一覧表示し、監査します。3 つの用途でこのスキルを共有します。全件の一覧表示、条件による絞り込み検索、クリーンアップ候補を見つけるための古いフラグの監査です。

読み取り専用です。このスキルで書き込みが行われることはありません。

すべての API 呼び出しは、バンドルされたヘルパー ${CLAUDE_PLUGIN_ROOT}/scripts/gb-call を通じて行います。使用するには、GB_API_KEY を環境変数に設定するか、/growthbook:gb-setup によって ~/.config/growthbook/.env に書き込む必要があります。

ワークフロー

ユーザーのリクエストに合った手順を選びます。

手順 A — 全件の一覧表示（「どのようなフラグがありますか？」）

まず、軽量なキー一覧を取得します。

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

すべてのフラグ ID が文字列配列として返されます。ページネーションはなく、最も低コストの呼び出しです。件数を示し、パターンが見られる場合はプレフィックスでグループ分けします（checkout-*、payments-*、infra-*）。

全件または一部の詳細をユーザーが求めている場合は、ページネーションを使用します。

gb-call GET '/api/v2/features?limit=100'
gb-call GET '/api/v2/features?limit=100&offset=100'   # next page

1 ページあたりの上限は 100 件です。返された件数が 100 件未満になるまで、offset を変えて繰り返します。

組織でプロジェクトを使用している場合は、プロジェクト別に出力をグループ分けします。孤立したテスト／デバッグ用エントリーと思われるフラグキー（test-、temp-、debug-、delete-me）も確認します。

手順 B — 条件による検索

クエリパラメーターを使って /api/v2/features の一覧エンドポイントを呼び出し、結果を絞り込みます。利用可能なフィルターは次のとおりです。

# By project:
gb-call GET '/api/v2/features?projectId=<project-id>'

# By tag (exact match, single tag):
gb-call GET '/api/v2/features?tag=<tag>'

API がサポートしていないフィルター（オーナー、環境の状態、値の型）については、全件を取得して、レスポンスのフィールドを使ってクライアント側で絞り込みます。

よくある検索：

リクエスト	方法
「X が所有するフラグ」	すべて取得し、owner.email で絞り込みます
「ブール型のフラグ」	すべて取得し、valueType === "boolean" で絞り込みます
「本番環境で有効なフラグ」	すべて取得し、environmentSettings.production.enabled === true で絞り込みます
「ルールのないフラグ」	すべて取得し、rules.length === 0 で絞り込みます
「payments タグの付いたフラグ」	GET /api/v2/features?tag=payments
「プロジェクト Y のフラグ」	プロジェクト名から ID を解決し、GET /api/v2/features?projectId=<id> を実行します

大規模な組織でクライアント側の絞り込みを行う場合は、まず全件をページネーションで取得してから絞り込みます。

Path C — 古いフラグの監査（「整理できるものは？」）

GrowthBook では、次の両方の条件を満たすフラグを古いとみなします。（a）2週間更新されていないこと、（b）アクティブな環境がない、またはすべてのルールでトラフィックの100%が単一のバリエーションにルーティングされていること。

Step C-1: 監査するフラグ ID を取得します。

ユーザーが明示的に指定したリスト、コードベースの grep、またはすべての ID の取得のいずれかを使用します。

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

Step C-2: 古さのチェックを実行します。

このエンドポイントでは、ID のリストを明示的に指定する必要があります（「古いフラグをすべて検索」するショートカットはありません）。

gb-call GET '/api/v2/stale-features?ids=flag-a,flag-b,flag-c'

Step C-3: 結果を解釈します。

各フラグには staleReason が設定されます。

staleReason	意味	対応
rules-one-sided	すべてのルールでトラフィックの100%が単一の値にルーティングされています。リリース済みの機能と思われます	安全に整理できます。勝者の値をコードに直接埋め込みます
no-rules	フラグにルールがありません	defaultValue がすでにコードに直接埋め込まれている場合は、安全に削除できます
toggled-off	すべての環境で無効になっています	不要になっている場合は、安全に削除できます
abandoned-draft	最近のアクティビティがないドラフトが開かれています	ドラフトを確認し、破棄するか続行します
never-stale	古さの検出対象から明示的に除外されています	スキップします。永続的に使用する意図のあるフラグです（キルスイッチ、運用トグルなど）
recently-updated	直近2週間以内に更新されています	まだ古くありません。後で再確認します
active-draft	アクティブなドラフトの改訂が進行中です	誰かが作業中のため、そのままにします
has-dependents	他のフラグがこのフラグを前提条件として指定しています	依存するフラグを更新せずに安全に削除することはできません。まず flag-graph を使用します
active-experiment	実行中の実験に関連付けられています	先に experiment-stop で実験を停止します
has-rules	片側に限定されていないアクティブなルールがあります	引き続き使用中です

Step C-4: レポートを提示します。

推奨事項ごとにまとめます。

1. 整理候補（launched、unused、abandoned）— 推奨する置き換え値を提示します
2. 除外対象（never-stale）— 別に一覧表示し、整理の推奨には含めません
3. 引き続きアクティブ — スキップします

候補の defaultValue と勝者となるルール値を提示します。削除する前にコードへ直接埋め込むために必要です。

何も削除しないでください。実際の削除は flag-cleanup に引き継ぎます。

ガードレール

• /stale-features には ID の明示的な指定が必要です。「古いフラグをすべて検索」するエンドポイントはありません。ユーザーが ID を指定しない場合は、先に /feature-keys から取得します。
• /feature-keys はページネーションなし、/features はページネーションあり（1ページあたり100件）です。 ID の全件一覧には /feature-keys を、詳細の検索には /features を使用します。
• neverStale: true のフラグは整理の推奨対象から除外します。 staleReason: "never-stale" として表示されます。別に提示しますが、削除を提案してはいけません。
• 古いかどうかを独自に推測しないでください。 正式な判定には /stale-features を使用します。GrowthBook 独自のルールが組み込まれており、ローカルでは算出できない置き換え値も提示されます。
• 大規模な組織でクライアント側のフィルターを使用すると、処理に時間がかかることがあります。 レート制限は60 rpmです。数百件のフラグをページネーションで取得する場合は、進捗を知らせてください。
• v2 のルールはフラットです。 v2 では、rules 配列はフラグオブジェクトのトップレベルにあり、各ルールは allEnvironments／environments のスコープを持ちます。v1 のように各環境の下にネストされているわけではありません。
• 読み取り専用です。 このスキルでは POST、PUT、PATCH、DELETE を絶対に実行しないでください。削除は flag-cleanup に引き継ぎます。

使用するエンドポイント

• GET /api/v2/feature-keys — ID の全件一覧。ページネーションの上限はありません
• GET /api/v2/features — 設定全体を含むページネーション付き一覧（limit、offset、projectId、tag フィルター）
• GET /api/v2/features/:id — 単一のフラグの設定全体
• GET /api/v2/stale-features?ids=a,b,c — 古さの監査（明示的な ids が必要）
• GET /api/v1/projects — プロジェクト名を ID に変換して、プロジェクトを指定した検索に使用

引き継ぎ

• flag-graph — 特定のフラグの依存関係を追跡するため（何に依存しているか、何がそのフラグに依存しているか）
• flag-cleanup — Path C で見つかったクリーンアップ候補をアーカイブまたは削除するため
• flag-targeting、flag-rules — 更新が必要なフラグを特定した後に変更を加えるため
• flag-revisions — 検索で見つかったフラグに未処理のドラフトがあるか確認するため