feature-flag-guide

機能フラグガイドスキル

サービスまたはチーム向けに、機能フラグ管理ガイドを完全な形で作成します。フラグの命名と分類方法、安全にフラグを作成してロールアウトする方法、ロールアウト中に監視する項目、フラグをいつどのようにクリーンアップするか、各段階の責任者を網羅します。規律なく運用された機能フラグは、恒久的な技術的負債になります。このガイドでは、フラグを意図的に作成し、安全にロールアウトし、役目を終えたら削除するための、チームで繰り返し使えるプロセスを示します。

必要な入力

まだ提供されていない場合は、次の情報を確認してください。

• サービスまたはチーム名 — ガイドの対象範囲
• 機能フラグプラットフォーム — LaunchDarkly、Split、Unleash、Flagsmith、Flipt、またはカスタム／社内ソリューション
• 文書化するフラグ（フラグ単位のガイドを作成する場合）、または「一般ガイド」（チーム全体のポリシーを作成する場合）
• ロールアウトの制約 — 機能を利用できる対象に関する、コンプライアンス、データプライバシー、契約上の制約（例：HIPAA、EU のみ、エンタープライズ顧客のみ）

出力形式

---

機能フラグ管理ガイド：[サービス／チーム名]

チーム： [チーム名] | プラットフォーム： [LaunchDarkly／Split／Unleash／カスタム] 文書オーナー： [名前] | 最終更新日： [日付] レビュー周期： 四半期ごと、およびフラグプラットフォームの変更時

---

1. フラグの分類

すべてのフラグは、必ずいずれか1つのカテゴリに属します。カテゴリによって、デフォルトの動作、本番環境で有効化できる人、クリーンアップが必要な時期が決まります。

種類	目的	デフォルト状態	本番環境での承認条件	最大有効期間
リリースフラグ	新機能のロールアウトを制御します。デプロイとリリースを切り離します	オフ	テックリードの承認	機能のリリースから90日
実験フラグ	A/Bテストまたは多変量テストを実施し、変更の影響を測定します	オフ（対照群）	プロダクト担当者とテックリード	実験期間＋30日
運用フラグ	サーキットブレーカー、キルスイッチ、スロットルなどの運用制御を行います	オン（通常の動作）	オンコール担当エンジニアが切り替え可能	無期限（年1回レビュー）
権限フラグ	ユーザーセグメント、プラン、地域ごとにアクセスを制限します	オフ（制限あり）	プロダクト担当者とアカウントオーナー	無期限（年1回レビュー）

迷った場合： 特定の機能リリースに紐づく一時的なフラグなら、リリースフラグです。制御用の設定値として永続的に存在するなら、運用フラグです。

---

2. フラグの命名規則

すべてのフラグで、次の命名規則に従う必要があります。

[type]-[service]-[feature-description]

要素	値	例
type	release、exp、ops、perm	release
service	短いサービス識別子。小文字で、単語をハイフンで連結	payments
feature-description	ケバブケースの説明。最大5語	new-checkout-flow

全体の例：

• release-payments-new-checkout-flow — paymentsサービスの新しいチェックアウト機能のリリースフラグ
• exp-search-personalized-ranking — パーソナライズされた検索ランキングの実験
• ops-api-rate-limit-override — APIレート制限を上書きする運用フラグ
• perm-dashboard-beta-users-only — ベータユーザーにダッシュボードへのアクセスを制限する権限フラグ

禁止事項：

• フラグ名にチケット番号を使わないでください（release-JIRA-1234 → 検索しにくく、名前だけでは内容がわかりません）
• フラグ名に日付を使わないでください（release-dark-mode-jan-2024 → フラグは日付を過ぎても残り続けます）
• 曖昧な名前を使わないでください（release-new-thing → フラグが50個ある場合に役立ちません）

---

3. フラグ作成チェックリスト

本番環境でフラグを作成する前に、すべての項目を完了してください。

フラグ作成前：

• フラグの種類を分類（セクション1）
• フラグ名が命名規則に準拠（セクション2）
• フラグオーナーを割り当て — クリーンアップを担当するエンジニアを1名指名
• フラグの説明欄にクリーンアップ日を設定（リリースフラグと実験フラグの場合）
• ロールアウト戦略を定義 — セクション4を参照
• 監視計画を定義 — セクション5を参照
• フラグガードを含むコードレビューの承認を得る

