api-flags-posthog-flags

PostHog によるフィーチャーフラグ

クイックガイド： PostHog のフィーチャーフラグを使用して、段階的なロールアウト、A/B テスト、リモート設定を行います。クライアント側では useFeatureFlagEnabled フックを使用します。サーバー側では、ローカル評価を有効にした posthog-node を使用します。実験では、必ず useFeatureFlagPayload と useFeatureFlagEnabled を組み合わせてください。フラグを確認するたびに、undefined の読み込み状態を処理します。

---

<critical_requirements>

重要：このスキルを使用する前に

すべてのコードは CLAUDE.md のプロジェクト規約（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります

（実験では必ず useFeatureFlagPayload を useFeatureFlagEnabled または useFeatureFlagVariantKey と組み合わせてください。ペイロードフックは露出イベントを送信しません）

（サーバー側のローカル評価には必ずフィーチャーフラグ用のセキュア API キー（phs_*）を使用してください。この用途では個人用 API キーは非推奨です）

（フラグの読み込み中は必ず undefined の状態を処理してください。フラグがすぐに利用できると決めつけないでください）

（フラグのメタデータには必ず所有者と有効期限を含めてください。所有者のいないフラグは、放置された負債になります）

（複数箇所でフラグを使用する場合は、必ず単一の関数内にフラグの使用をまとめてください。これにより、クリーンアップ時にフラグのコードが取り残されるのを防げます）

</critical_requirements>

---

自動検出： PostHog のフィーチャーフラグ、useFeatureFlagEnabled、useFeatureFlagPayload、useFeatureFlagVariantKey、PostHogFeature、isFeatureEnabled、getFeatureFlag、段階的なロールアウト、A/B テスト、実験、多変量フラグ

使用する場面：

• 段階的なロールアウト（ユーザーの 10% にデプロイし、次に 50%、最後に 100% に拡大）
• 実験による A/B テスト（変更の影響を測定）
• キルスイッチ（デプロイせずに機能をすぐに無効化）
• リモート設定（コードを変更せずに動作を変更）
• ベータ機能のオプトイン（ユーザーが新機能を試せるようにする）
• ユーザーターゲティング（特定のコホートに機能を表示）

使用しない場面：

• 変更されることのない単純なオン／オフスイッチ（環境変数を使用してください）
• コンパイル時に確定する必要がある設定（ビルドフラグを使用してください）
• シークレットや機密データ（シークレット管理を使用してください）
• 常に有効にする機能（そのままコードをリリースしてください）

主なパターン：

• React フックによるクライアント側のフラグ評価
• パフォーマンス向上のためのサーバー側ローカル評価
• ブール値フラグと多変量フラグ
• パーセンテージターゲティングによる段階的なロールアウト
• A/B テストと実験
• リモート設定用のペイロード
• ローカル開発時のオーバーライド
• フラグのクリーンアップとライフサイクル管理

---

詳細リソース：

• examples/core.md - ブール値フラグ、多変量フラグ、PostHogFeature コンポーネント、ペイロード、実験、ロールアウト、ライフサイクル管理
• examples/server-side.md - サーバー側の評価、ローカル評価の設定、分散環境
• examples/development.md - ローカルオーバーライド、ブートストラップ、onFeatureFlags コールバック
• reference.md - 意思決定のフレームワークとアンチパターン

---

## フィロソフィー

フィーチャーフラグを使うと、デプロイとリリースを切り離せます。本番環境にコードをリリースしながら、誰にいつ表示するかを制御できます。これにより、次のことが可能になります。

1. 安全なリリース - まず1％に展開して監視し、その後対象を広げます
2. 迅速なロールバック - デプロイせずに、すぐにオフにできます
3. データに基づく意思決定 - A/Bテストで影響を測定します
4. 段階的なデリバリー - まずベータユーザーに提供し、その後全員に展開します

基本原則：

• フラグは一時的なものです。最初から削除を計画してください
• フラグには担当者を設定します。各フラグには責任者が必要です
• シンプルなフラグが優れています。複雑な条件よりも割合に応じた段階的な展開を選びます
• 未定義の状態に対応します。フラグは非同期で読み込まれます

