diagnosing-experiment-health

実験の健全性を診断する

このスキルでは、次の疑問に答えます。PostHog の実験結果がおかしい、偏っている、または空に見えるのはなぜですか？ 1 つの実験の設定、エクスポージャー、結果、実行中に変化した内容を診断し、健全性を確認します。

ディスパッチ表でユーザーの問題に一致する項目を探し、該当する診断のリファレンスファイルを読みます。

リファレンスファイル内の各診断には、検証の確度に応じて [HIGH]、[MEDIUM]、または [LOW] のタグが付いています。[HIGH] は PostHog のコードで直接検証済み、[MEDIUM] は一部検証済み、またはチームの情報源で確認済み、[LOW] はここでは検証されていない SDK や外部の挙動を示します。[LOW] の項目は、事実として断定せず、検証する仮説として扱ってください。

ステップ 1 — 実験を特定する

ユーザーが実験を名前または説明で参照している場合は、まず finding-experiments スキルを読み込み、 具体的な ID に特定してください。

experiment-get を呼び出し、以下のフィールドを取得してください。これらはほとんどすべての診断で入力として使われます。

• status（draft / running / paused / exposure_frozen / stopped）、start_date、end_date、is_legacy
• feature_flag.active と feature_flag.filters.multivariate.variants[] — バリアントキーと分割（rollout_percentage）。 これは現在のフラグです。リリースまたは編集の後は、実行時の分割を変更履歴から確認してください（ステップ 1.5）。
• feature_flag.filters.aggregation_group_type_index — 設定されている場合、実験の単位は個人ではなくグループです
• feature_flag.filters.groups[] — 各グループについて、variant、properties、 rollout_percentage（そのグループのロールアウト率。実験に参加する、一致したバケッティング単位（個人、またはフラグもしくはグループがグループタイプで集約されている場合はグループ）に対する割合）を確認してください。各グループに個別の値があるため、フラグに条件のないグループが 1 つある場合を除き、全体のロールアウト率は 1 つに定まりません。一致したコホートに対して、フラグのバリアントキーのいずれかに該当する null 以外の variant が設定されている場合、バリアントが強制的に割り当てられます（ランダム化ではなく、リリース条件による割り当て）— A7 に該当します。深刻な設定（A7b）に注意してください。ロールアウト率が高いのに、バリアントが固定されたグループの properties が広範または空の場合や、ランダム化されたグループ（variant: null）が残っていない場合、またはいずれかのアームへのリリース経路がない場合、もう一方のバリアントの対象者が不足します（分析可能な露出が一方のアームにほぼ 0 件になります）。references/bias-and-skew.md を参照してください。
• feature_flag.bucketing_identifier と feature_flag.ensure_experience_continuity — フラグがハッシュ化する対象（A3、A6、A8、A10）
• holdout と excluded_variants — 意図的に分析対象から外される人とアーム
• exposure_criteria.multiple_variant_handling — 指定がない場合、デフォルトは "exclude" です
• exposure_criteria.exposure_config — 露出イベントとそのプロパティフィルター。 未設定の場合、または $feature_flag_called が指定されている場合は、resolved_exposure_event からデフォルトの露出イベントを確認してください。 $feature_flag_called が指定されている場合は、$experiment_exposure（event IN ('$feature_flag_called', '$experiment_exposure')）も確認し、行数ではなく人数を数えてください。 $experiment_exposure を指定する設定では、resolved_exposure_event の値にかかわらず、そのイベントがカウントされます。 それ以外のイベントまたはアクションは、カスタム露出イベント です。 設定内のプロパティフィルターは、どちらにも適用されます（B12）。 どのプロパティにバリアントが格納されるかは、references/diagnostic-snapshot.md の表で確認してください。
• exposure_criteria.activation_config — デフォルトの露出に加えて適用される、アクティベーションイベントまたはアクション。 設定されている場合、最初のフラグ露出以降に発生した最初のアクティベーションイベントから、その人を露出済みとしてカウントし、そのイベント時刻を露出時刻として扱います。 カスタム露出イベントとは組み合わせられません。
• exposure_criteria.filterTestAccounts — デフォルトは true です
• 共有メトリクスを含む metrics と metrics_secondary — 各メトリクスについて、名前、タイプ、定義を確認してください。 メトリクスの説明には、名前ではなく定義を使ってください（D13）。
• stats_config — method（Bayesian または Frequentist）、信頼水準（bayesian.ci_level、frequentist.alpha）、frequentist.sequential_testing_enabled、cuped、baseline_variant_key。 method が未設定の場合は Bayesian、信頼水準が未設定の場合は 95% とみなされます。逐次検定と CUPED はプロジェクトのデフォルトに従います（C13）。
• running_time_calculation — 目標サンプル数（全バリアントの合計）、達成までに残っている日数、最小検出効果。 推定値がユーザーの入力した数値に基づく場合、または作成時に記録されてからページ上で更新されていない場合、日数は推定期間全体を表します（C12）。 実験を複製した場合、ページで更新されるまでは、複製元の値が引き継がれます。
• only_count_matured_users — E11

