copying-flags-across-projects

プロジェクト間でフィーチャーフラグをコピーする

このスキルでは、同じ PostHog 組織内のソースプロジェクトから 1 つ以上のターゲットプロジェクトへ、フィーチャーフラグを複製する方法を説明します。

このスキルを使用する場面

• ユーザーが「別のプロジェクトにフラグをコピーして」「このフラグを複製して」「プロジェクト間でフラグを同期して」と依頼した場合
• ステージングプロジェクトから本番プロジェクトへ、またはその逆へフラグを昇格させたい場合
• 別のワークスペースにフラグ設定を複製し、コホートの依存関係を維持したい場合
• プロジェクトを環境として使用し、真の環境が存在しない状況に対応している場合

このスキルの対象外

• 組織をまたいだコピーはサポートされていません。このエンドポイントでは、ソースとターゲットのプロジェクトが同じ組織に属している必要があります。
• プロジェクト内のすべてのフラグの一括コピーには対応していません。このツールは一度に 1 つのフラグをコピーします。一括コピーする場合は、フラグキーごとにループして呼び出してください。各呼び出しは独立しています。
• 古いフラグや使用されていないフラグの整理には対応していません。代わりに cleaning-up-stale-feature-flags スキルを参照してください。

ワークフロー

1. ソースフラグを特定する

フラグのキーとソースプロジェクトの IDが必要です。

• ユーザーからフラグキーとプロジェクト ID の両方が提示された場合は、そのまま使用します。
• ユーザーからフラグ名（例：「新しい料金プランのフラグ」）が提示された場合は、ソースプロジェクトで posthog:feature-flag-get-all を呼び出し、一致するフラグを見つけて、その key を確認します。
• ユーザーからフラグだけが提示され、プロジェクトが指定されていない場合は、どのプロジェクトにあるか確認してください。現在の MCP プロジェクトだと決めつけないでください。誤ったソースからコピーしてしまうのは、よくある失敗です。

2. ターゲットプロジェクトの ID を特定する

ターゲットはソースと同じ組織に属している必要があります。コピーを実行する前に posthog:projects-get を呼び出して、利用可能なプロジェクトを一覧表示し、所属を確認してください。

複数のターゲットへコピーする場合、1 回の呼び出しで最大 50 件のターゲットプロジェクト ID を指定できます。成功と失敗はターゲットごとに報告されるため、一部で失敗しても、残りはブロックされません。

3. ソースフラグとその依存関係をプレビューする

ソースフラグに対して posthog:feature-flag-get-definition を呼び出します。次に、依存関係を先に検出しようとせず、必ず feature_flag_key、from_project、target_project_ids を指定して posthog:feature-flags-copy-dependencies-check を呼び出してください。この呼び出しでは何もコピーされず、フラグに依存関係がない場合は警告なしの空の結果が返されます。そのため、コピーのたびに実行しても負荷は低く、実際の依存関係を見落とすこともありません。

can_copy_dependencies が false でも、必ずしもコピーがブロックされているとは限りません。コピーするものがない場合も false になります。問題として報告するのは、warnings が空でない場合だけです。

コピーする前に、ユーザーに簡潔な概要を提示します。

• ソースのフラグキー、名前、有効状態
• フィルターグループ（ロールアウト率、プロパティフィルター、バリアントの分割）
• filters.groups[].properties[] 内のコホート参照。これらはサーバー側で対応付けられますが、ターゲットプロジェクトに一致するコホートがすでに存在するかどうかをユーザーに伝えてください。
• フラグに暗号化されたペイロード（has_encrypted_payloads）があるか、またはリモート設定（is_remote_configuration）であるか
• スケジュールされた変更があるかどうか（ユーザーは手順 4 でそれらをコピーするか選択できます）
• 依存関係チェックの copied_dependency_keys（コピーするとターゲットに作成される依存関係）、reused_dependency_keys（ターゲットですでに満たされている依存関係）、および warnings

4. コピーオプションを確認する

確認は3つのオプションすべてを対象とします。最も安全な組み合わせをデフォルトとし、異なる動作をユーザーが明示的に希望した場合にのみ変更を確認してください。

• disable_copied_flag: true — コピー先では、コピーされたフラグは無効な状態になります。デフォルトで推奨します。新しいプロジェクトでフラグを有効にするのは、意図をもって状況を確認したうえで行うべきです。
• copy_schedule: false — スケジュールされた変更はコピーされません。デフォルトで推奨します。スケジュールは通常、プロジェクト固有のものです。
• copy_dependencies: false — 依存関係にあるフラグはコピーされません。手順3の確認で報告されたキーのコピーをユーザーが承認した場合にのみ、true に設定してください。

ユーザーが「そのまま本番に反映して」または「本番で有効にして」と言った場合は、disable_copied_flag を false に切り替えてください。「ロールアウトのスケジュールを含めて」または「スケジュールされたロールアウトも一緒に」と言った場合は、copy_schedule を true に切り替えてください。

5. コピーを実行する

