creating-experiments

実験の作成

このスキルでは、新しい A/B テスト実験を作成する手順を説明します。プロジェクトを確認し、次に 3 ステップのフローに進み、最後に下書きを報告します。

基本原則：まず下書きを作り、詳細を調整する

まず実験をすばやく下書きとして作成し、その後で指標と設定を調整します。 ユーザーはすぐに具体的な下書きを確認し、内容を改善できます。 質問するのではなく、プロジェクトの事実に基づいて設定を選び、どの選択が推測なのかを伝えます。 例外はバケッティングです。事実だけでは決められないため、実験を作成する前に確認してください。

ステップ 0：プロジェクトを確認する

適切なバケッティング、指標、実施期間はプロジェクトによって異なります。ページを閲覧する人、フラグを評価する SDK、指標イベントの発生頻度を確認します。 何かを設定する前に、これらを確認してください。

1. リクエストから、対象（変更に到達したことを示すイベント。通常、ページの場合は $pageview）と、候補指標イベントを推測します。 read-data-schema で両方が存在することを確認してください。見つけられるイベント名をユーザーに尋ねる必要はありません。 ページの場合は、対象イベントの $host と $pathname についても event_property_values を読み取ってください。 応答では値がすべて列挙されるのではなくサンプルが示されるため、ある値が存在しない証拠としてではなく、プロジェクトで記録される値の形式（末尾のスラッシュ、www. の接頭辞、大文字・小文字）を確認するために参照してください。 完全一致フィルターには、その形式を反映させる必要があります。すべてのページビューが /pricing/ と記録されている場合、/pricing では何も一致しません。また、ホストが www.example.com の場合、example.com では何も一致しません。

2. experiment-setup-context ツールが利用可能な場合は、target_event と metric_event を指定して 1 回呼び出します。 ウェブの対象範囲では、完全一致の $host を含む target_properties を追加します。 対象範囲が 1 ページの場合は、完全一致の $pathname も追加します。 target_url_contains は $current_url に対する部分文字列一致です。 ドメインだけを指定すると、その文字列を含むあらゆるホストに一致し、notexample.com も対象になります。また、ホームページのパスを指定すると、その配下のすべてのページに一致します。 どちらの場合も、トラフィックとエクスポージャー率が実際より多く見積もられます。 複数のページにまたがる対象範囲では、完全一致の $host を指定し、target_url_contains にはパスの一部だけを指定します。 候補指標がイベントの一部の発生だけをカウントする場合は、同じ呼び出しに metric_properties を追加します。 previous_experiments_limit: 5 を指定します。前例を確認するには 5 件で十分です。デフォルトの 10 件では、得られる情報がほとんど増えないのに応答がおよそ 2 倍になります。 ツールが利用できない場合は、呼び出さずに続行し、以下の選択はすべて最善の推測として扱います。表示されていないツールを呼び出してはいけません。

   各フィルターには、event または person の type、key、operator、value が必要です。 この呼び出しでは flag_evaluates_to 演算子は拒否され、その演算子名を示す 400 エラーが返されます。 1 つのドメインのホームページの場合：

   {
     "target_event": "$pageview",
     "target_properties": [
       { "key": "$host", "type": "event", "operator": "exact", "value": ["www.example.com"] },
       { "key": "$pathname", "type": "event", "operator": "exact", "value": ["/"] }
     ],
     "metric_event": "your_conversion_event",
     "previous_experiments_limit": 5
   }
   

3. 結果に references/setup-decisions.md を適用します。このファイルでは、各事実を選択項目（バケッティング、フラグの評価場所、エクスポージャー、主要指標、実施期間、前例）および要約用の優先度に対応付けています。

4. これらの選択をステップ 1〜3 に引き継ぎます。

選択が「未決定」で、かつユーザーが会話に参加している場合に限り、ユーザーに確認してください。 ユーザーが不在だと伝えている場合、または質問なしで下書きを作るよう依頼している場合は、デフォルトで決定し、未解決の点をレポートに記載します。

3 ステップの作成フロー

ステップ 1：何をテストしますか？

experiment-create を呼び出す前に、以下を確認します。

• 実験名 — 内容がわかる名前にします。可能であれば、コンテキストから推測します
• 仮説 — 何が起こると予想するかを記述します（description に設定します）
• フィーチャーフラグのキー — ケバブケースにします。ユーザーが既存のフラグを指定していない場合は、新しいキーを推測します。 フラグは自動的に作成されるため、別途作成しないでください。唯一の例外はデバイス ID によるバケット分けです。experiment-create では設定できません（configuring-experiment-rollout のレシピを参照してください）。
• タイプ — 空欄のままにします（内部的に "product" がデフォルトになります）。"web" は、ブラウザーで PostHog のツールバーを使って視覚的に設定するノーコード実験用に予約されています。MCP 経由では実質的に操作できません。ユーザーがノーコード／ツールバー実験を希望する場合は、ここでは作成せず、PostHog UI を案内してください。

これらを推測するのに十分な情報がユーザーから提供されている場合は、質問せずにそのまま進めてください。

ステップ 2：誰にどのバリアントを表示しますか？

これはロールアウト設定に関するステップです。

ロールアウトについて質問する前に、必ず configuring-experiment-rollout を読み込んでください。 質問の表現、推奨事項、回答後の分岐はそこに記載されています。ロールアウトに関する質問を独自に作成したり、覚えている例がユーザーの状況にも当てはまると決めつけたりしないでください。

主な判断ポイント（詳細は configuring-experiment-rollout に記載されています）：

