managing-experiment-lifecycle

実験ライフサイクルの管理

このスキルでは、実験の状態遷移について説明します。各アクションの内容、使用するタイミング、バリアントの割り当てと分析への影響を取り上げます。

状態図

draft ──launch──▶ running ──end──▶ stopped ──archive──▶ archived
                  │ │   ▲              │
                  │ pause resume  ship_variant
                  │ │   │         (also ends if running)
                  │ ▼   │
                  │ paused (flag inactive, still "running" status)
                  │
                  ├─freeze_exposure──▶ exposure_frozen ──unfreeze_exposure──▶ running
                  │                    (enrollment closed, metrics keep flowing)

Any non-draft state ──reset──▶ draft

アクションとその影響

各アクションについて、重要な質問は次の2つです。

1. どのユーザーにどのバリアントが表示されますか？（ユーザーの視点）
2. 分析の対象に含まれるのは誰ですか？（統計の視点）

起動（experiment-launch）

draft → running に遷移します。フィーチャーフラグを有効化し、start_date を設定します。

• 前提条件：状態が draft であること。フラグに2〜20個の多変量バリアントが必要です（特定のキーは不要です。ベースラインは「control」があればそれに、なければ最初のバリアントがデフォルトになります）。
• 起動前のチェックリスト：メトリクスが少なくとも1つあるか？ バリアントは正しいか？ フラグはコードに実装されているか？
• バリアント：設定済みの分割に基づき、ユーザーが各バリアントに割り当てられ始めます。
• 分析：start_date からデータ収集が始まります。

リクエストボディは不要です。

変更がユーザー向けで大きなものである場合に限り、起動時に一度だけ検討する項目があります。実験対象のフローをユーザーが完了したとき（例：フォームの送信イベントをトリガーとして）に表示する短いアンケートを用意すると、初日からメトリクスと合わせて定性的なフィードバック（評価と任意のコメント）を収集できます。セットアップ時のアドバイスとして一度だけ提案し、断られたら取り下げ、起動を遅らせることは決して避けてください。実験の終了時やバリアントの適用時には提案しないでください。そのタイミングでは、ロールアウトの条件のように受け取られてしまいます。→ [[diagnosing-experiment-health]] の references/qualitative-feedback.md を参照してください。

一時停止（experiment-pause）

フィーチャーフラグを無効化します。ユーザーにはデフォルトのエクスペリエンス（通常は control）が表示されます。

• 前提条件：running であり、すでに一時停止中ではないこと。
• バリアント：/decide からフラグが返されなくなり、新しい露出イベントは記録されません。
• 分析：一時停止中は新しいデータが追加されませんが、既存のデータは保持されます。実験の状態は「running」のままです。

リクエストボディは不要です。再有効化するには experiment-resume を使用します。

再開（experiment-resume）

一時停止後にフィーチャーフラグを再有効化します。ユーザーは決定論的に同じバリアントへ再割り当てされます。

• 前提条件：一時停止中であること。
• バリアント：一時停止前と同じ割り当てになります。バケット分けは決定論的です。
• 分析：露出のトラッキングが再開されます。

リクエストボディは不要です。

曝露の凍結（experiment-freeze-exposure）

ほかのすべてを継続したまま、新規ユーザーの登録を停止します。すでに登録済みのユーザーは引き続き自分のバリアントを維持し、メトリクスの流入も続き、end_date は null のままです。 すでに曝露されたユーザーを静的コホートにスナップショットし、フィーチャーフラグのすべてのリリース条件をそのコホートに限定します。 ステータスは exposure_frozen になります。

サンプル数が十分で、測定を止めずにユーザーの追加を停止したい場合に、長期的なメトリクス（収益、LTV、リテンション、更新）で使用します。この用途には終了も一時停止も適しません。終了すると end_date で測定が止まり、一時停止するとフラグがすべてのユーザーに対して無効になります。

• 前提条件：実行中であること（ドラフト、停止、一時停止、または凍結済みではないこと）、フラグが関連付けられていて削除されていないこと、リリース条件が少なくとも1つあること
• バリアント：登録済みユーザーは自分のバリアントを維持します（決定論的なバケット分け）。新規ユーザーはフラグの条件に一致しなくなります
• 分析：曝露数の増加は止まります（曝露曲線が横ばいになることが想定されます）が、登録済みユーザーのメトリクスデータは蓄積され続けます

タイミング：曝露のスキャンとコホートのスナップショットは API 呼び出し内で同期的に実行され、所要時間は曝露されたユーザー数に応じて長くなります。曝露されたユーザーが数万人いる実験では、数十秒程度かかることがあります。 ユーザーに事前に所要時間の目安を伝え、応答を待ってください。呼び出しに時間がかかっても失敗と見なしたり、再試行したりしないでください。

