launchdarkly-flag-drift

LaunchDarkly フラグドリフト検出

あなたは、フィーチャーフラグのコード内 SDK フォールバック既定値がLaunchDarkly の既定ルール (フォールスルー) からドリフトしていないかを確認し、ドリフトしている場合はコードを整合させるためのスキルを使用しています。あなたの役割は、LaunchDarkly からフラグの現在の既定ルール値を特定し、コード内のすべての SDK 評価に渡されている既定引数を突き止め、それらを比較し、両者が異なる場合にのみ、コード内の既定値を一致するように更新することです。フラグを削除したり、評価ロジックを変更したりすることは決してありません。

前提条件

このスキルを使用するには、リモートでホストされている LaunchDarkly MCP サーバーが環境内で設定されている必要があります。

必須の MCP ツール:

• get-flag: 特定の環境におけるフラグの設定 (フォールスルー、バリエーション、offVariation) を取得します。フォールスルーは環境固有であるため、重要な環境ごとに 1 回ずつ呼び出してください。

任意の MCP ツール:

• list-flags: ユーザーがフラグを名前だけで説明した場合に、フラグキーを見つけます
• get-environments: プロジェクトの環境を列挙し、どれが重要かを判断します
• get-flag-status-across-envs: 環境をまたいだフラグの状態の簡単なスナップショット (各 get-flag を取得する前に、環境間の差異をすばやく見つける方法)

中核となる概念: SDK フォールバック既定値はオフバリエーションではない

すべての SDK 評価呼び出しはフォールバック既定値を受け取ります。これは、LaunchDarkly に到達できない場合、クライアントが初期化されていない場合、またはフラグが利用できない場合に返される値です。これはコード側の安全値であり、フラグの offVariation (フラグがオフに切り替えられたときに配信される値) や fallthrough (どのターゲティングルールにも一致しないときに配信される既定ルール) とは異なります。

このスキルは、1 つの特定の不変条件を「正しい」ものとして扱います: コード内フォールバック既定値は、現在の既定ルール (フォールスルー) の値と一致すべきである。両者が乖離している場合、それがドリフトです。これを整合させることで、障害時に返される値が、そうでなければ大多数のユーザーが受け取る値と一貫したものになります。

中核となる概念: 1 つのコード内既定値、多数の環境

コード内フォールバック既定値は、デプロイされたコードにコンパイルされる単一の値です。一方、フラグのフォールスルーは環境ごとに設定され、環境間で異なる場合があります (たとえば、production、eu-production、federal がそれぞれ異なる既定ルールを配信する可能性があります)。したがって、フォールスルーは、コードが実行される重要な環境すべてで解決する必要があり、1 つだけでよいわけではありません。

• 重要な環境がフォールスルーについて一致している場合、その共有値が期待される既定値です。通常どおり整合させます。
• 重要な環境が一致していない場合 (たとえば、EU は true を配信するが Federal は false を配信する)、単一のコード内既定値ではそれらすべてに一致することはできません。この乖離自体が 1 つの発見事項です: それを明示し、1 つに黙って整合させるのではなく、このビルドにとってどの環境が権威的かを確認してください。エッジケースを参照してください。

重要な環境を 1 つだけ確認することは、このスキルが誤った、または誤解を招く結果を生み出す最も一般的な原因であるため、常に重要な環境の完全なセットを最初に確定してください。

チームによっては、意図的にフォールバックを保守的/オフの値のままにしておく場合もあります。不一致は常に自動編集と見なすのではなく、明示すべき発見事項として扱ってください。エッジケースを参照してください。

ワークフロー

ステップ 1: フラグと重要な環境を特定する

1. フラグキーを取得します。 ユーザーがフラグを名前で説明した場合は、list-flags を使用してキーを解決します。続行する前に確認してください。
2. 重要な環境を確定します。 フォールスルーは環境ごとに異なり、同じコード内デフォルトが、デプロイされたコードが提供するすべての環境を代表しなければなりません。比較する前に、その完全なセットを特定してください:
   • 1 つのビルドが複数の本番グレードの環境（例: production、eu-production、federal）に提供される場合、それらすべてが重要です。
   • ビルドが単一の環境にスコープされている場合（リージョン固有またはテナント固有のデプロイ、例: Federal 専用ビルド）、その単一の環境だけが重要です。
   • リポジトリ内のシグナル（デプロイ設定、CI 内の環境名、SDK キーの配線）を探し、ユーザーに確認してください。セットが不明確な場合は、get-environments を使用して存在するものを列挙します。単一の production を前提としないでください。

ステップ 2: LaunchDarkly から期待されるデフォルトを特定する