• バリアントの分割（バリアントの数と、それぞれの割合）
• 全体のロールアウト割合（全ユーザーのうち、実験に参加する割合）
• バケット分け、および認証ステップをまたいでフラグを維持するかどうか。プロジェクトの情報だけでは判断できないため、ユーザーに選んでもらいます

ユーザーがロールアウトの詳細を指定しない場合は、デフォルトを使用します。コントロール／テストを 50/50 に分割し、ロールアウトを 100% にします。

ステップ 3：影響をどのように測定しますか？

これは分析と指標に関するステップです。指針を得るため、configuring-experiment-analytics スキルを読み込んでください。 このスキルの最初のステップでは、新しい指標を作成する前に、再利用できる既存の共有指標があるかを確認します。プロジェクトですでに設定されている指標を重複して作成しないでください。

作成時に指標を設定しないでください。 指標は experiment-create には渡されません。作成後に experiment-update で追加します。これにより、作成時の呼び出しを簡潔に保てます。

ユーザーがあらかじめ指標を指定した場合は、その内容を確認し、作成直後に追加してください。指定がない場合は、仮説（ステップ 0）から主要指標を推測し、作成後に追加してください。推測したことを伝えてください。

ステップ 0 で実行時間の見積もりが作成された場合は、その計画を実験に保存できるよう、running_time_calculation として experiment-create に渡してください。

作成方法

experiment-create を次のように呼び出します。

{
  "name": "Descriptive experiment name",
  "feature_flag_key": "kebab-case-key",
  "description": "Hypothesis: [what you expect to happen]",
  "feature_flag": {
    "filters": {
      "multivariate": {
        "variants": [
          { "key": "control", "name": "Control", "rollout_percentage": 50 },
          { "key": "test", "name": "Test", "rollout_percentage": 50 }
        ]
      },
      "groups": [{ "properties": [], "rollout_percentage": 100 }]
    }
  }
}

フラグの設定は、非推奨の parameters キーではなく、フラグ独自のフィルター形式で feature_flag オブジェクトに指定します。 ここには異なる2種類のパーセンテージがあるため、混同しないでください。

• filters.multivariate.variants[].rollout_percentage は、実験に参加したユーザーを各バリアントにどのように振り分けるかを示します（合計は100にする必要があり、均等に分けることを推奨します）。
• filters.groups[0].rollout_percentage は全体に対するゲートです。つまり、すべてのユーザーのうち、実験に参加する割合を示します（0～100。省略時のデフォルトは100）。

重要な詳細：

• バリアントは最低2つ、最大20個です。特定のバリアントキーは必須ではありません。分析のベースラインは、"control" をキーとするバリアントがあればそれを、なければ最初のバリアントをデフォルトにします（stats_config.baseline_variant_key で上書きできます）。ユーザーが特定のキーを求めない限り、ベースラインのキーには慣例として "control" を使います。
• filters.groups[0].rollout_percentage を省略した場合、デフォルトは100です。
• バケッティングと ensure_experience_continuity：デフォルトのユーザー ID によるバケッティングを使い、ensure_experience_continuity は指定しないで、チームの永続性のデフォルト設定を適用します。この呼び出しの前に、ステップ0で確認したサーフェスの ID の内訳と、デバイス ID によるバケッティングや永続性を使う場合にそれぞれ必要になることを報告し、ユーザーに選んでもらいます。デバイス ID によるバケッティングには、先にフラグを作成する必要があります。そのため、下書きができるまで選択を待つことはできません。ID の内訳だけでは判断できません。「configuring-experiment-rollout の「ログインをまたいだバケッティングと永続性」を参照してください。
• 統計設定にはチームのデフォルト（手法、信頼水準）を使います。ユーザーが別の手法を求めた場合にのみ、stats_config を設定します。

作成後

1. 下書きの内容を3つのグループに分けて報告します。これにより、ユーザーはすばやく確認できます。

   • 確信を持って設定：選択内容と、その根拠となる事実（「共有指標『Signups』をリンクしました。ご希望どおり、ユーザーごとのサインアップイベント数をカウントします」）。
   • 最善の推測です。ご確認ください：選択内容、根拠となる事実、変更される条件（「直近4件の実験でこの方法でコンバージョンを測定していたため、ファネル指標にしました。代わりにユーザーごとの回数をカウントしたい場合はお知らせください」）。
   • 未決定：不足している情報と、決定方法（「フラグはローカル評価でサーバー上でも評価されます。サーバーとブラウザーで同じ distinct ID が使われているか確認してください」）。

   また、読み取れなかったものがあれば伝えます。たとえば、利用できなかったツールや、ステータスが ok ではなかったセクションです。

2. 実験の URL を必ず表示します。 experiment-create のレスポンスには _posthogUrl が含まれます。ユーザーが UI で実験を表示して設定できるよう、このリンクを必ず表示してください。

3. コード内でフィーチャーフラグを実装するよう、ユーザーに伝えます。 実験ページへのリンクを示し、「こちらに示すとおりにフラグを実装してください」と伝えます。実験の詳細ページには、ユーザーの SDK 向けの実装スニペットが表示されます。

4. まだ設定されていない場合は、指標の設定を案内します。configuring-experiment-analytics スキルを読み込みます。

5. ユーザーが求めた場合にのみ、実験を開始します。作成は下書きの状態で終了します。開始すると実際のユーザーに対してフィーチャーフラグが有効になるため、指示がない限り experiment-launch を呼び出してはいけません。

関連スキル

• configuring-experiment-rollout — バリアントの分割、ロールアウトの割合、テストの対象者
• configuring-experiment-analytics — 曝露条件と主要・副次指標
• managing-experiment-lifecycle — 実験作成後の開始、一時停止、リリース、終了