feature-flags-architect

機能フラグの設計

機能フラグをエンドツーエンドで適切に管理するための手順です。分類し、リリースし、段階的に展開し、廃止します。多くのチームはフラグを使い捨ての if 文として扱いますが、このスキルでは、測定可能な負債を伴う管理されたライフサイクルとして扱います。

使用するタイミング

• 新しいフラグを追加し、ロールアウト計画が必要なとき
• 古くなったフラグや孤立したフラグがないか、コードベースを監査するとき
• フラグプロバイダーを選ぶとき（LaunchDarkly、GrowthBook、Statsig、Unleash、Flipt、自作）
• リスクの高いローンチに備えてキルスイッチの経路を設計するとき
• リリース凍結の前にフラグの負債を解消するとき
• そもそも機能をフラグの背後でリリースすべきかどうかを検討するとき

基本原則：フラグはライフサイクルであり、単なる if ではありません

request → design → ship → ramp → cleanup → archive

クリーンアップされないフラグは、使われなくなった分岐、古いデフォルト値、テストされていないコードパス、制限のない影響範囲といった負債になります。このスキルに含まれる3つのスクリプトで、ライフサイクルを徹底できます。

クイックスタート

# 1. Audit the repo for flag debt
python scripts/flag_debt_scanner.py --repo . --max-age-days 90

# 2. Plan a progressive rollout for a new flag
python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring

# 3. Verify every flag has a documented kill switch
python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md

4種類のフラグ（分類体系）

フラグの種類によって、ライフスパンと所有者が異なります。誤分類すると負債が生じます。

種類	目的	一般的なライフスパン	所有者	クリーンアップのトリガー
リリース	本番環境で未完成の機能を非表示にする	数日～数週間	Eng	ロールアウトが100%に到達
実験	A/Bテストでバリエーションを検証する	数週間	Product/Marketing	テスト終了、勝者の決定
運用	サーキットブレーカー、パフォーマンス切り替え、キルスイッチ	数か月～数年	Eng/SRE	オートスケーリングまたは機能の廃止により置き換え
権限	ユーザー／アカウント／プランごとの利用権限	数年（恒久的）	Product	プラン／ロールの廃止

負債スキャナーの監視対象にするのは、リリースフラグと実験フラグだけにしてください。運用フラグと権限フラグは、設計上、長期間維持されます。判断ツリーについては references/flag_taxonomy.md を参照してください。

3つのPythonツール

いずれも標準ライブラリのみを使用します。--help を指定して実行してください。

flag_debt_scanner.py

使用頻度の低い、--max-age-days より古いフラグを見つけ、クリーンアップ候補を提示します。

python scripts/flag_debt_scanner.py --repo . --max-age-days 90 --format text
python scripts/flag_debt_scanner.py --repo . --max-age-days 60 --format json > debt.json

検出ヒューリスティック：

1. --repo を走査し、一般的なフラグ呼び出しパターンに一致するコード参照を検索します。
   • flag("...")、isFlagEnabled("...")、featureFlag("...")、getFlag("...")
   • client.variation("...", ...)、unleash.isEnabled("...")、growthbook.feature("...")
2. フラグ識別子ごとに、それを導入した最古のコミットを検索します（git log --diff-filter=A -S <name>）。
3. 導入から --max-age-days 日を超えており、かつ使用箇所が --min-uses 以下の場合、そのフラグを負債として判定します。

フラグ名、経過日数、ファイル参照、推奨アクションを出力します。JSONモードはCIでの利用に適しています。

rollout_planner.py

対象ユーザー数、目標割合、期間、戦略に基づいて、段階的なロールアウトスケジュールを生成します。

python scripts/rollout_planner.py --population 100000 --target-percent 100 --duration-days 14 --strategy ring
python scripts/rollout_planner.py --population 50000 --target-percent 25 --duration-days 7 --strategy linear
python scripts/rollout_planner.py --population 1000000 --target-percent 100 --duration-days 30 --strategy log

戦略：

• ring：1% → 5% → 25% → 50% → 100% と均等な間隔で展開します。リスクの高いローンチのデフォルトです。
• linear：毎日一定の割合で展開します。中程度のリスクに対するデフォルトです。
• log：初期は急速に展開し、その後は緩やかに進めます。確信がある低リスクのローンチに対するデフォルトです。
• cohort：名前付きコホートごとに展開します（社内 → ベータ → 無料 → 有料 → 全員）。

各フェーズの日付、割合、予想ユーザー数、中止基準、検証手順を含むMarkdownテーブルを出力します。

kill_switch_audit.py

コードから検出したフラグとドキュメントを照合し、それぞれのキルスイッチの経路が文書化されているか確認します。

python scripts/kill_switch_audit.py --repo . --flag-doc docs/feature-flags.md
python scripts/kill_switch_audit.py --repo . --flag-doc runbooks/flags.md --format json

確認項目：

1. コードから検出したすべてのフラグに --flag-doc のエントリーがあること
2. 各エントリーに、所有者、種類、キルスイッチのトリガー、監視ダッシュボードが記載されていること
3. ドキュメントが不足しているフラグ（FAIL）または必須項目が不足しているフラグ（WARN）を報告すること