必須のフラグ説明欄：

Type: [Release / Experiment / Ops / Permission]
Owner: [Name]
Linked ticket: [JIRA-XXXX or GitHub issue URL]
Purpose: [One sentence — what this flag controls]
Cleanup by: [Date — required for Release and Experiment flags; "Annual review" for Ops/Permission]
Rollout plan: [Link to this document or inline summary]

コード要件：

# Good — behaviour is clear when flag is off, and cleanup is obvious
if flag_client.is_enabled("release-[service]-[feature]", user_context):
    return new_feature_handler(request)
else:
    return existing_handler(request)

# Bad — nested flags, ternaries, and implicit defaults make cleanup error-prone
result = new_handler() if (f1 and not f2) or f3 else old_handler()

---

4. ロールアウト戦略

デシジョンツリー

リリースフラグまたは実験フラグに適したロールアウト戦略を選ぶには、次のデシジョンツリーを使用してください。

Is the change reversible without a deploy?
├── No → Use an Ops flag with manual enable, not a percentage rollout
└── Yes → Continue

Is there a user-level identifier available (user ID, session ID)?
├── No → Use server-side percentage (stateless, but inconsistent per user)
└── Yes → Use user-based percentage (consistent experience per user) ← preferred

Is the change risky (touches payments, auth, or data writes)?
├── Yes → Start at 1% → 5% → 25% → 50% → 100%, with 24-hour holds
└── No → Start at 10% → 50% → 100%, with 4-hour holds

Does the change affect specific customer tiers or geographies?
├── Yes → Use segment-based targeting, not percentage rollout
└── No → Use percentage rollout

ロールアウトの段階

段階	割合	維持期間	次の段階に進むための合格基準
カナリア	1%	24時間	エラー率がSLOの範囲内で、P1インシデントがない
初期ロールアウト	5–10%	24時間	エラー率とレイテンシが対照群と同等
部分ロールアウト	25–50%	24–48時間	ビジネスメトリクスが対照群と比べて悪化していない
大半へのロールアウト	75%	24時間	最終確認 — リグレッションがない
全体へのロールアウト	100%	48時間	安定 — クリーンアップを予定する

本番環境のリリースフラグでは、段階を飛ばさないでください。 ロールアウトを速めても、本番インシデントが発生するリスクに見合いません。

セグメントベースのターゲティング

ロールアウトを制限する必要がある場合は、セグメントターゲティングを使用してください。

# LaunchDarkly segment example — adapt for your platform
targeting_rules:
  - clause:
      attribute: "subscription_tier"
      operator: "in"
      values: ["enterprise", "team"]
    serve: "on"
  - clause:
      attribute: "country"
      operator: "in"
      values: ["US", "CA", "GB"]
    serve: "on"
  default: "off"

---

5. モニタリング要件

ロールアウトが0%でも100%でもないすべてのフラグでは、積極的なモニタリングが必要です。フラグをロールアウトしたまま放置しないでください。

フラグごとに必要なメトリクス

メトリクス	比較対象	アラートのしきい値
エラー率	フラグ有効コホートとフラグ無効コホート	フラグ有効グループのエラー率がベースラインの2倍を超える
p99レイテンシ	フラグ有効とフラグ無効	フラグ有効グループのレイテンシが20%を超えて高い
[主要ビジネスメトリクス]	フラグ有効とフラグ無効	フラグ有効グループで5%を超える悪化
[コンバージョン率／完了率]	フラグ有効とフラグ無効	フラグ有効グループで2%を超える低下

[LaunchDarkly / Split / Datadog] で分割メトリクスのモニタリングを設定する：

1. Navigate to the flag → Metrics tab
2. Add metric: [primary business metric]
3. Add metric: error_rate (service-level)
4. Add metric: p99_latency (endpoint-level)
5. Set alert: notify [flag owner] in Slack #[team-channel] if metric degrades by [threshold]
6. Set experiment duration: [N days] if this is an Experiment flag