ステップ 1.5 — 診断スナップショットを取得する（質問する前に検証）

ユーザーに確認の質問をする前に、 references/diagnostic-snapshot.md にある診断スナップショットを取得します。このスキルのほとんどの診断は、聞き取りをしなくてもそのデータから確認したり、可能性を排除したりできます。

診断のたびに、まず手軽に確認できる情報源を読みます。保存済みの結果を読み、その後に変更履歴を読みます。 ユーザーから予想外の変更について報告があった場合は、保存済みの結果より先に変更履歴を読みます。 診断に必要な情報が露出データにしかない場合は、そのデータを確認します。 生イベントの照会は、それらの情報源では確認できない内容に限ります。

ステップ 2 — 症状を診断に照らし合わせる

ユーザーの発言…	診断グループ
「小さい方のバリアントに偏りがあるようです」／バナーに偏りと表示される	A — 偏りと不均衡
「バリアントの比率が設定した割合と一致しません」／不一致の警告／「58/42は正常ですか？」	A — 偏りと不均衡
「なぜ50/50ではないのですか？」／「毎日、片方のバリアントのユーザー数が少なくなります」	A — 偏りと不均衡
「コントロールとテストの両方にユーザーがいます」／$multiple の割合が高い	A — 偏りと不均衡
「自社の分析では均等に分かれているのに、PostHogではそうなっていません」	A — 偏りと不均衡
「フラグに対する応答のほとんどがfalseです」／「ユーザーに新しいUIが一瞬表示され、その後消えました」	A — 偏りと不均衡
サーバーサイドレンダリングのアプリで複数のバリアントに露出する	A — 偏りと不均衡
フィーチャーフラグと実験の状態の不一致に関するバナー	A — 偏りと不均衡
「distinct_idを移行しています」／実行中に「匿名からuser_idに切り替えています」	A — 偏りと不均衡
指標のカウントが露出数より大幅に少ない（例：10倍または100倍の差）	A — 偏りと不均衡（Dより先にこちらへ）
「実験の結果が0です／データが不十分です」／空	B — 空の実験
「バリアントが常にundefined／falseです」	B — 空の実験
「$feature_flag_called は発生しますが、露出が表示されません」	B — 空の実験
「フィルターを追加したら露出がゼロになりました」／「複製した実験が空です」	B — 空の実験
「露出は十分ありますが、コンバージョンがゼロです」	B — 空の実験（続いてD11）
「実験は実行中と表示されますが、数週間／数か月、露出数が変わっていません」	B — 空の実験
「実行期間を延ばすと有意性の判定が何度も変わります」	C — 解釈上の落とし穴
「有意と判定された後、再び有意ではなくなりました」	C — 解釈上の落とし穴
「実行を始めて1日ですが、結果を見てもよいですか？」	C — 解釈上の落とし穴
「露出数46で30/16に分かれています。壊れていますか？」	C — 解釈上の落とし穴
「完了／目標到達と表示されますが、有意な結果がありません」	C — 解釈上の落とし穴
「A/Aテストで有意な結果が出ています」	C — 解釈上の落とし穴
「指標が多く、有意なものとそうでないものがあります」	C — 解釈上の落とし穴
「テストバリアントの成績が悪いのですが、正しく設定されていますか？」／「この実験を確認してもらえますか？」	ステップ3 — 2つの確認、その後CとD12
「ベイズ推定では勝つ確率が96％です。リリースすべきですか？」	C — 解釈上の落とし穴
「信頼区間が重なっています。これは有意でないという意味ですか？」	C — 解釈上の落とし穴
「p値がちょうど1です」／「コントロールでリフトが表示されています」	C — 解釈上の落とし穴
「外部ツール（有意性計算ツールまたはAIエージェント）の結果がPostHogと一致しません」	C — 解釈上の落とし穴
「リリースすべきですか？主要指標は上昇していますが、副次指標は低下しています」	C — 解釈上の落とし穴
「PostHogの数値と自分のSQLのカウントが一致しません」	D — 数値とSQL
「ファネルではX％ですが、生イベントのカウントではYと表示されます」	D — 数値とSQL
「実験では横ばいですが、ダッシュボードでは低下しています」	D — 数値とSQL
「収益の合計が合っていないようです」／「内訳に『none』と表示されます」	D — 数値とSQL
「指標の名前と数値が示す内容が異なります」	D — 数値とSQL
「録画と統計が一致しません」／「露出したユーザーの録画がありません」	D — 数値とSQL
「フィルターを適用してもユーザー数が変わりません」	D — 数値とSQL
「現在の人物プロパティ（露出時点ではなく現在の状態）で結果を分類したいです」	D — 数値とSQL
「結果が更新されません」／「更新しても何も変わりません」	D — 数値とSQL
「実行中に分割／ロールアウト／指標／条件を変更したら、結果がおかしくなりました」	E — 実行中の変更
「一晩で数値が変わりましたが、誰も変更していません」	E — 実行中の変更、その後DのD8
「数日間一時停止しましたが、まだ信頼できますか？」	E — 実行中の変更
「実験を凍結しました」／「凍結後にユーザーがバリアントを失いました」／「凍結が拒否されました」	E — 実行中の変更
「終了／リリースしたら、予期せずフラグが0/100に切り替わりました」	E — 実行中の変更
「バリアントをリリースしましたが、一部のユーザーにはまだ適用されません」	E — 実行中の変更
「長期指標が主要指標と反対の動きをしています」	E — 実行中の変更
「リテンション指標に予想外のユーザーがカウントされています」	E — 実行中の変更
「実験終了後にフィーチャーフラグをシンプルな（ブール値の）フラグに戻せません」	E — 実行中の変更
「新しいバリアントで実験を再開するにはどうすればよいですか？」	E — 実行中の変更
「レガシー実験と表示されます」／指標を編集できません	E — 実行中の変更（E13 レガシー実験）
「結果を読み込めません」／多くの指標行に data: null と表示されます（レガシー実験ではない）	ステップ1.5 — 診断スナップショット（null行）
「新しいフローについてユーザーはどう考えていますか？」／実験に関する定性的なフィードバックを求めている	F — 定性的なフィードバック
「なぜユーザーはコントロールを好んだのですか？」／「テストバリアントのどこが気に入らなかったのですか？」	F — 定性的なフィードバック
症状が不明確な場合は、診断を選ぶ前に確認の質問を1つしてください。診断ごとに対処法は異なります
— 推測しないでください。
報告内容が複数のグループの項目に当てはまる場合は、それぞれのグループを読みます（ステップ3）。

