mcpField
V
vercel-flags

vercel-flags

github.com/vercel開発62852 回インストール3 日前に更新
リポジトリ

vercel-flags について

Vercel Flagsで機能フラグを計画、作成、実装、整理するためのスキルです。開発者向けに、CLIでの管理やスタック別の統合方法、段階的なロールアウトと実験を案内します。

主な機能

  1. 01フラグの種類とターゲティングの計画
  2. 02Vercel CLIによるフラグ管理
  3. 03スタック別の統合実装
  4. 04ロールアウトとA/Bテスト
  5. 05フラグの検証と整理

活用シーン

  1. 01割合指定のロールアウト計画
  2. 02フラグの作成や変更
  3. 03アプリへのキルスイッチ追加
  4. 04終了したフラグの整理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/vercel/flags --skill vercel-flags

インストール後、Claude Code で/vercel-flagsを入力して読み込まれたか確認します。

同梱ファイルreferences/cleanup.mdreferences/cli.md

詳細

Vercel Flags

Vercel Flags は、Vercel のフィーチャーフラグプラットフォームです。フラグは Vercel ダッシュボードまたは vercel flags CLI で作成・管理し、アプリ内でサーバーサイド評価できます。再デプロイせずに、環境（Development、Preview、Production）ごとに切り替えられます。

このスキルを使って、機能をフラグで管理する方法を決め、フラグを作成・変更し、ロールアウトや実験を実施します。アプリのコードは、スタックに合ったスキルを使って記述してください（アプローチの選択を参照）。CLI の手順をユーザー向けの「次のステップ」として残さず、自分で実行してください。

リクエストの振り分け

  • 計画（「これをフラグで管理する」「10％にロールアウトする」「料金ページで A/B テストを行う」「キルスイッチを追加する」など）：フラグの計画に従い、次にアプローチの選択に進みます。
  • コード変更なしでフラグを作成または管理する（作成、確認、有効化、設定、分割、ロールアウト、ルール、アーカイブ）：CLI でフラグを管理するに従います。認証済み CLI が必要です。SDK パッケージ、Toolbar、Flags Explorer、.env.local は不要です（FLAGS_SECRET を読み取る vercel flags override は除きます）。
  • プロジェクト間でフラグを共有する：Project Connectionsに従って同じチーム内のプロジェクトを接続し、次にコンシューマーアプリケーションを設定します。
  • フラグを整理または削除する（「このフラグを削除する」「古いフラグを整理する」「このフラグをコードに直接埋め込む」など）：references/cleanup.mdに従い、アーカイブする前にライフサイクルと安全性を確認します。
  • すでに Flags SDK を使っているアプリにフラグを追加する（package.json に flags がある）：すぐに flags-sdk スキルを読み込みます。このスキルは Vercel 上にフラグを作成し、コード内で宣言します。
  • それ以外の場合にコードへ実装する：アプローチの選択に従い、適切なスキルまたはリファレンスを読み込みます。アプリのリポジトリ内では、曖昧なリクエストを計画、作成、実装まで求めているものとして扱います。

アプローチの選択

コードを書く前にプロジェクトを確認してください。

  • すでに別のフラグプロバイダーを使用している（Statsig、LaunchDarkly、PostHog、GrowthBook など）：そのプロバイダーを使い続けます。Next.js または SvelteKit では、Flags SDK がアダプターを介して接続します。flags-sdk スキルを読み込んでください。それ以外のスタックでは、プロバイダー独自の SDK を使います。そのプロバイダーのロールアウト、ターゲティング、実験は、vercel flags ではなく、プロバイダー独自のダッシュボードで設定します。このスキルの CLI とライフサイクルのセクションは適用されません。
  • まだプロバイダーを使っていない：Vercel Flags を使います。スタックに合わせて統合方法を選択します（SDK）。
    • Next.js または SvelteKit：Flags SDK（flags + @flags-sdk/vercel）を使います。Flags Explorer との統合と、静的ページの事前計算に対応しています。flags-sdk スキルを読み込んでください。利用できない場合は、npx skills add vercel/flags@flags-sdk を提案します（自動インストールはしないでください）。
    • その他のフレームワークまたはプレーンなサーバー（例：Express）：@vercel/flags-core を使います。その他のフレームワークを参照してください。
    • プロバイダーの移植性を求めている、またはすでに OpenFeature を使っている：Vercel Flags OpenFeature プロバイダー（OpenFeature と Vercel Flags の使用）を使います。