新しいフラグをリリースする前のマージ前ゲートとして使用してください。

プロバイダーの選び方（5つ＋DIY）

プロバイダー	最適な用途	料金モデル	ロックインのリスク	OSS オプション
LaunchDarkly	エンタープライズ、複雑なターゲティング、監査／コンプライアンス	MAU 単位、高額	高	なし
GrowthBook	ミッドマーケット、A/B テスト重視、OSS に親和的	MAU 単位＋OSS	低	あり（セルフホスト）
Statsig	グロース／プロダクトチーム、高度な実験	無料枠＋MAU 単位	中	なし
Unleash	OSS 優先、セルフホスト可能、開発者に優しい	OSS＋Enterprise	低	あり
Flipt	軽量、k8s ネイティブ、シンプルな要件	OSS のみ	なし	あり
DIY	フラグが100個未満、ターゲティングなし、完全な制御	なし	なし	該当なし

判断基準：

• フラグが50個未満でターゲティングが不要 → 設定ファイルまたは環境変数を使った DIY
• 分析＋実験が必要 → Statsig または GrowthBook
• コンプライアンス／SOC2 監査ログが必要 → LaunchDarkly
• セルフホストが必要（データレジデンシー／エアギャップ環境） → Unleash または Flipt
• 詳細は references/provider_comparison.md を参照してください。

ワークフロー

ワークフロー 1：新機能をフラグで制御してリリースする

1. Classify: which of the 4 flag types?
   → Release (most common for engineering work)
2. Run rollout_planner.py to design the ramp
3. Add flag entry to docs/feature-flags.md BEFORE writing code:
   - name, owner, type, kill-switch trigger, dashboard URL
4. Write the code with the flag
5. Run kill_switch_audit.py — must pass before merge
6. Deploy at 0%; verify kill switch works
7. Execute rollout schedule; abort if abort criteria met
8. At 100% for 7+ days: remove flag, delete dead branch, archive doc entry

ワークフロー 2：四半期ごとのフラグ整理

1. Run flag_debt_scanner.py --repo . --max-age-days 90 > debt.md
2. For each flagged item:
   a. Confirm it reached 100% (or was killed)
   b. Find the issue/PR that introduced it; verify owner agrees to remove
   c. Delete dead branches; remove flag config
   d. Run kill_switch_audit.py — should now show one fewer flag
3. Update CHANGELOG: "Removed N stale flags"

ワークフロー 3：プロバイダーを選ぶ

1. Estimate flag count (current + 12-month projection)
2. Required features:
   - Targeting rules (user, account, geo, %)?
   - A/B testing + stats?
   - Audit log / SOC2?
   - Self-hosting / data residency?
3. Pricing budget (MAU * cost-per-MAU)
4. See provider_comparison.md decision tree
5. Build a 30-day proof-of-concept before signing

ワークフロー 4：キルスイッチを設計する

1. Identify the failure modes:
   - Latency spike (which threshold?)
   - Error rate spike (which threshold?)
   - Business metric regression (which threshold?)
2. Wire each to an abort:
   - Manual: dashboard link + on-call playbook
   - Automated: alert threshold flips flag back to 0%
3. Test the kill switch in staging BEFORE production rollout
4. Document in flag-doc; pass kill_switch_audit.py

参考資料

• references/flag_taxonomy.md — 4つの種類、判断ツリー、所有者、存続期間
• references/provider_comparison.md — LaunchDarkly／GrowthBook／Statsig／Unleash／Flipt／DIY の比較
• references/rollout_strategies.md — リング／段階的／ログ／コホート／地域、停止基準、モニタリング
• references/flag_lifecycle.md — 申請 → 設計 → リリース → 拡大 → 整理 → アーカイブ

スラッシュコマンド

/flag-cleanup — 現在のリポジトリで整理ワークフロー全体を実行します。負債をスキャンし、削除計画を作成し、キルスイッチを監査します。

アセットテンプレート

• assets/flag_request_template.md — 新しいフラグの申請フォーム（名前、所有者、種類、キルスイッチ、ロールアウト計画）

アンチパターン

• 50か所で if (FLAG_FOO) を使う恒久的なフラグ — リリースフラグではなく、実行時設定を使うパーミッションフラグにするべきです
• 所有者のいないフラグ — 元のエンジニアが退職すると、誰も整理しなくなります
• キルスイッチの記載がない — 機能に問題が起きても、無効にする方法が誰にもわかりません
• 6か月間実施した A/B テスト — 勝者を選びましょう。無期限の実施は負債になります
• 見た目の変更に対する機能トグルとしてのフラグ — フラグではなく、デプロイでリリースしましょう

検証可能な成功基準

このスキルを使うチームは、次の目標を達成する必要があります：

• 新しいフラグの100％がマージ時に kill_switch_audit.py を通過する
• flag_debt_scanner.py --max-age-days 90 のリポジトリ全体での古いフラグの検出数が5個以下である
• すべてのフラグに、文書化された所有者、種類、キルスイッチがある
• リリースフラグの廃止までの平均期間：ロールアウト率100％から60日未満