flag-revisions

flag-revisions

GrowthBook の機能フラグにある下書きリビジョンを確認、管理します。フラグの変更はすべて、公開前に下書きリビジョンを経由します。これは「現在進行中のものは何か？」を確認するためのスキルです。未完了の下書きを確認し、ステータスを把握して、ライフサイクル（作成、破棄）を管理するために使用します。実際のフラグ変更（ルール、メタデータ、トグル、デフォルト値）は、関連する flag-* 書き込みスキルで処理され、下書きも自動的に作成、管理されます。

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

リビジョンのステータス一覧

ステータス	意味	次に行うこと
draft	編集中で、まだ送信されていません	さらに編集してから、レビューをリクエストするか公開します
pending-review	レビューがリクエストされ、承認待ちです	レビュアーが flag-review で判定を送信します
approved	承認済みで、公開可能です	flag-publish で公開します
changes-requested	レビュアーが問題を指摘しました	作成者が下書きを編集し、レビューを再リクエストします
published	公開済みで、変更できません	flag-publish で元に戻せます
discarded	破棄されました	これ以上の対応は不要です
pending-parent	ランプスケジュールによって自動管理されています	手動で破棄しないでください

ワークフロー

ユーザーのリクエストに合った経路を選択します。

経路 A — 特定の機能のアクティブな下書きを一覧表示する

ユーザー自身の下書きを表示するか、このフラグのすべての下書きを表示するかを確認してから、適切なクエリを実行します。

# User's own active drafts:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts&mine=true'

# All active drafts on this flag:
gb-call GET '/api/v2/features/<id>/revisions?status=all-drafts'

all-drafts は、4 種類すべてのアクティブな下書きステータス（draft、pending-review、approved、changes-requested）を対象にします。v2 では status を省略しても同じ結果になります。一部のステータスに絞り込むには、?status=draft,pending-review を指定します。

各リビジョンについて、バージョン番号、ステータス、作成者、日付、コメントを提示します。対応が必要な項目があれば明示します。pending-review ではレビュアーによる対応が必要で、changes-requested では作成者による対応が必要です。

経路 B — すべての機能から自分の下書きを一覧表示する

gb-call GET '/api/v2/flag-revisions?mine=true&status=all-drafts'

組織内のすべてのアクティブな下書きを表示するには、mine=true を省略します。v2 では status を省略すると、デフォルトで all-drafts が指定されます。

見やすさのため、機能ごとに出力をまとめます。対応が必要な下書きの件数を提示します。

経路 C — 特定のリビジョンを確認する

gb-call GET /api/v2/features/<id>/revisions/<version>

公開中のバージョンからの変更点を提示します。defaultValue、rules 配列、メタデータフィールド、環境ごとの environmentsEnabled、prerequisites を確認します。また、baseVersion（この下書きの分岐元である公開バージョン）と status も表示します。

バージョン番号が分からない状態で、最後に更新されたアクティブな下書きを取得するには、最初にユーザー自身の下書きを表示するか、誰かが作成した最新の下書きを表示するかを確認します。これにより、チームメイトの下書きが意図せず選ばれるのを防げます。

# User's own most recent draft:
gb-call GET '/api/v2/features/<id>/revisions/latest?mine=true'

# Most recently updated draft by anyone:
gb-call GET /api/v2/features/<id>/revisions/latest

単一のリビジョンを返します。複数の下書きが開いている場合、最後に更新されたものが自動的に選ばれます。すべての下書きを表示するには、代わりに経路 A を使用してください。

パス D — 下書きの作成：暗黙的と明示的

下書きを作成する方法は2つあります。どちらも有効で、どちらを使うかは状況によって異なります。

暗黙的（すべての書き込みスキルでのデフォルト）： 書き込みエンドポイントのバージョンとして new を渡します。サーバーは新しい下書きを自動的に作成するか、直近で更新された未完了の下書きに変更を追加します。

# Example — the "new" magic used in write skills:
echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/new/default-value -

次の場合に使用します：変更が1つだけの場合、または未完了の下書きが1つだけで、そこに変更を追加するのが適切な場合。

明示的（事前作成してから指定）： 最初に空の下書きを作成し、バージョン番号を控えてから、それ以降のすべての書き込み呼び出しで new ではなく、その特定のバージョンを指定します。これは3段階のフローです。先の段階に進まないでください。

フェーズ 1 — セットアップ（フラグを変更する前）：