重要な環境ごとに 1 回 get-flag を呼び出します。各環境について、以下を読み取ります:

• fallthrough: デフォルトルール。単一の variation（インデックス）を指している場合、それが解決された値です。パーセンテージの rollout である場合、単一のデフォルト値は存在しないため、停止してエッジケースとして処理します。
• variations: fallthrough.variation（インデックス）を variations[index].value にマッピングします。この解決された値が、その環境の期待されるデフォルトです。
• offVariation とフラグタイプ: 比較のための有用なコンテキスト、および型の不一致を発見するために役立ちます。

次に、環境間で突き合わせます:

重要な環境間で	期待されるデフォルト
すべてが同じ値に解決される	その共有値が期待されるデフォルトです。ステップ 3 に進みます。
異なる値に解決される	環境間の不一致。 1 つのコード内デフォルトではそれらすべてを満たせません。自動で選択しないでください。 環境ごとの値を報告し、このビルドにとってどの環境が権威があるか（または不一致を先に LaunchDarkly で解決すべきか）を確認してください。エッジケースを参照してください。

（get-flag-status-across-envs は、環境が異なるかどうかについて迅速な事前情報を提供できますが、編集前に必ず get-flag で実際のフォールスルー値を解決してください。）

フォールスルー値を推測しないでください。常に get-flag から解決してください。

ステップ 3: すべてのコード内デフォルトを見つける

コード内でフラグが評価されるすべての場所、そして特に重要なのは SDK 呼び出しに渡されるデフォルト/フォールバック引数を見つけます。コードベース全体でフラグキーを検索し、各ヒットでデフォルトを特定します。

• デフォルトは通常、variation(...) / *Variation(...) 呼び出しへの最後の位置引数です（例: boolVariation("<key>", context, <default>)）。
• チームはしばしば SDK をラップします。フラグごとにデフォルトを 1 回宣言するラッパー/レジストリ/設定レイヤー、アノテーションまたは構造体タグベースのデフォルト、および生成されたデフォルトファイルを確認してください。

言語と抽象化ごとのパターンの完全なセット、およびデフォルト引数とコンテキスト引数を区別する方法については、SDK デフォルトパターンを参照してください。

ステップ 4: 比較して判断する

比較する前に双方を正規化します（JSON/数値/型に関する注意点は「エッジケース」を参照）。その後、次のように判断します。

結果	アクション
重要な環境間でフォールスルーについて一致しない	停止 — 単一の期待デフォルトは存在しません。 環境ごとの値を報告し、編集前にこのビルドにとってどの環境が権威的かを確認してください（または先に LaunchDarkly 側で相違を解消してください）。1 つの環境に自動的にすり合わせないでください。
コード内デフォルトが（すべての重要な環境で）期待デフォルトと一致する	ドリフトなし。 drift_detected: false を報告して停止します。PR は開かないでください。
コード内デフォルトが異なる	ドリフトを検出。 ステップ 5 に進んですり合わせます。
複数の評価でコード内デフォルトが異なる	ドリフト。それらすべてを期待値にすり合わせ、以前の不整合を記録します。

ステップ 5: コード内デフォルトをすり合わせる

期待値に一致するように、デフォルト/フォールバック引数のみを更新します。

• 評価ロジック、分岐、またはオフパスの動作を変更しないでください。
• フラグまたはその評価を削除しないでください。
• デフォルトが生成されたファイルにある場合は、手で編集しないでください。信頼できる情報源（コンストラクター/レジストリ/アノテーション）を更新し、プロジェクトのコード生成コマンドで再生成してください。サマリーに requires_generation: true を記録してください。

例（変更前と変更後）、期待デフォルト = true:

// Before: outage returns false even though the default rule now serves true
const enabled = await ldClient.variation('new-checkout-flow', context, false);

// After: fallback default reconciled to match the fallthrough
const enabled = await ldClient.variation('new-checkout-flow', context, true);

周囲の if (enabled) { ... } else { ... } 分岐はそのままにします。

ステップ 6: コミット前に検証する

プロジェクトに設定されたチェックを、変更したファイルにスコープして実行します。package.json のスクリプト、Makefile、AGENTS.md/CLAUDE.md/CONTRIBUTING.md、または CI 設定から見つけます。通常は、フォーマット、リント、型チェック、ビルド、および関連するテストです。

強制停止: いずれかのチェックが失敗し、修正できない場合は、コミットやプッシュを行わないでください。代わりに変更範囲を狭めてください。フォーマット/リント/型チェック/ビルド/テストに失敗するコードを決して出荷しないでください。

ステップ 7: プルリクエストを開く