スカウトや別の自動チェックからの報告には検出内容が記載されています。その検出内容に基づいて振り分け、再度取得する前に報告の数値を利用してください。

ステップ3 — 根拠のある診断をすべて提示する

ステップ2で症状を照合し、関連するリファレンスファイルを読んだ後、アクションを推奨する前に、該当する診断をすべて列挙してください。

併発しているメカニズムは、それぞれ独立して提示してください。どれか1つがより顕著でも、「待つ」または「修正する」という1つの推奨にまとめないでください。メカニズムによって対処法は異なります。体系的なバイアス（例：不均等な割り当てと Exclude の組み合わせ）は待っても解消せず、統計的なパターン（例：サンプル数が少ないことによるばらつき）は解消する可能性があります。これらをまとめてしまうと、ユーザーがまとめられた助言に従った後もバイアスが残ります。

プロジェクトの状態で検証できる経路があるメカニズムのみを列挙してください。対象は、設定（experiment-get から確認）、スナップショットデータ、アクティビティログ、またはリポジトリのソースコード（エージェントがリポジトリを保持している場合）です。設定から確認できるメカニズムも該当します。たとえば、デフォルトの multiple_variant_handling="exclude" を使った80/20の割り当ては experiment-get で確認できるため、列挙できます。確認できる情報源がないメカニズム（例：スナップショットでバリアント比率が正常なのに SRM とすること）は挙げないでください。

報告内容にかかわらず、すべての診断で次の2点を確認してください。