適用対象外（400）：

• グループ単位で集計される実験 — フラグはユーザーではなくグループを対象としているため、ユーザーコホートではグループ単位のマッチングを凍結できません
• ホールドアウト内の実験 — ホールドアウトの割り当てはリリース条件より前に評価されるため、新規ユーザーが引き続きホールドアウトに登録されます
• 早期アクセス条件があるフラグ — こちらもリリース条件より前に評価されるため、凍結しても新規登録を停止できません
• 匿名ユーザーの曝露が大半を占める場合（例：ログアウト状態の画面での実験） — 匿名の「ユーザー情報を持たない」ユーザーはユーザーコホートに一致できず、割り当てられたバリアントが気付かないうちに失われます。そのため、未解決の割合が小さくない場合は凍結が拒否されます
• 曝露されたユーザー数が非常に多い場合 — 曝露スキャンにはユーザー数の上限とタイムアウトが設定されています。いずれかの上限を超えると、凍結は実行されず、API はエラー内容が明確な 400 を返します

凍結が拒否された場合は、再試行するのではなく、どの制限が該当するかを説明してください。これらは一時的なものではなく、構造上の制限です。

ほかの操作との相互作用：ship-variant と reset は凍結を解除します（どちらもスナップショットコホートを削除します）。end はフラグに影響しないため、凍結済みの実験を終了すると、フラグはスナップショットコホートに限定されたままになります。 ローカル評価を使用する SDK では静的コホートを解決できないため、凍結されたフラグは /decide エンドポイントを介して評価されます（静的コホートの標準的な動作）。 凍結直前に取り込まれた曝露は、スナップショットに含まれない場合があります（取り込みの遅延）。

リクエストボディはありません。登録を再開するには experiment-unfreeze-exposure を使用します。

曝露の凍結解除（experiment-unfreeze-exposure）

曝露が凍結された実験で、登録を再開します。 スナップショットコホートの条件と凍結マーカーをすべてのリリースグループから削除し、フラグの元のターゲティングを復元したうえで、スナップショットコホートを削除します。 ステータスは running に戻ります。

• 前提条件：曝露が凍結されていて、実験が終了していないこと
• バリアント：登録済みユーザーは自分のバリアントを維持し、新規ユーザーは元のリリース条件に基づいて再び登録できます
• 分析：曝露数の増加が再開します

バイアスが生じる可能性があります：登録を再開すると、フラグが異なる可能性のある新たなユーザー層に再び曝露されます。 凍結前に登録したユーザーと凍結解除後に登録するユーザーでは、登録時期が異なり、場合によっては条件も異なります。2つのコホートを1つの分析に混在させると、結果にバイアスが生じる可能性があります。 凍結解除の前に、特に凍結期間が長い場合や、その間に対象ユーザー層や製品に変更があった場合は、ユーザーに警告してください。凍結した結果の妥当性だけを確認したいのであれば、凍結解除は不要な場合があります。

リクエストボディはありません。

終了（experiment-end）

end_dateを設定し、停止状態に移行します。フィーチャーフラグは変更されません。

• 前提条件：実行中である必要があります（開始済みで、まだ停止していないこと）
• バリアント：ユーザーには割り当てられたバリアントが引き続き表示されます（フラグは有効なままです）
• 分析：結果はend_dateまでのデータで確定します

リクエストボディは任意です：conclusion（「won」、「lost」、「inconclusive」、「stopped_early」、「invalid」）およびconclusion_comment。

ユーザーに表示される内容を変えずに、結果を確定したい場合に使用します。 実験の露出が凍結されていた場合、終了しても凍結は解除されず、フラグはスナップショットのコホートに絞られたままです（それを望まない場合は、事前に凍結を解除するか、バリアントをリリースしてください）。

バリアントのリリース（experiment-ship-variant）

フィーチャーフラグを書き換え、選択したバリアントをユーザーの100%に配信します。

• 前提条件：開始済みである必要があります（実行中または停止済み）。ドラフトからはリリースできません。
• バリアント：すべてのユーザーにリリースしたバリアントが表示されます。フラグはキャッチオールグループを含むように書き換えられます。
• 分析：まだ実行中の場合、実験も終了します（end_dateが設定されます）

リリースする前に、必ずユーザーに確認してください — フィーチャーフラグが恒久的に書き換えられます。

必須項目：variant_key（例：「test」）。任意項目：conclusion、conclusion_comment。

フラグの変更前にレビューを必要とする承認ポリシーがある場合、409を返します。

フラグのクリーンアップPR（終了およびバリアントのリリース時のオプション）