検証が通過した後にのみ行います。references/pr-template.md を使用してください。説明には、フラグキー、チェックした重要な環境とその解決済みフォールスルー値、コード内デフォルトの変更前と変更後、そして SDK のフォールバックデフォルトのみ が変更されたこと（フラグとその評価は保持されていること）を記載する必要があります。

• リポジトリのコントリビューション規約（ブランチ命名、コミットスタイル）に従ってください。まず AGENTS.md/CLAUDE.md/CONTRIBUTING.md を確認してください。
• 明確なデフォルト: ブランチ fix/flag-default-drift-<flag-key>、コミット fix: sync in-code default for <flag-key> to match fallthrough。

ステップ 8: 構造化されたサマリーを報告する

次のフィールドを含む簡潔なサマリーを作成します。

flag_key:              <key>
environments_checked:  [<env>: <resolved fallthrough value>, ...]
environments_diverge:  true | false
drift_detected:        true | false
old_default:           <in-code value before, or n/a>
new_default:           <expected value / value written, or n/a>
files_modified:        [<paths>]
pr_url:                <url or null>
requires_generation:   true | false
notes:                 <anything the reviewer should know, incl. any cross-environment divergence>

エッジケース

状況	対応
フォールスルーがパーセンテージロールアウトである	単一のデフォルト値は存在しません。分割を報告し、自動編集は行わず、フォールバックがどの値を表すべきかをユーザーに尋ねてください。
フォールバックが意図的に保守的に見える（offVariation や安全な値と一致する）	不一致を提示し、変更する前に意図を確認してください。チームによっては、フォールバックを意図的に安全な値のままにしている場合があります。
コード内のデフォルトが生成されたファイルにある	信頼できる唯一のソースを編集して再生成してください。生成された出力を手で編集してはいけません。requires_generation: true を設定してください。
コードのデフォルトとバリエーションの型の間に型の不一致がある	PR／サマリーでバグとして報告してください。デフォルトとバリエーションの型は一致しているべきです。
JSON／オブジェクト／浮動小数点数のデフォルト	文字列表現ではなく正規化した値で比較してください（{"a":1} == { "a": 1 }、0 == 0.0）。
フラグが見つからない、または環境が間違っている	ユーザーに通知してください。キーのタイプミスを確認し、環境を確認してください。
動的なフラグキー（flag-${id}）	自動検出が不完全な可能性があります。手動レビューの対象として報告してください。
重要な環境間でフォールスルーが一致しない（例: eu-production は true を配信し、federal は false を配信する）	単一のコード内デフォルトではすべてに一致させることはできません。ビルドが1つの環境にスコープされている場合は、その環境の値に合わせて調整し、他の環境について注記してください。ビルドが複数の異なる環境に配信される場合は、1つを黙って選ばないでください。環境ごとのすべての値を提示し、どの環境が権威を持つかを確認するか、まず LaunchDarkly 側で不一致を解消することを推奨してください。
ビルドが単一の環境（リージョン固有またはテナント固有のデプロイメント）を対象としている	その環境を唯一の重要な環境として扱ってください。他の環境のフォールスルーは、このビルドのデフォルトには関係しません。
フラグが複数のリポジトリにまたがっている	このスキルは現在のリポジトリで動作します。同じキーを参照している他のリポジトリを注記し、個別に調整できるようにしてください。

やってはいけないこと

• フラグやその評価を削除しないでください。このスキルはデフォルト引数にのみ触れます。
• フォールバックのデフォルト以外の評価ロジック、分岐、オフパスの動作を変更しないでください。
• 1つの環境だけを確認しないでください。ビルドが配信するすべての重要な環境でフォールスルーを解決してください。
• 重要な環境間で不一致がある場合に、1つの環境のフォールスルーに合わせて調整しないでください。単一のデフォルトでは異なる環境を満たすことはできないため、まず不一致を提示し、権威を持つ環境を確認してください。
• 生成されたファイルを手で編集しないでください。信頼できる唯一のソースから再生成してください。
• ドリフトが存在しない場合は PR を開かないでください。
• フォールスルーの値を推測しないでください。get-flag から解決してください。
• フォーマット、リント、型チェック、ビルド、テストに失敗するコードを出荷しないでください。

参考資料

• SDK デフォルトパターン: 言語、ラッパー、アノテーション、生成ファイルのパターンごとにフォールバックのデフォルトがどこに存在するか、およびその見つけ方
• PR テンプレート: ドリフト調整のための構造化された PR 説明
• フラグのクリーンアップ: デフォルトを調整するのではなく、フラグを完全に削除することが目的の場合
• フラグのターゲティング: コードではなく LaunchDarkly のデフォルトルールを変更することが目的の場合