以下を指定して posthog:feature-flags-copy-flags-create を呼び出します。

• feature_flag_key：コピー元のフラグのキー
• from_project：コピー元プロジェクトの ID
• target_project_ids：解決済みのコピー先プロジェクト ID のリスト
• disable_copied_flag：手順4の値（デフォルトは true）
• copy_schedule：手順4の値（デフォルトは false）
• copy_dependencies：手順4の値（デフォルトは false）。省略すると、ユーザーが承認していても依存関係のコピーは通知なくスキップされます。

6. コピー先ごとの結果を報告する

レスポンスには success 配列（コピーされたフラグごとに1件）と failed 配列（コピー先ごとのエラー）が含まれます。両方をユーザーに伝えてください。

• 成功ごとに、コピー先プロジェクトの ID、新しいフラグの ID、およびコピー先での active 状態を伝えてください。
• 失敗ごとに、コピー先プロジェクトの ID とエラーメッセージを伝えてください。よくある原因は、コピー先のチームで編集権限がないこと、またはコピー先に上書きできないリソースとして同じフラグがすでに存在することです。

コピーに失敗したコピー先がある場合は、失敗したものを再試行するか、スキップするか、根本原因（例：アクセス権を付与してから再試行）を解消するか、ユーザーに確認してください。

重要な注意事項

• コホートは自動的に再マッピングされます。 コピー元のフラグがコホートを参照している場合、エンドポイントは各コピー先プロジェクトに同等のコホートを作成または再利用し、フラグのフィルターがコピー先プロジェクトのコホート ID を参照するように書き換えます。対応は不要ですが、コピー先に新しいコホートが作成される場合があることをユーザーに伝えてください。
• 暗号化されたペイロードは保持されます。 暗号化されたペイロードを持つリモート設定フラグをコピーしても、暗号化は維持されます。ペイロードはコピー先プロジェクトのキーで再暗号化されます。
• スケジュールされた変更でもコホートは再マッピングされます。 copy_schedule: true の場合、スケジュールされたコホート参照は、適用中のフィルター条件と同様に再マッピングされます。
• 認証要件。 ユーザーの API キーには、明示的な feature_flag:write（または feature_flag:*）スコープが必要です。* のみのキーは拒否されます。このエンドポイントは INTERNAL ビューセットによって制限されており、* への同意では要件を満たしません。チームスコープのキーでもこのエンドポイントにはアクセスできません。組織スコープのキー、またはスコープなしのキーが必要です。
• コピー元での編集アクセス。 ユーザーはコピー元フラグのチームで、少なくとも編集者レベルのアクセス権を持っている必要があります。コピーの前に、エンドポイントは PostHog のアクセス制御を通じてこれを適用します。
• コピー先ごとのアクセス権。 ユーザーが表示できないコピー先は、結果から通知なく除外されます。表示できても編集権限がないコピー先は、権限エラーとともに failed 配列に含まれます。
• 取り消しはできません。 コピーすると、コピー先に新しいフラグが作成されます（同じキーのフラグがすでに存在する場合は上書きされます）。特にコピー先が本番プロジェクトの場合は、コピーを実行する前に必ずユーザーに確認してください。

操作例

ユーザー： プロジェクト 12345 の new-checkout フラグをプロジェクト 67890 にコピーしてください。

エージェント： プロジェクト 12345 のコピー元フラグを確認しています。

(calls posthog:feature-flag-get-definition)

new-checkout フラグは現在、プロジェクト 12345 で 25% のロールアウトが設定されたブール値です。コホートフィルターや予定されている変更はありません。より安全なデフォルトとして、プロジェクト 67890 では無効にし、予定されている変更もない状態でコピーします。よろしいですか？

ユーザー： はい。ただし、コピー先では有効にしてください。

エージェント： 承知しました。コピー先では有効にします。

(calls posthog:feature-flags-copy-flags-create with disable_copied_flag: false, copy_schedule: false)

完了しました。プロジェクト 67890 にフラグ ID 99887 を作成しました（active: true）。失敗したコピー先はありません。

利用可能なツール

• posthog:feature-flags-copy-flags-create — コピーを実行します。必須フィールド：feature_flag_key、from_project、target_project_ids。任意フィールド：disable_copied_flag、copy_schedule、copy_dependencies。
• posthog:feature-flags-copy-dependencies-check — コピーによってフラグの推移的なフラグ依存関係に生じる影響をプレビューします。コピーは実行しません。コピーの前に必ず呼び出してください。フラグに依存関係がない場合は、空の結果を返します。
• posthog:feature-flag-get-all — ユーザーがわかりやすい名前だけを指定した場合に、指定したプロジェクト内でキーまたは名前からフラグを検索します。
• posthog:feature-flag-get-definition — コピー前にプレビューできるよう、コピー元のフラグ全体（フィルター、バリアント、コホート参照、暗号化フラグ）を取得します。
• posthog:projects-get — アクティブな組織内のプロジェクト一覧を取得します。コピー先のプロジェクト ID の解決と検証に使用します。