experiment-endとexperiment-ship-variantはいずれもopen_cleanup_pr: trueを指定できます。 その場合、バックグラウンドのPostHog Codeタスクが実験のフィーチャーフラグコードを削除し、チームが接続しているGitHubリポジトリにドラフトのプルリクエストを作成します。

• ユーザーが依頼するか、確認した場合にのみ指定してください。
• キーにはtask:writeスコープが必要です。そうでない場合、リクエスト全体が403で拒否され、実験は終了もリリースもされません。
• クリーンアップが実行されるのは、呼び出しによって実際に実験が終了し、conclusionが設定されている場合のみです。停止済みの実験をリリースする場合や、結論を指定せずに終了する場合はスキップされます。また、チームでフラグのクリーンアップ機能が有効になっている必要があります。有効でない場合は通知なくスキップされます。
• 複数のリポジトリが接続されている場合は、repository（「organization/repository」）で対象を指定します。省略すると、実験に保存されたリポジトリ、チームのデフォルト、または接続されている唯一のリポジトリの順に使用します。候補が複数あり、デフォルトもない場合、指定がなければクリーンアップはスキップされます。
• experiment-cleanup-taskで進捗を確認できます。PRが作成されると、そのURLが表示されます。通常、クリーンアップには数分かかります。

アーカイブ（experiment-archive）

停止済みの実験をデフォルトのリスト表示から非表示にします。

• 前提条件：停止済みである必要があります（end_dateが設定されていること）
• バリアント：変更なし — フラグに影響はありません
• 分析：変更なし — 結果には引き続きアクセスできます

リクエストボディは不要です。experiment-updateでarchived=falseを設定すると復元できます。

リセット（experiment-reset）

実験をドラフト状態に戻します。start_date、end_date、conclusion、archivedをクリアします。

• 前提条件：すでにドラフト状態ではないこと
• バリアント：フラグは変更されず、ユーザーには割り当てられたバリアントが引き続き表示されます
• 分析：収集済みのデータは残りますが、再開始後にstart_dateを調整しない限り、結果には含まれません

リクエストボディは不要です。

複製（experiment-duplicate）

新しいドラフトとしてコピーを作成します。日付は新しく設定され、結果は含まれません。

重要：元のものとは異なる一意のfeature_flag_keyを必ず指定してください。同じキーを使用すると、両方の実験が同じフラグを共有し、一方への変更がもう一方にも影響します。

任意項目：カスタムname（デフォルトは「Original Name (Copy)」）。

プロジェクトにコピー（experiment-copy-to-project）

実験を同じ組織内の別のプロジェクトに新しい下書きとしてコピーします。コピー先が別のプロジェクトの場合は、experiment-duplicate の代わりにこちらを使用してください。同じプロジェクト内にコピーする場合は duplicate を使用します。

• 前提条件：コピー元でレガシーメトリクスを使用していないこと。コピー先のプロジェクトが同じ組織に属し、書き込み権限があること。組織間またはリージョン間のコピーはできません。
• コピーされるもの：名前、説明、タイプ、パラメーター、フィルター、プライマリ／セカンダリメトリクス（新しい uuid）、統計情報とスケジュール設定、露出条件。コピーされないもの：保存済みメトリクスへの参照（プロジェクト単位）、ホールドアウト、露出コホート、日付、結果、結論。
• フィーチャーフラグ：target_team_id は必須です。feature_flag_key は任意です。解決されたキーはその後、コピー先のプロジェクトで検索されます。渡したキーの有無ではなく、検索結果によって動作が決まります。
  • feature_flag_key を省略した場合：コピー元の実験のフラグキーがデフォルトで使用されます。このキーは通常、コピー先のプロジェクトには存在しないため、そこで同じキーの新しいフラグが作成されます。（次の項目にあるように、デフォルトのキーが既存のキーと競合することもあるため、安全を期すには明示的なキーを渡してください。）
  • 解決されたキーがコピー先のプロジェクトにフラグとしてすでに存在する場合：コピーは新しいフラグを作成せず、その既存のフラグを共有します。そのため、両方の実験が同じフラグを参照し、どちらか一方でのライフサイクル操作（公開、一時停止）が両方に影響します。既存のフラグは、多変量でバリアントが2～20個である必要があります。そうでない場合、呼び出しは400を返します。
  • 解決されたキーがコピー先のプロジェクトに存在しない場合：そのキーで新しい独立したフラグが作成されます。確実に独立させるには、コピー先にまだ存在しない feature_flag_key を渡してください。

呼び出す前に、コピー元の実験とコピー先のプロジェクトを名前で確認してください。これは、ユーザーが現在見ていないプロジェクトに書き込みます。返される実験（およびその ID）はコピー先のプロジェクトに属します。