ガードレールメトリクス

主要メトリクスの結果にかかわらず、これらのメトリクスを悪化させてはいけません。ガードレールに抵触した場合は、調査を待たずに直ちにロールバックしてください。

• エラー率がSLOのしきい値（[X]%）を超える
• p99レイテンシがSLOのしきい値（[Y] ms）を超える
• [サービス固有のガードレール — 例：決済失敗率、認証失敗率]

ガードレールに抵触した場合の即時ロールバックコマンド：

# [LaunchDarkly CLI]
ld-cli flag update [project-key] [flag-key] --default-variation off

# [Split CLI]
split-cli update-treatment [flag-name] --treatment "off" --percentage 100

# [Unleash CLI / API]
curl -X POST https://[unleash-host]/api/admin/features/[flag-name]/disable \
  -H "Authorization: [admin-token]"

# [Custom — adapt to your implementation]
[command or dashboard step]

---

6. フラグごとの作成テンプレート

新しいフラグを作成する際は、このテンプレートをフラグの説明欄とリンクされたチケットにコピーしてください。

## Flag: [flag-name]

**Type:** [Release / Experiment / Ops / Permission]
**Owner:** [Name] ([Slack handle])
**Created:** [Date]
**Cleanup by:** [Date]
**Linked ticket:** [URL]

### Purpose
[One paragraph: what this flag controls, why it exists, what "on" and "off" mean]

### Rollout Plan
| Stage | Target | Date | Approved by |
|---|---|---|---|
| Canary | 1% | [Date] | [Name] |
| Early | 10% | [Date] | [Name] |
| Partial | 50% | [Date] | [Name] |
| Full | 100% | [Date] | [Name] |

### Monitoring
- Primary metric: [metric name and dashboard link]
- Guardrail metrics: error rate < [X]%, p99 < [Y] ms
- Alert channel: #[team-channel]

### Rollback Procedure
[Exact steps to turn the flag off in an emergency — should take < 2 minutes]

### Cleanup Checklist
- [ ] Flag at 100% for 48+ hours with no incidents
- [ ] Code path for flag-off branch removed from codebase
- [ ] Flag deleted from [platform]
- [ ] Ticket closed

---

7. 緊急キルスイッチ手順

本番インシデントによりフラグを直ちに無効にする必要がある場合：

目標時間：判断から2分以内にフラグを無効にします。

1. Go to [platform URL] — bookmark this: [URL]
2. Search for the flag by name: [flag-name]
3. Set to 0% / "off" for ALL users
4. Verify the service error rate drops within 60 seconds
5. Post to #incidents:
   "🟡 Feature flag [flag-name] disabled — rolling back [feature description].
    Owner: [name]. Error rate before: [X]%. Monitoring for recovery."
6. Page the flag owner if not already aware

Opsフラグ（通常はオンの動作をオフにする必要があるキルスイッチ）の場合：

# These flags are "on" by default and turned "off" to disable a feature
# Confirm the flag polarity before toggling — "off" may mean "disabled" or "enabled" depending on naming
# Flag [flag-name]: OFF = [feature behaviour when off]
[kill switch command for your platform]

---

8. 古いフラグのポリシーとクリーンアップ

古いフラグとは、ロールアウトが100%で、その状態が48時間を超えて続いているもの、またはクリーンアップ期限を過ぎているものです。古いフラグは技術的負債です。

古いフラグの定義

次のいずれかに該当する場合、そのフラグは古いフラグです。

• クリーンアップ期限を過ぎたリリースフラグである
• ロールアウトが100%（または0%）の状態で30日を超えている
• リンクされたチケットがクローズされているが、コードのクリーンアップが完了していない
• 担当者がチームを離れている

クリーンアップチェックリスト

[ ] Flag is at 100% rollout and has been stable for 48+ hours
[ ] Monitoring shows no issues for the flag-on cohort
[ ] Code changes:
    [ ] Remove the flag check from application code
    [ ] Remove the "off" code path entirely — do not leave dead code
    [ ] Remove any flag-related tests that test the off behaviour
    [ ] Update any documentation that references the flag
