flag-review

flag-review

GrowthBook のフィーチャーフラグのドラフト改訂版について、承認レビューを依頼し、提出します。組織で承認ワークフローが設定されている場合にのみ必要です。承認が不要な場合は、flag-publish でレビュー手順なしに一連の処理を完了できます。

このスキルでは、ドラフト作成者（レビューを依頼する側。自己承認はできません）とレビュー担当者（レビュー結果を提出する側）の 2 つの役割を使用します。

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

承認フロー

draft → [request-review] → pending-review → [approve]           → approved → [publish]
                                           → [request-changes]  → changes-requested → [edit + re-request] → pending-review
                                           → [comment]          → pending-review (status unchanged)

ワークフロー

パス A — レビューを依頼する（承認を求めるドラフト作成者）

1. 改訂版を特定します。ユーザーがバージョン番号を指定した場合は、それを使用します。指定がない場合は、まず /latest を試します（ドラフトが 1 つの場合の標準的な方法）。必要に応じて一覧表示に切り替えます。

   gb-call GET /api/v2/features/<id>/revisions/latest
   # or if version is known:
   gb-call GET /api/v2/features/<id>/revisions/<version>
   

   draft または changes-requested のステータスを受け付けます。それ以外のステータスの場合は、ステータスを提示し、flag-revisions のステータス表を使って意味を説明します。

2. レビューを依頼します。

   echo '{"comment":"<optional context for reviewers>"}' \
     | gb-call POST /api/v2/features/<id>/revisions/<version>/request-review -
   

   改訂版のステータスは pending-review に変わります。公開するには、flag-publish を使う前にレビュー担当者の承認が必要だとユーザーに伝えます。自己承認はできず、別のチームメンバーがレビューする必要があることも伝えてください。

パス B — レビューを提出する（pending-review の改訂版をレビューする担当者）

1. 改訂版を特定します。バージョン番号だけでは不十分です。バージョン番号はフラグごとのカウンターであり、全体で一意ではないため、フラグ ID も必ず必要です。ユーザーが持っている情報を確認し、それに応じて検索します。

   フラグ ID とバージョンがわかっている場合 → 直接取得します。

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

   フラグ ID はわかっているが、バージョンが不明な場合 → そのフラグで pending-review の改訂版を一覧表示します。

   gb-call GET '/api/v2/features/<id>/revisions?status=pending-review'
   

   作成者のメールアドレスまたは userId がわかっている場合 → 作成者で機能横断検索します。

   gb-call GET '/api/v2/flag-revisions?status=pending-review&author=<email-or-userid>'
   

   作成者の名前はわかっているが、メールアドレスは不明な場合 → pending-review の改訂版をすべて取得し、クライアント側で createdBy に名前が一致するものを絞り込みます。

   gb-call GET '/api/v2/flag-revisions?status=pending-review'
   

   各改訂版には createdBy フィールド（表示名または "API"）があります。createdBy にユーザーが指定した名前を含む項目に絞り込み、先に進む前にユーザーに確認します。

   何もわかっていない場合 → 同じ広範な検索を行い、すべての結果を表示して、該当するものをユーザーに特定してもらいます。

2. 内容が単純でない場合は、まず GrowthBook の UI を開くか確認します。並べて表示される差分と承認コントロールのほうが、テキストよりわかりやすいためです。

   # macOS:
   open <host>/features/<flag-id>?v=<version>
   # Linux:
   xdg-open <host>/features/<flag-id>?v=<version>
   

   GB_API_URL の api. を app. に置き換えて <host> を求めます。レビュー担当者が UI での作業を希望する場合は、ここで終了します。

   API を使ってレビューする場合は、改訂版と公開中のフィーチャーの両方を取得し、適切な変更前後の差分を表示します。

   gb-call GET /api/v2/features/<id>/revisions/<version>   # draft state
   gb-call GET /api/v2/features/<id>                       # current live state
   

   公開中のフィーチャーとドラフトのフィールドを比較し、変更されたルール（追加／編集／削除）、defaultValue の変更、メタデータの変更、環境トグルの変更、前提条件の変更を提示します。

3. レビュー担当者に、実行する操作を確認します。

   • approve — 変更内容に問題がなく、公開可能です
   • request-changes — 問題が見つかったため、作成者による更新が必要です
   • comment — フィードバックのみで、ステータスは変更しません

4. レビューを提出します。

   echo '{"action":"approve","comment":"<optional>"}' \
     | gb-call POST /api/v2/features/<id>/revisions/<version>/submit-review -
   

   ステータスの遷移：

   • approve → approved — flag-publish を使って公開するようユーザーに伝えます
   • request-changes → changes-requested — 次に何が起こるか（作成者が編集し、再度レビューを依頼する）をレビュー担当者に伝えます
   • comment → pending-review のまま — コメントが記録されます

パス C — レビューのステータスを確認する

バージョンが不明な場合は、まず /latest を試します。

gb-call GET /api/v2/features/<id>/revisions/latest
# or with a known version:
gb-call GET /api/v2/features/<id>/revisions/<version>

ステータスと次に必要な対応を報告します。

ステータス	次のステップ
draft	準備ができたら作成者がレビューを依頼します
pending-review	レビュー担当者が判断を提出します
approved	作成者が flag-publish を使って公開します
changes-requested	作成者がドラフトを編集してから、再度レビューを依頼します

ガードレール

• 自己承認はサーバー側でブロックされます。 API は、ドラフトの作成者本人が送信したレビューを拒否します。ユーザーが自分でドラフトを作成したと言った場合は、submit-review を呼び出す前に処理を止めます。「このドラフトはあなたが作成しました。別のチームメンバーによる承認が必要です。」そうでない場合はサーバーに判定を任せ、エラーが発生した場合はユーザーに伝えます。
• レビューをリクエストできるのは、ステータスが draft または changes-requested の場合のみです。 それ以外のステータスでユーザーが試みた場合は、現在のステータスを伝えます。
• レビューを送信できるのは、ステータスが pending-review の場合のみです。 一致しない場合は、現在のステータスを伝えます。
• changes-requested は破棄されません。 ドラフトは引き続き存在します。作成者が編集し、Path A で再度レビューをリクエストします。作成者が変更を明示的に破棄したいと希望しない限り、破棄を提案しないでください。
• 変更時のレビューリセット。 組織でこの設定が有効になっている場合、approved のドラフトを編集すると、ステータスが draft に戻ります。承認済みのリビジョンを編集しようとしているユーザーには、次のように警告します。「このリビジョンを編集すると承認ステータスがリセットされ、レビューを再度リクエストする必要があります。」
• 承認 ≠ 公開。 approved のドラフトは、まだ公開されていません。作成者は引き続き flag-publish を実行する必要があります。
• このスキルでは公開しません。 承認後は flag-publish に引き継ぎます。

使用するエンドポイント

• GET /api/v2/features/:id/revisions/:version — 操作前にリビジョンを確認する
• GET /api/v2/features/:id/revisions（status フィルター）— フラグのレビュー待ちリビジョンを検索する
• GET /api/v2/flag-revisions（status、mine フィルター）— すべてのフラグからレビュー待ちリビジョンを検索する
• POST /api/v2/features/:id/revisions/:version/request-review（本文：任意のコメント）
• POST /api/v2/features/:id/revisions/:version/submit-review（本文：action と任意のコメント）

引き継ぎ先

• flag-revisions — すべての未完了ドラフトを一覧表示して確認する
• flag-publish — 承認後、ドラフトを公開する