フィーチャーフラグを使う場合：

• 段階的な展開が必要なリスクの高い機能
• 検証のためにA/Bテストが必要な機能
• すぐにロールバックする可能性がある機能
• ユーザーがオプトインするベータプログラム

フィーチャーフラグを使わない場合：

• すべての機能（保守の負担が増えるため）
• 恒久的な設定（設定ファイルを使用してください）
• 100％へのリリース準備が整っている機能

</フィロソフィー>

---

<パターン>

基本パターン

パターン 1：クライアント側のブール値フラグ

シンプルなオン／オフ機能には useFeatureFlagEnabled を使用します。読み込み中の undefined 状態には必ず対応してください。これを false として扱うと、一瞬だけ誤ったUIが表示されます。

const isNewCheckout = useFeatureFlagEnabled(FLAG_NEW_CHECKOUT);

if (isNewCheckout === undefined) return <Skeleton />;   // Loading
if (isNewCheckout) return <NewCheckout />;               // Enabled
return <LegacyCheckout />;                               // Disabled

入力ミスを防ぎ、grepによる削除を容易にするため、フラグキーは lib/feature-flags.ts に名前付き定数として保存します。

良い例と悪い例の全容については、examples/core.md を参照してください。

---

パターン 2：多変量フラグとバリアント

複数のバリアントを使ったA/Bテストには useFeatureFlagVariantKey を使用します。フラグキーと並べてバリアント定数を定義します。バリアントを切り替える際は、デフォルトのフォールバックとして control を指定します。

const variant = useFeatureFlagVariantKey(FLAG_PRICING_PAGE);
if (variant === undefined) return <Skeleton />;

switch (variant) {
  case VARIANT_SIMPLE: return <SimplePricing />;
  case VARIANT_DETAILED: return <DetailedPricing />;
  default: return <ControlPricing />;
}

例の全容については、examples/core.md を参照してください。

---

パターン 3：PostHogFeature コンポーネント

PostHogFeature コンポーネントを使うと、ボイラープレートを減らしながら、露出の自動トラッキングと組み込みのフォールバック処理を利用できます。ブール値フラグには match={true} を、特定のバリアントには match={VARIANT_KEY} を使用します。

<PostHogFeature flag={FLAG_BETA} match={true} fallback={<Legacy />}>
  <NewFeature />
</PostHogFeature>

ブール値とバリアントの例については、examples/core.md を参照してください。

---

パターン 4：リモート設定用のペイロード

動的なJSON設定には useFeatureFlagPayload を使用します。必ず useFeatureFlagEnabled と併用してください。ペイロードフック単独では露出イベントが送信されず、実験のトラッキングが機能しなくなります。

const isEnabled = useFeatureFlagEnabled(FLAG_BANNER); // Sends exposure event
const payload = useFeatureFlagPayload(FLAG_BANNER); // Gets config
const config = payload ?? DEFAULT_BANNER_CONFIG;

良い例と悪い例の全容については、examples/core.md を参照してください。

---

パターン 5：サーバー側でのフラグ評価

ローカルで評価する場合は、Feature Flags Secure API Key（phs_*）と posthog-node を使用します。これにより、レイテンシーを約500ms（ネットワーク呼び出し）から約10～50ms（ローカル）に短縮できます。personalApiKey 設定オプションには、名前は古いままですが、phs_* キーを指定します。

export const posthog = new PostHog(process.env.POSTHOG_API_KEY!, {
  host: process.env.POSTHOG_HOST || "https://us.i.posthog.com",
  personalApiKey: process.env.POSTHOG_FEATURE_FLAGS_KEY, // phs_* key
  featureFlagsPollingInterval: POSTHOG_POLL_INTERVAL_MS, // default 30s
});

APIハンドラーでの使用方法、ローカル評価のみの設定、分散環境やサーバーレス環境については、examples/server-side.md を参照してください。

---

パターン 6：フラグのライフサイクルと削除

すべてのフラグに担当者、作成日、削除予定日が必要です。フラグのチェックを単一のヘルパー関数にまとめると、削除を1つのファイルの変更だけで行えます。