[ ] PR merged and deployed to production
[ ] Flag deleted from [platform] (do not just disable — delete)
[ ] Cleanup ticket closed
[ ] Flag owner confirms cleanup in Slack: "Flag [name] has been cleaned up — [commit link]"

古いフラグの自動検出：

# Run weekly — flags past cleanup date or at 100% for > 30 days
# [Platform-specific query — adapt:]

# LaunchDarkly API
curl -s "https://app.launchdarkly.com/api/v2/flags/[project-key]" \
  -H "Authorization: [api-key]" | \
  jq '.items[] | select(.creationDate < (now - 2592000) * 1000) | {key: .key, created: .creationDate}'

# Notify #engineering-housekeeping with list of stale flags

古いフラグのエスカレーション

クリーンアップ期限超過日数	対応
0–14日	フラグ担当者にSlackリマインダーを送信
14–30日	フラグ担当者とテックリードにSlackリマインダーを送信
30日超	テックリードがクリーンアップ担当者を割り当て、優先度P2のチケットを作成
60日超	エンジニアリングマネージャーが確認 — フラグを強制削除する場合がある

---

9. ガバナンス

操作権限

操作	実行者	必要な承認
フラグの作成（任意の環境）	任意のエンジニア	不要 — ただし作成チェックリストを完了すること
開発環境でフラグを有効化	任意のエンジニア	不要
ステージング環境でフラグを有効化	任意のエンジニア	不要
本番環境でフラグを有効化（0–10%）	フラグ担当者	テックリードへの共有
本番環境でロールアウトを進める（10–100%）	フラグ担当者	各段階でテックリードの承認
本番環境でOpsフラグを有効化	オンコールエンジニア	不要 — これらは緊急時の制御手段です
フラグの削除	フラグ担当者	コードのクリーンアップが完了したことをテックリードが確認
Permissionフラグの作成	フラグ担当者	プロダクトマネージャーの承認

監査ログ

本番環境でのすべてのフラグ変更は追跡可能でなければなりません。[platform] で以下が設定されていることを確認してください。

• 変更ログ: 本番環境のフラグ変更はすべて、誰が、何を、いつ変更したかを記録します。
• Slack 通知: 本番環境のフラグ変更は #[team]-flag-changes に自動的に投稿されます。
• 四半期レビュー: 四半期ごとに、テックリードがフラグの全一覧をレビューし、オーナーが最新であることを確認し、オーナーのいないフラグを削除します。

---

品質チェック

• すべてのフラグに、その説明内で指名されたオーナーがいる — オーナーのいないフラグがない
• リリースフラグと実験フラグにはクリーンアップ日が設定されている — 無期限ではない
• 現在 1～99% のロールアウト段階にあるすべてのフラグにモニタリングが設定されている
• 緊急キルスイッチ手順がテスト済みである — オンコールのエンジニアがプラットフォームの URL をブックマークし、手順を把握している
• 古いフラグの検出が自動で実行され、結果が毎週レビューされている
• コードレビューのチェックリストに以下が含まれている: 「この PR はフラグを導入しているか？ もしそうなら、作成チェックリストは完了しているか？」
• フラグのオーナー以外に少なくとも 1 人が、緊急時に任意のフラグを無効化する方法を知っている

アンチパターン

• クリーンアップ日のないリリースフラグを作成しない — 有効期限のないフラグは、コードベースが保守不能になるまで気付かれずに蓄積する恒久的な技術的負債になります
• 1～99% のロールアウト段階にあるフラグのモニタリング設定を省略しない — メトリクス比較のない部分的ロールアウト中のフラグは、センサーのないリスクです
• フラグを他のフラグの中に入れ子にしない — 複合的なフラグロジックはクリーンアップをほぼ不可能にし、テスト不能なコードパスを生み出します
• フラグのオーナーが所有権を再割り当てせずにチームを離れることを許さない — オーナーのいない孤立したフラグは決してクリーンアップされません
• フィーチャーフラグを恒久的な設定システムとして使用しない — 100% または 0% の状態が 30 日を超えて続いているフラグはクリーンアップする必要があります。フラグを恒久的な設定として使用すると、ビジネスロジックがフィーチャーフラグプラットフォームに結合します