新しいエンジンに移行（experiment-migrate）

レガシー実験（is_legacy: true、メトリクスの種類が ExperimentTrendsQuery または ExperimentFunnelsQuery）を新しい実験エンジンに移行します。

これを手動で行わないでください。 新しい実験を作成してメトリクスをコピーすると、2つ目のフィーチャーフラグが作成されるため、新しい実験には露出もデータもありません。 experiment-migrate は元のフラグを再利用するため、移行後の実験は最初から元の対象ユーザーを引き継ぎます。

• 前提条件：実験がレガシーであること。すでに新しいエンジンを使用している場合は、400が返されます。
• 動作：同じ設定で新しい実験を作成し、メトリクスを新しい形式に変換します。レガシー実験は変更されずに残るため、プロジェクトには1つのフィーチャーフラグを使用する2つの実験が存在することになります。レガシー実験では結果が表示されなくなるため、結果を取得するには移行が唯一の方法です。
• レガシーの共有メトリクス：同じ呼び出し内で変換されます。それぞれに新しい共有メトリクスが作成され、移行後の実験から参照されます。
• バリアント：変更されません。フラグは共有されるため、ユーザーは引き続き現在のバリアントを維持します。
• 分析：移行後の実験は同じ露出を読み取ります。結果は新しいエンジンで計算されるため、レガシービューに表示されていた数値と異なる場合があります。

呼び出す前に、実験が2つになることをユーザーに伝えてください。呼び出し後、両方の実験へのリンクを提示してください。 再度呼び出すと、最初の呼び出しで作成された実験が返されるため、安全に再試行できます。

リクエストボディはありません。

レガシー実験では、ほとんどの編集も拒否されます。experiment-update は、名前、説明、end_date 以外の変更に対して400を返します。 この3つはレガシー実験でも引き続き変更できるため、実験を直接編集し、これらの変更のために移行しないでください。 ユーザーが移行を求めている場合、実験の結果を必要としている場合、またはガードによって拒否されるフィールドの変更を求めている場合にのみ移行してください。その変更は、移行後の実験に適用します。

判断フレームワーク

状況	アクション	ツール
ドラフトの準備が完了し、フラグが実装され、メトリクスが設定済み	起動	experiment-launch
明確な勝者があり、有意な結果が得られた	勝者のバリアントをリリース	experiment-ship-variant
十分な時間が経過しても有意差がない	結論が出ないまま終了	experiment-end
問題が発生し、一時的に露出を停止する必要がある	一時停止	experiment-pause
一時停止後に再開する	再開	experiment-resume
新規ユーザーの登録を止め、登録済みユーザーの測定を続ける	露出を凍結	experiment-freeze-exposure
凍結後に登録を再開する	露出の凍結を解除	experiment-unfreeze-exposure
実験が終了し、クリーンアップの準備ができている	アーカイブ	experiment-archive
同じ設定で最初からやり直す必要がある	ドラフトにリセット	experiment-reset
類似の実験を新たに始めたい	複製	experiment-duplicate
同じ実験を別のプロジェクトで実施したい	別のプロジェクトにコピー	experiment-copy-to-project
レガシーな実験で、新しいエンジンが必要	移行	experiment-migrate

実験の特定

すべてのライフサイクル操作には実験 ID が必要です。ID がわからない場合は、先に finding-experiments スキルを読み込み、ユーザーの指定（名前、説明、 「最新」など）から具体的な ID を特定してください。

エラー処理

エラーメッセージ	意味
"Experiment has already been launched."	ドラフト以外の実験は起動できません
"Experiment has not been launched yet."	ドラフトの終了／一時停止／リリースはできません
"Experiment has already ended."	停止済みの実験は終了／一時停止できません
"Experiment is already paused."	代わりに再開を使用してください
"Experiment is not paused."	すでにアクティブです
"Experiment is already in draft state."	リセットするものがありません
"Experiment is already archived."	すでに完了しています
"Experiment exposure is already frozen."	凍結するものがありません
"Experiment exposure is not frozen."	凍結を解除するものがありません
"Cannot freeze a paused experiment. Resume it first."	まず再開してから凍結してください
"Group-aggregated experiments cannot have their exposure frozen."	構造上の制約です。再試行しないでください
"This experiment uses legacy metric formats..."	まず移行してください — experiment-migrate

400 が返された場合は、再試行するのではなく、状況をユーザーに説明してください。

関連スキル

• creating-experiments — 次の実験を一から作成する
• diagnosing-experiment-health — リリースまたは終了を判断する前に、結果の妥当性を確認する
• configuring-experiment-rollout — ライフサイクル操作ではなく設定編集である、変更の分割とロールアウトを行う