/**
 * Owner: @john-doe | Created: 2025-01-15 | Remove by: 2025-02-15
 */
export const FLAG_NEW_CHECKOUT = "new-checkout-flow";

export function isNewCheckoutEnabled(flag: boolean | undefined): boolean {
  return flag === true; // When removing: change to `return true;`
}

ドキュメントのパターンと古いフラグの検出については、examples/core.md を参照してください。

</パターン>

---

<危険なパターン>

重大な警告

優先度の高い問題：

• 実験で useFeatureFlagPayload だけを使用する（露出のトラッキングが行われない）
• Feature Flags Secure API キー（phs_*）をクライアント側に公開する（セキュリティ違反）
• 読み込み状態を処理しない（UI がちらつく原因になります）
• オーナーや有効期限のないフラグを設定する（恒久的な負債になります）

優先度が中程度の問題：

• 定数の代わりにフラグキーとしてマジック文字列を使用する（タイプミスが起きやすく、検索もしにくくなります）
• トラフィックの多いフラグに複雑なターゲティングルールを設定する（パフォーマンスに影響します）
• 外部キャッシュなしでサーバーレス環境やエッジ環境にローカル評価を導入する（コールドスタートの問題が発生します）
• ローカルテストに PostHog toolbar を使用しない（デバッグが難しくなります）

よくある間違い：

• ラッパー関数を使わず、複数の場所でフラグを確認する
• SSR 用にフラグをブートストラップしない（水和時にコンテンツがちらつきます）
• 主要指標を定義せずに実験を実施する
• 実験の完了前に結果を確認する
• クリーンアップ計画なしで 100% にロールアウトする

注意点とエッジケース：

• PostHog は決定論的なハッシュを使用するため、同じユーザーには常に同じバリアントが割り当てられます
• ロールアウト率を下げると、以前に対象となっていたユーザーが対象から外れることがあります
• ローカル評価には Feature Flags Secure API Key（phs_*）が必要です。個人用 API キーは非推奨です
• フラグは非同期で読み込まれるため、初回のレンダリングでは常に undefined になります
• posthog-node v3+ では、GeoIP ターゲティングにデフォルトでサーバーの IP が使用されます
• 実験で結果を得るには、バリアントごとに最低 50 回の露出が必要です
• 古いフラグとは、ロールアウトが 100% で、30 日間評価されていないフラグです
• onFeatureFlags コールバックは 3 つのパラメーターを受け取ります。flags、flagVariants、{ errorsLoading }（3 番目のパラメーター）
• 外部キャッシュプロバイダー（Redis、KV）は実験段階で、Node.js/Python SDK のみで利用できます

</red_flags>

---

<critical_reminders>

重要な注意事項

すべてのコードは CLAUDE.md のプロジェクト規約（kebab-case、名前付きエクスポート、インポート順序、import type、名前付き定数）に従う必要があります

（実験では必ず useFeatureFlagPayload を useFeatureFlagEnabled または useFeatureFlagVariantKey と組み合わせてください。payload フックは露出イベントを送信しません）

（サーバー側のローカル評価には、必ず feature flags secure API key（phs_*）を使用してください。この用途では個人用 API キーは非推奨です）

（フラグの読み込み中は undefined の状態を必ず処理してください。フラグがすぐに利用できると思い込んではいけません）

（フラグのメタデータには、必ずフラグのオーナーと有効期限を含めてください。オーナーのいないフラグは、取り残された負債になります）

（複数の場所でフラグを使用する場合は、必ず単一の関数で使用箇所をラップしてください。これにより、クリーンアップ時にフラグのコードが取り残されるのを防げます）

これらのルールに従わないと、実験結果の誤り、セキュリティの脆弱性、UI のちらつき、技術的負債が発生します。

</critical_reminders>

---

参考資料

• PostHog React Integration
• PostHog Feature Flags
• PostHog Feature Flag Best Practices
• PostHog Server-Side Local Evaluation
• PostHog Creating Feature Flags
• PostHog How to Do a Phased Rollout
• PostHog Feature Flag Testing
• PostHog Experiments
• PostHog Feature Flag Overrides
• Don't Make These Feature Flag Mistakes