ダッシュボードと vercel flags CLI は、どの統合方法でも同じように使えます。

フラグを計画する

フラグを作成する前に、以下を決めてください。作成後に種類を変更することはできません。

  • 種類：オン／オフやキルスイッチには boolean を使用します。フラグでバリアントを選択する場合や設定を保持する場合は、string、number、json を使用します（フラグの種類）。
  • バリアント：ロールアウトの段階ではなく、動作に基づいて名前を付けます（control、new-checkout など）。
  • キー：ケバブケースで安定した値にし、CLI、ダッシュボード、コードで同じ文字列を使用します（flag() の key、または evaluate() の最初の引数）。
  • 環境：各環境には、それぞれの値またはターゲティングが適用されます。リリース時に Development、Preview、Production でどの値を使うか計画してください。
  • ターゲティング：パーセンテージロールアウトや A/B 分割では、user.id のような、振り分けに使う安定した識別子が必要です。まず Flags → Entities でエンティティと属性を定義してください。アプリは評価コンテキストから同じ名前を返す必要があります（エンティティ）。
  • フォールバック：フラグがアーカイブ済み、未作成、または評価に失敗した場合にアプリが使用する値です。コードでは defaultValue になります。
  • 終了：長期的な運用スイッチでない限り、フラグは一時的なものです。references/cli.md — Lifecycle and safety で削除する順序を計画してください。

CLI でフラグを管理する

CLI では Vercel アカウントの認証を使用します。SDK キーと vercel env pull はアプリケーションの認証情報であり、CLI の前提条件ではありません。

前提条件：Vercel CLI をインストールし、認証済みである必要があります。インストールされていない場合は、pnpm i -g vercel を実行してください。認証またはリンクに関する問題がある場合は、利用可能であれば vercel-cli スキルに従ってください。利用できない場合は、npx skills add vercel/vercel@vercel-cli を提案し（自動インストールはしないでください）、それまでは vercel <command> --help を使用してください。

現在のサブコマンド一覧を確認するには vercel flags --help を実行し、サブコマンドを使用する前に vercel flags <cmd> --help を実行してください。references/cli.md では、--help だけでは分からない、CLI の概念とアプリの対応関係、昇格の順序、静的値とターゲティングモードの違い、アーカイブまたは削除の前に実行する確認について説明しています。

プロジェクトの指定

ローカルリンクを使わずに対象を選択するには、--project <name-or-id> と --scope <team> を使用してください。CLI が --project を拒否する場合は、先にアップグレードしてください（pnpm i -g vercel）。これらのオプションを指定しない場合、コマンドはリンク済みのプロジェクトを使用します。vercel project inspect --non-interactive を実行して、報告された所有者とプロジェクト名を確認してください。.vercel/ ディレクトリがあるだけでは、リンク済みである証拠になりません。link_required が報告された場合、プロジェクトはリンクされていません。ユーザーが指定したプロジェクトまたはチームと出力が異なる場合は、再リンクせずに処理を中断して確認してください。リンクされていないディレクトリでは、vercel link よりも --project／--scope を優先してください。対象プロジェクトが不明な場合は、ユーザーに確認してください。

一般的なフロー

まず必ず inspect を実行して、各環境で現在どの値が提供されているかを確認してください。また、CLI のキーはアプリケーションですでに宣言されているフラグに合わせてください。既存のフラグを採用する代わりに、フラグを新たに作成しないでください。

  • 作成：vercel flags create <key> --kind boolean --description "<description>"。キーがすでに存在する場合は、そのキーを採用してください。
  • オン／オフ：ブール型フラグには enable／disable、あらゆる種類のフラグで単一のバリアントを提供するには set <key> を使用します。これにより、環境は静的値モードになります。
  • 段階的なロールアウト：rollout <key> --by user.id ...（機能をロールアウトする）。
  • A/B テスト：split <key> --by user.id ...（A/B テストを実施する）。
  • ターゲティングルールとセグメント：rules、segments、targeting enable <key> を使用して、環境を静的値からターゲットとルールに切り替えます（バージョン 65 より前の CLI では use-targeting <key> を使用します）。
  • 検証：提供中の状態には inspect、履歴には versions、トラフィックが新しいバリアントに到達していることの確認には evaluations を使用します。
  • データファイル：datafile --environment <production|preview|development> --json を実行すると、デバッグ用に SDK が現在使用しているデータファイルを確認できます。
  • 廃止：まずコードを削除し（references/cleanup.md）、評価が行われていないことを確認してから archive を実行します。rm はアーカイブ済みのフラグにのみ使用してください。ライフサイクルと安全性に従ってください。