• 実験の開始からどれくらい経っていますか？ 結果を読む前に、実験の経過日数（start_date）と、目標サンプルに対する割合（露出合計を running_time_calculation.recommended_sample_size と比較したもの）を示してください（references/interpretation.md の C1）。 ページが使う露出合計は、最初の主要指標から取得します。保存された結果に含まれる全バリアントの number_of_samples の合計であり、exposures.total_exposures ではありません。 recommended_sample_size は、ページが推定値を最後に計算したときに保存した目標値です。 これが存在しない場合は、目標値が保存されていないと伝えてください。
• 誰が露出していますか？ 設定が適切だと判断する前に、露出対象の母集団（exposure_criteria とフラグのリリース条件）を、意思決定の対象となる人々と照合してください（references/numbers-vs-sql.md の D12）。 デフォルトの露出設定は、適切な対象者が実験に含まれていることの根拠にはなりません。 意思決定の対象者が不明な場合は、質問してください。

診断グループ

A — バイアスと偏り

バリアントのバランスが取れていないように見える、特定のバリアントに偏りがあるように見える、アプリ内の警告バナーが表示された、またはユーザーが複数のバリアントに割り当てられている場合が該当します。不均等な割り当てと Exclude の相互作用、サンプル比率の不一致とその原因、露出イベントの欠落やグループ間での送信の偏り、一部の対象者にバリアントを返さないフラグ、ID の分断、ブートストラップと /flags の不一致、実行中のフラグ編集、強制バリアント、フラグと実験の状態の不整合を扱います。

→ references/bias-and-skew.md を参照してください

B — 空の実験／露出数0／「データ不足」

よくある問題です。SDK の呼び出し（誤った評価メソッド、identify() のタイミング、重複排除）、露出の記録（カスタムイベントにバリアントプロパティがない、必須プロパティ、広告ブロッカー）、露出条件との一致（テストアカウントのフィルター、一致しないフィルター、適格性の判定順、露出前にイベントが発生）を扱います。

→ references/empty-experiment.md を参照してください

C — 有意性／解釈の落とし穴

有意性の反転、A/A テストで有意性が示される、ベイズ統計と頻度論の混同、多重比較、トラフィック量が少ないことによるばらつき、途中結果の確認／早期終了が該当します。実行時間の推定（「目標到達」は結果ではありません）と、結果の解釈を変える統計設定（逐次検定、CUPED、信頼水準、ベースラインのバリアント）も含みます。

→ references/interpretation.md を参照してください

D — 数値が一致しない（PostHog とユーザーの SQL／生のカウント）

実験ページでは、対象となるエクスポージャーの範囲、$multiple の除外、テストアカウントのフィルター、日付範囲が適用されます。これらをアドホックな SQL で再現できていることは、ほとんどありません。ファネルのアトリビューション（統計では最初から最後のステップへの遷移のみをカウント）、ブレークダウン（メトリクスイベントではなくエクスポージャーイベントから読み取る）、ユーザーごとの平均と「収益の合計」の混同、古い保存済みの結果、統計と食い違うレコーディングタブ、実験よりも狭い対象をカウントするインサイト、定義と一致しないタイトルのメトリクスを取り上げます。

→ references/numbers-vs-sql.mdを参照してください。

E — 実行途中の変更後に起きる予想外のこと（ライフサイクルとリテンションの癖を含む）

ロールアウトの拡大は安全ですが、縮小には注意が必要です。バリアントの割り当て比率を変えるのはアンチパターンで、実行途中でメトリクスを追加するのは p ハッキングです。「バリアントを出荷」するとフラグが書き換わりますが、実験を終了するだけでは書き換わりません。リセットで消去されるのは結果であり、フラグではありません（エクスポージャーの凍結解除は除きます）。一時停止、凍結、凍結解除はいずれも結果にバイアスを与える可能性があります。開始日を変更すると、分析全体が移動します。また、リテンションメトリクスの癖、「成熟したユーザー」のフィルタリング、長期メトリクスと短期メトリクスの乖離も取り上げます。

→ references/mid-run-changes.mdを参照してください。

F — 定性的なフィードバック：数値がどれだけ動いたかではなく、変更がどう受け止められたか

A～E のグループでは変化の仕組みを見つけます。F が扱うのは、そこでは答えられない問いです。つまり、実験に参加した人たちが変更をどう受け止めたかです。ユーザーが実験対象のフローを完了したときに表示する短いアンケートを使えば、評価と任意のコメントを加えて、この定性的な側面を把握できます。バリアントごとに回答を確認でき、現在 MCP 経由で利用できます。