echo '{"comment":"<optional intent note>"}' | gb-call POST /api/v2/features/<id>/revisions -
# Returns { revision: { version: <N>, status: "draft", ... } }

バージョン番号 <N> を控えてください。フェーズ 2 のすべての変更で、このバージョンを指定する必要があります。

フェーズ 2 — すべてのフラグ変更（次に進む前にすべて完了させる）：

該当する書き込みスキル（flag-targeting、flag-toggle、flag-metadata、flag-default-value、flag-prerequisites など）を使用し、すべてのエンドポイントパスで new を <N> に置き換えます。

echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/<N>/default-value -
echo '<payload>' | gb-call POST /api/v2/features/<id>/revisions/<N>/rules -
echo '<payload>' | gb-call PUT /api/v2/features/<id>/revisions/<N>/metadata -

意図したすべての変更を適用するまで、フェーズ 3 に進まないでください。

フェーズ 3 — 公開（すべての変更が完了した後にのみ実行）：

バージョン <N> を指定して、flag-publish に引き継ぎます。

次の場合にこのパターンを使用します：既存の未完了の下書きとは独立した状態から始めたい場合、同じリビジョンに反映する必要がある複数の変更をまとめて行う場合、または複数の下書きが開いていて、編集対象を指定する必要がある場合。

注：現在のライブバージョンではなく、特定の公開済みリビジョンから分岐する場合は、フェーズ 1 の本文に baseVersion を渡せます。

パス E — 下書きの破棄

gb-call POST /api/v2/features/<id>/revisions/<version>/discard

破棄する前に、次のように確認してください：「<flag-id> のリビジョン <version> を破棄しますか？これは取り消せません。この下書きに保留中の変更はすべて失われます。」

終端以外のステータスであれば、どれでも破棄できます。draft、pending-review、approved、changes-requested はすべて直接破棄できます。サーバーによってブロックされるのは published と discarded のみです。

ガードレール

• status にはカンマ区切りの値を指定できます。 ?status=draft,approved は、いずれかのステータスに一致するリビジョンを返します。4つのアクティブな下書きステータスすべてを対象にするには、省略形の ?status=all-drafts を使用します。v2 エンドポイントでは、status を省略すると all-drafts がデフォルトになります。
• pending-parent リビジョンは自動管理されます。 ランプスケジュールの一部として自動的に作成、公開されます。手動で破棄しないでください。停止しているように見える場合は、GrowthBook サポートに連絡してください。
• フラグには複数の未完了の下書きが存在する場合があります。 常にすべて表示し、1つだけだと思い込まないでください。
• version=new は標準的な書き込みパターンです。 他の書き込みスキルでは、下書きをアトミックに作成または再利用するために使用します。ユーザーが編集前に空の下書きを求めている場合にのみ、POST /revisions を明示的に呼び出してください。
• 破棄は取り消せません。 下書きと、保留中の変更はすべて失われます。ユーザーが「やり直します」の一部として何気なく「破棄」と言った場合は、変更が保持されないことを理解しているか確認してください。
• changes-requested は破棄済みとは異なります。 下書きは引き続き存在し、編集できます。作成者が問題を修正し、flag-review を通じて再度レビューをリクエストします。
• このスキルは読み取りと管理のみを行います。 フラグのルール、メタデータ、デフォルト値、環境ごとの切り替えを変更するには、該当する書き込みスキルを使用してください。

使用するエンドポイント

• GET /api/v2/features/:id/revisions — 機能のリビジョン一覧（ステータス、作成者、上限、オフセットの各フィルター）
• GET /api/v2/flag-revisions — すべての機能にわたるリビジョン一覧（mine、status、featureId、author の各フィルター）
• GET /api/v2/features/:id/revisions/:version — 特定のリビジョンを確認
• GET /api/v2/features/:id/revisions/latest — 最新の下書きを取得（mine=true フィルターを使用可能）
• POST /api/v2/features/:id/revisions — 新しい空の下書きを作成
• POST /api/v2/features/:id/revisions/:version/discard — 下書きを破棄

引き継ぎ

• flag-review — 下書きの承認レビューを依頼または提出するためのものです
• flag-publish — 下書きを公開したり、マージコンフリクトを解決したり、以前のリビジョンに戻したりするためのものです
• flag-rules、flag-targeting、flag-toggle、flag-metadata、flag-default-value、flag-prerequisites — 下書きを作成および変更するライティングスキルです