archive、unarchive、rm、update --remove-variant では確認が求められます。ユーザーの承認を得ている場合は --yes を渡してください。

認証情報

  • OIDC：Vercel 上では、アプリはプロジェクトの OIDC トークンで認証し、現在の環境の設定を評価します。ローカル開発では、vercel env pull により Development トークンが .env.local に書き込まれます（はじめに）。
  • プロジェクト接続：コンシューマープロジェクトの OIDC トークンを使って、同じチーム内の別プロジェクトのフラグを SDK キーなしで読み取れます。セットアップと最低バージョンについては、プロジェクト接続に従ってください。
  • SDK キー（FLAGS）：Vercel 外のアプリ、環境を明示的に選択する場合、またはチームをまたいでフラグを読み取る場合に使用します。各キーは単一の環境に紐付けられ、作成時に一度だけ表示されます（SDK キー）。CLI の認証に失敗した場合の復旧手段ではありません。
  • FLAGS_SECRET：プロジェクトで Vercel Flags を有効にすると、環境ごとに作成されます。Flags Explorer のオーバーライドとプリコンピュートコードの署名に使用され、vercel flags override は環境または .env.local から読み取ります。既存の値を保持し、通常のセットアップの一環としてローテーションしないでください。ローカルの値が見つからなくても、リモートの値が存在しないとは限りません。そのため、生成する前に対象環境を確認してください。値が不足している場合の生成方法については、flags-sdk スキルを参照してください。シークレットをターミナル、ログ、チャットに出力しないでください。

Flags Explorer

Flags Explorer は Vercel Toolbar のパネルで、アプリのフラグを一覧表示し、FLAGS_SECRET で署名された Cookie を使ってブラウザーごとにフラグをオーバーライドできます（Flags Explorer）。アプリはディスカバリーエンドポイントを通じてフラグを公開します。このエンドポイントは Flags SDK が生成します（flags-sdk スキル）。vercel flags override <key>=<value> を実行すると、同じ Cookie トークンがターミナルから生成されます。

その他のフレームワーク

Flags SDK のエントリーポイントがないフレームワークでは、@vercel/flags-core を直接使用してください（Core SDK）。モジュールスコープでクライアントを 1 つ作成し、リクエストハンドラー内で evaluate() または bulkEvaluate() を呼び出してください。どちらも初回使用時にクライアントを初期化します。モジュールスコープで client.initialize() を呼び出したり、ハンドラーが待機するための Promise をキャッシュしたりしないでください。

// src/flags.ts
import { createClient } from "@vercel/flags-core";

const client = createClient();

// Call from a request handler, not during module loading.
export async function showNewCheckout(userId: string): Promise<boolean> {
  const result = await client.evaluate<boolean>("new-checkout", false, {
    user: { id: userId },
  });
  return result.value;
}

OIDC を使用する場合、トークンはリクエストコンテキストから取得されるため、モジュールの読み込み時には存在しないことがあります。埋め込み定義であっても、トークンの project_id によってエントリを選択するためにトークンが必要です。また、ローカルの .env.local の認証情報によって、このタイミングの問題が見えなくなることがあります。明示的な初期化は任意ですが、認証情報が利用可能になってから行う必要があります。すでに開始された初期化 Promise を後から待機しても、リクエストコンテキスト内で初期化が行われるわけではありません。Vercel 以外では、SDK キーを渡してください：createClient(process.env.FLAGS)。

evaluate() の第 3 引数は評価コンテキストです。ロールアウトやルールでバケット分けできるように、そのエンティティ名と属性名を Flags → Entities で定義したものと一致させる必要があります。

参照

  • references/cli.md：vercel flags の各概念がアプリにどう対応するか（キー、種類、バリアント、フォールバック、ターゲティング属性、タイムスタンプ条件、認証、オーバーライド、埋め込み定義、データファイル）と、フラグを昇格、検証、削除、アーカイブする際のライフサイクルおよび安全性チェックリストについて説明します。
  • references/cleanup.md：コードからフラグを削除する方法について説明します。従うべきリポジトリのルール、収集すべき証拠、インライン化する値、作業を止めるタイミング、削除するもの、クリーンアップ PR に含める内容を扱います。

コメント

Markdown 対応