適している実験もあれば、そうでない実験もあります。判断基準は、両方のバージョンを見せなくても、ユーザーが変更について説明できるかどうかです。フロー、レイアウト、プロセスの再設計は対象になりますが、しきい値やランキングの微調整は、測定された効果がどれほど大きくても対象になりません。仕組みに関する診断がまだ終わっていない間は、アンケートを実施しないでください。壊れたフラグのゲートに加えてアンケートを実施すると、対象者の半数が機能を一度も使えなかったまま、その機能への意見を集めることになります。また、新しいアンケートを提案する前に、既存のアンケートや最近のアンケートが対象期間をすでにカバーしていないか確認してください。

作成前に正しく把握しておくべきことが 2 つあります。単一のバリアントにだけ表示されるアンケート自体が、バリアント間の差になります。また、フラグにリンクされた 実行中の アンケートは、エクスポージャーイベントを生成することがあります。

→ references/qualitative-feedback.mdを参照してください。

ステップ 4 — 実験の状態に合わせて推奨事項を調整する

まず診断結果を提示します（ステップ 3）。そのうえで、実験の現在の状態で許可される範囲に絞って推奨します。

• Draft — 設定の変更は自由です。推奨して適用してください。 Draft のフラグでも、引き続きユーザーに影響することがあります。リセットによって作成された Draft や、既存のフラグ上に作成された Draft は、feature_flag.active が true の場合があり、そのフラグの編集は即座に該当ユーザーに反映されます。
• Running（および、開始済みで終了していない paused または exposure_frozen） — すべての変更にトレードオフがあります。推奨する前に、実験の途中で変更した場合の影響（アンチパターンか、安全か、ユーザーに見えるか）を説明してください。実験途中の変更ルールについては、configuring-experiment-rollout と、そのリファレンスファイル references/changing-distribution-after-launch.md を参照してください。 一時停止、凍結、凍結解除、リセットも変更にあたります。いずれも実験を中断し、結果にバイアスを生じさせる可能性があります（references/mid-run-changes.md の E8、E9、E16）。
• Stopped / archived — 実験とそのフィーチャーフラグは、実験結果として記録された内容を表します。推奨は、（a）既存データの解釈、（b）_次の_実験で行うこと、または（c）何が起きたかの説明に限定します。

診断は、調査結果と推奨事項で締めくくります。 実行中の実験またはそのフラグへの変更（新しい指標、新しいエクスポージャー条件、リセット、再起動、フラグの編集）は、ユーザーが判断することです。これまでに収集したデータにその変更が及ぼす影響を伝え、明示的な指示がある場合にのみ変更してください。

Stopped または archived の実験では、状態変更（ship-variant によるフラグの書き換え、手動でのフラグ編集、リセット、アーカイブ）の取り消しを先回りして提案しないでください。ユーザーが「X はなぜ起きたのですか？」と尋ねた場合は、X について説明し、「取り消す方法はこちらです」といった後書きを加えないでください。そのような提案は、ユーザーが示していない意図を前提としています。「意図したものではなかった場合は、取り消せます」や「元に戻しますか？」といった条件付きの提案も、先回りした提案にあたります。「これはどうすれば元に戻せますか？」「ship-variant をロールバックできますか？」「50/50 の配分に戻すにはどうすればよいですか？」など、ユーザーが取り消し操作を明示的に尋ねた場合に限り、取り消し方法を案内してください。

用語は一貫して使ってください。バリアント間の split は、リリース条件のオーディエンスのうち実験に参加する割合を表す rollout とは異なります。default exposure event（resolved_exposure_event）は、custom exposure event とは異なります。Multiple variant handling（exposure_criteria.multiple_variant_handling）の Exclude from analysis／Use first seen variant オプションは、複数のバリアントに露出した人をどのように集計するかを決めるものであり、どのイベントをエクスポージャーとして扱うかを決めるものではありません。

関連するスキル

• configuring-experiment-analytics — 診断で指摘されたエクスポージャーまたは指標の設定を修正します
• configuring-experiment-rollout — split 変更のアンチパターンと、安全な rollout の調整について説明します
• managing-experiment-lifecycle — 実験をそのままでは立て直せない場合に、リセット、終了、または再開します
• analyzing-experiment-session-replays — 数値に問題はないものの、その背景にある行動を確認する必要がある場合に使用します
• debugging-experiments — 他の人の実験についてサポート依頼が届き、回答を文章で作成する場合に使用します