feature-usage-feed

LLM 評価を利用した機能利用状況フィードの構築

PostHog の一部の機能（グループセッションの要約、単一セッションの要約、リプレイ AI 検索、エラートラッキング AI デバッグなど）では、毎週数百から数千件の LLM トレースが生成されます。すべてを手作業で読むのは現実的ではありません。このスキルでは、大量のトレースから、ユーザーが実際にその機能をどう使っているかを示す代表的なユースケースをリアルタイムの Slack フィードにまとめる一連の手順を扱います。

このワークフローは UI と MCP を併用し、UI を中心に進めます。トレースの調査とフィルターの特定（ステップ 1～2）は MCP を利用します。評価の作成、ドライラン、有効化（ステップ 4～5）も、エージェントに posthog:llma-evaluation-* ツールが公開されていれば MCP を利用できます。ただし、利用できないことも多く、その場合は UI に切り替えてください（アラートの設定は常に Data pipeline → destinations の UI で行います）。各ステップには UI に切り替える場合の手順が記載されています。チャットから始めた場合でも、最後は UI で作業を完了することになります。

使用するタイミング

• 「本番環境で、ユーザーは実際に [機能 X] をどう使っていますか？」
• 「より良いドキュメントの作成や改善の優先順位付けのために、[機能 X] の代表的なユースケースを特定できますか？」
• 「トレースを手作業で確認せずに、代表的な利用例を Slack フィードで受け取りたいです。」
• 「#team-[area]-usage に [機能 X] のユースケースフィードを設定してください。」

ユーザーが単一のトレースのデバッグや既存の評価の調整だけを希望している場合は、代わりに exploring-llm-traces または exploring-llm-evaluations を案内してください。

2 種類のフィルターパターン

このスキルでは、「対象の機能」を評価の対象に絞り込む方法を 2 種類扱います。

パターン A — 機能固有の trace_id プレフィックス。 独自の $ai_trace_id パターンを出力する単独の機能（例：session-summary:group:、replay-search:、エラートラッキング固有のフロー）が対象です。プレフィックスでフィルターします。

パターン B — PostHog AI のエージェントモード。 PostHog AI の特定のエージェントモード（エラートラッキング、プロダクト分析、セッションリプレイ、SQL、フラグ、アンケート、AI オブザーバビリティ）を介してユーザーが操作する機能が対象です。ai_product = 'posthog_ai' AND agent_mode = '<mode>' でフィルターします。この方法には、すべての $ai_generation に agent_mode と supermode を追加する PR #55160（2026 年 4 月にマージ済み）のデプロイが必要です。実用上の利点として、agent_mode IS NOT NULL を「ユーザーに表示されるチャットターン」の信頼できるフィルターとして使えます。バッチジョブやツール内部の LLM 呼び出しは別のコードパスを通り、agent_mode=null となるため、自動的に除外されます。

ユーザーが「PostHog AI の [ET／リプレイ／SQL／フラグ／アンケート] モードで、ユーザーは何をしようとしているのか」と尋ねている場合は、パターン B です。「[単独の機能] はどのようなユースケースを対象にしているのか」と尋ねている場合は、パターン A です。最初にパターンを選んでください。プロンプト、フィルター、Slack チャンネルの命名は、すべてその選択に基づきます。

前提条件

要件	確認方法
（パターン A）機能が、安定した $ai_trace_id パターンを持つ $ai_generation イベントを発行する	個別の $ai_trace_id プレフィックスを posthog:execute-sql で確認します
（パターン B）最近の $ai_generation イベントに agent_mode プロパティが存在する	最近の ai_product='posthog_ai' イベントで properties.agent_mode をグループ化して posthog:execute-sql を実行します。null バケットは正常です（バッチジョブとツール内部の呼び出し）。対象の各モードに null 以外の値が含まれていることを確認します。
$session_id が $ai_generation イベントに付与されている（トレースをトリガーとなったセッションにリンクする）	countIf($session_id IS NOT NULL) / count() を posthog:execute-sql で確認します
$session_id が $ai_evaluation イベントにも付与されている（Slack アラートからセッションにリンクできる）	評価を一度実行した後、$ai_evaluation イベントを対象に同じクエリを実行します
ユーザーが組織レベルの AI データ処理承認を得ている	llm_judge 評価に必要です

いずれかのイベントタイプで $session_id が欠落している場合は、続行する前にバックエンドの修正を依頼してください。UI による回避策はありません。セッション要約機能には、PR #54952 にスレッド化パターンの実例があります。パターン B については、PR #55160 にエージェントモードのスレッド化パターンがあります。

ツール

ツール	目的
posthog:query-llm-traces-list	機能の $ai_trace_id パターンに一致するサンプルトレースを検索します
posthog:query-llm-trace	特定のトレースの内容を最初から最後まで確認します
posthog:execute-sql	トレース量、session_id のカバレッジ、評価結果の分布を確認します
posthog:llma-evaluation-create	（公開されていないことがよくあります — UI での代替手順：AI observability → Evaluations → New）LLM による判定評価を作成します（最初は無効）
posthog:llma-evaluation-run	（公開されていないことがよくあります — UI での代替手順：評価の詳細ページに「Run on event」ボタンがあります）プロンプトを反復調整する際に、特定の生成結果を対象に評価をドライランします
posthog:llma-evaluation-update	（公開されていないことがよくあります — UI での代替手順：AI observability → Evaluations で評価を編集します）準備ができたらプロンプトを調整／有効化します
posthog:llma-evaluation-report-create	（公開されていないことがよくあります — UI での代替手順：評価の詳細ページに「Reports」タブがあります）フィードの稼働開始後、評価に関する AI レポートをスケジュールし、シグナル品質を継続的に監視します
posthog:workflows-list / posthog:workflows-get	（公開されていないことがよくあります — UI：Data pipeline → Workflows）既存のワークフロー設定を参照します。新しいフィードを設定する際、既存のフィード構成を複製するのに便利です。読み取り専用で、作成／更新ツールはまだ公開されていないため、手順 6 の Slack ワークフロー設定は UI のみで行います。

開始する前に、エージェントの MCP ツールセットで posthog:llma-evaluation-* ツールが実際に公開されているか確認してください。 読み込まれていない場合は、手順 4〜5 をツール呼び出しではなく、UI の操作手順として扱ってください。

ワークフロー

ステップ 1 — フィルターを特定する

**パターン A（機能固有の trace_id プレフィックス）：**機能に対応するプレフィックスを見つけます。

SELECT
    splitByChar(':', coalesce(properties.$ai_trace_id, ''))[1] AS root,
    splitByChar(':', coalesce(properties.$ai_trace_id, ''))[2] AS subtype,
    count() AS events
FROM events
WHERE timestamp > now() - INTERVAL 3 DAY
    AND event = '$ai_generation'
    AND properties.$ai_trace_id IS NOT NULL
GROUP BY root, subtype
ORDER BY events DESC
LIMIT 25

注：coalesce(..., '')は重要です。これがないと、HogQL では nullable 列に対するsplitByCharでエラーが発生します。

**パターン B（PostHog AI エージェントモード）：**対象とするモードのカバレッジとボリュームを確認します。

SELECT
    properties.agent_mode AS agent_mode,
    properties.supermode AS supermode,
    count() AS events,
    count(DISTINCT properties.$ai_trace_id) AS traces
FROM events
WHERE timestamp > now() - INTERVAL 3 DAY
    AND event = '$ai_generation'
    AND properties.ai_product = 'posthog_ai'
GROUP BY agent_mode, supermode
ORDER BY events DESC
LIMIT 20

agent_modeの想定値は、error_tracking、product_analytics、sql、session_replay、flags、survey、llm_analytics、nullです。nullは、おおむねバッチジョブとツール内部の呼び出し（ユーザーチャットではないもの）です。supermode='plan'では、計画のターンと実行のターンが分かれます。フィードが特に plan モードを対象としている場合は、別に取り上げる価値があります。

モードとおおよそのボリュームを記録します。ボリュームが少ないモード（1 日あたり 100 件未満）では、初期の検証が難しいほど更新頻度の低いフィードになります。ボリュームが多いモード（1 日あたり 1,000 件超）では、Slack の過剰な通知を避けるためにサンプリングが必要になる場合があります。サンプリングについては「ヒント」セクションを参照してください。

ステップ 2 — サンプルトレースをいくつか取得する

ステップ 4 でプロンプトを反復改善する際に使用します。

パターン A：

posthog:query-llm-traces-list
{
  "properties": [
    { "type": "event", "key": "$ai_trace_id", "operator": "icontains", "value": "<your-prefix-here>" }
  ],
  "limit": 10,
  "dateRange": { "date_from": "-2d" },
  "randomOrder": true
}

パターン B：

posthog:query-llm-traces-list
{
  "properties": [
    { "type": "event", "key": "ai_product", "operator": "exact", "value": "posthog_ai" },
    { "type": "event", "key": "agent_mode", "operator": "exact", "value": "<mode-here>" }
  ],
  "limit": 10,
  "dateRange": { "date_from": "-2d" },
  "randomOrder": true
}

randomOrder: trueは重要です。新しいものに偏ると、代表性のないサンプルになります。テストするトレースを 5～10 件選びます。

出力サイズに関する警告：query-llm-traces-listにlimit: 10を指定すると、通常、JSON が 3～6 MB 返されます（各生成の入力と出力の全内容を含みます）。これではコンテキストウィンドウの上限を超えてしまいます。「result exceeds maximum allowed tokens」エラーが表示されたら、直ちに要約をサブエージェントに委任してください。サブエージェントには、各トレースについて、トレース ID、最初のユーザーメッセージ（約 300 文字に短縮）、会話の内容を一文で説明したものを抽出するよう依頼します。生のファイルをそのまま読み込もうとしないでください。

トレースツールが返すのは AI のペイロードのみです。 $current_url、agent_mode、ai_productなどのカスタムプロパティは、値を伴わずに_redactedKeys内の名前として返されます。 サンプルで必要な場合は、サンプルのトレース ID を指定してposthog:execute-sqlで読み取ってください。 上記の両パターンで行っているように、これらのプロパティでフィルタリングしても影響はありません。

パターン B のサンプルでは、トピックの逸脱に注意してください。agent_modeタグは、各ターンでユーザーが選択したモードを示します。ただし、同じ会話内でユーザーが話題を外れても、チャットの状態にはそのモードが保持されます（例：ユーザーが「error tracking」モードを選択し、3 ターン後に無関係な料金について質問した場合）。評価プロンプトの分類ステップでは、話題の逸脱を許容する必要があります。PASS は「ユーザーがこのモードの対象範囲内と認識できることをしている」、FAIL は話題の逸脱を捉えることを意味するようにします。そうしないと、モードタグが付いているというだけで、無関係な PASS エントリーがフィードに含まれてしまいます。

ステップ 3 — LLM 判定プロンプトを作成する

このプロンプトには 2 つの役割があります。（a）トレースが関連性のあるものかどうかを分類すること、（b）そのまま Slack に投稿できる（前置きやメタな説明のない）推論テキストを生成することです。推論フィールドが Slack メッセージの本文になります。

テンプレート：

You are analyzing a PostHog [FEATURE NAME] trace to extract its real use case.
Your reasoning text will be posted directly to a Slack channel as a notification.
Write it as a short, ready-to-post message — no preamble, no meta-description.

Step 1 — Classification:
- PASS = this trace is the [feature kind] you care about
- FAIL = a different LLM call or a false match
- N/A = ambiguous from the trace alone

Step 2 — Reasoning (only matters if PASS). Write 2-3 sentences in this exact format:

"[OPENER] [what they targeted/filtered for]. They were
trying to [understand X / debug Y / find Z]. The result surfaced [key pattern
or finding]."

Your output MUST start with the exact phrase "[OPENER]". No other opening is allowed.

Rules:
- No "This is a [feature]..." or "The input contains..." preamble
- No JSON, field names, system-prompt references, or meta-description
- Concrete > generic. "users hitting error tracking for the first time" beats "user behavior"
- If you cannot infer one of the three pieces from the trace, write "(unclear from trace)" in that slot — do not guess

ユーザーが実際にその機能をどのように利用するかに合った [OPENER] を選んでください。 強制オープナーは重要です（モデルが「このトレースは……」というメタな説明に逸れるのを防ぎます）が、動詞はインタラクションに合ったものにする必要があります。

機能／モード	OPENER
セッションの要約（グループ／単一）	A user ran a summary on
リプレイの AI 検索	A user searched replays for
エラートラッキングモードの PostHog AI	A user asked PostHog AI about
セッションリプレイモードの PostHog AI	A user asked PostHog AI about
SQL モードの PostHog AI	A user asked PostHog AI to write SQL for

注：supermode='plan' は agent_mode の行に追加するサブフィルターであり、独立した行ではありません。プランモードのみを対象にするには、agent_mode='<mode>' AND supermode='plan' でフィルターし、"A user asked PostHog AI to plan" のようなオープナーを選びます。

チャットベースの機能に "A user ran" を強制すると、「A user ran a question about...」のような不自然な表現になり、Slack で読むと違和感があります。強制オープナーというパターン自体は共通ですが、具体的なフレーズは機能ごとに異なります。

否定的な例のリスト（「『This is a...』という前置きは禁止」など）は、どのオープナーを使う場合も重要です。削除しないでください。

ステップ 4 — 評価を作成して（無効の状態で）テストし、反復する

すべてのトレースにすぐ適用されないよう、enabled: false で作成します。

posthog:llma-evaluation-create が公開されている場合は、次のペイロードを使用します。

posthog:llma-evaluation-create
{
  "name": "[feature] use case feed",
  "description": "Extracts canonical use cases for [feature] for the #team-[area]-usage Slack feed",
  "evaluation_type": "llm_judge",
  "evaluation_config": {
    "prompt": "<full prompt from step 3>"
  },
  "output_type": "boolean",
  "output_config": { "allows_na": true },
  "model_configuration": {
    "provider": "<provider>",
    "model": "<model>"
  },
  "enabled": false,
  "conditions": [
    {
      "id": "default",
      "rollout_percentage": 100,
      "properties": [
        // Pattern A — feature-native trace_id prefix:
        { "key": "$ai_trace_id", "type": "event", "operator": "icontains", "value": "<your-prefix>" }

        // Pattern B — PostHog AI agent mode (use these INSTEAD of the trace_id filter):
        // { "key": "ai_product", "type": "event", "operator": "exact", "value": "posthog_ai" },
        // { "key": "agent_mode", "type": "event", "operator": "exact", "value": "<mode>" }
      ]
    }
  ]
}

モデルの選択はユーザーに任せてください。LLM 判定のコストはイベント量に比例して増加します。また、低コストと高性能のどちらを選ぶかは、ユーザー自身の支出許容度やシグナル品質の要件に応じて決めるべき、実際的なトレードオフです。代わりに選択しないでください。

UI を使う場合（llma-evaluation-create が公開されていない場合）：AI observability → Evaluations → New evaluation に進みます。Type = LLM judge、output = boolean + allow N/A、filters = 上記と同じ、enabled = off に設定します。ステップ 3 のプロンプトを貼り付けます。

次に、サンプルのトレースに対してドライランを実行します。

posthog:llma-evaluation-run が公開されている場合：

posthog:llma-evaluation-run
{
  "evaluationId": "<uuid from create>",
  "target_event_id": "<a $ai_generation event id from step 2>",
  "timestamp": "<ISO timestamp of that event>"
}

UI を使う場合： 評価の詳細ページで、トレースサンプルのイベント ID を使って「Run on event」ボタンをクリックします。

返された $ai_evaluation_reasoning を確認します。前置きが入っていたり、話が逸れたり、入力について説明したりする場合は、プロンプトを修正して（llma-evaluation-update を使うか、UI で編集して）再実行します。有効にする前に、3～5 件のトレースで反復してください。

反復中によくある失敗パターン：

症状	対処
推論が「This is a...」で始まる	強制オープナーの指示を強化し、反例を追加する
推論が一般的すぎる（「ユーザーの行動」「さまざまなパターン」）	プロンプトに具体的な表現の肯定例を追加する
モデルがすべてを PASS に分類する	FAIL の定義を厳密にし、該当しない例を追加する
推論が Slack に投稿するには長すぎる	文の上限を明記する（「最大 3 文、厳守」）

ステップ 5 — 評価を有効にする

3～5 回のサンプル実行で、Slack にそのまま投稿できる出力が得られたら有効にします。

posthog:llma-evaluation-update が公開されている場合：

posthog:llma-evaluation-update
{
  "evaluationId": "<uuid>",
  "enabled": true
}

UI での代替手順： AI observability → Evaluations → 評価を開く → 有効化を切り替えます。

これで、新しい一致する $ai_generation イベントが発生するたびに評価が実行されます。

ステップ 6 — ワークフローを構築する（UI のみ）

ワークフローの設定は書き込み用 MCP からはアクセスできません（posthog:workflows-list／posthog:workflows-get は読み取り専用です）。以下は UI での手順です。

前提条件： 始める前に、対象チャンネルに PostHog Slack ボットを招待してください（Slack チャンネルで /invite @PostHog を実行します）。これを行わないと、Slack への送信ステップは保存時ではなく送信時に、原因が分かりにくい権限エラーで失敗します。見落としやすいため注意してください。

6.1 ワークフローを作成する

Data pipeline → Workflows → New workflow の順に選択します。ステップ 4 の評価名と一致するように、名前を <feature> use case feed にします。

6.2 トリガーステップ

• イベント： AI evaluation (LLM)（つまり $ai_evaluation）。これは評価の実行時に出力されるイベントで、$ai_evaluation_* プロパティを持つ唯一のイベントです。元の $ai_generation イベントには評価結果が追加されないため、ここで $ai_generation を条件にしても一致するものはありません。
• プロパティフィルター（両方必須）：
  • AI Evaluation Name (LLM) が <your eval name from step 4> と等しい
  • AI Evaluation Result (LLM) が true と等しい

⚠️ 重要： 保存される $ai_evaluation_result の値は文字列の 'True'／'False'／'None' であり、'PASS'／'FAIL'／'N/A' ではありません（プロンプトテンプレート内での呼び方とは異なります）。Workflows UI のプロパティフィルターでは true が 'True' に正規化されるため、ドロップダウンから equals true を選択すれば機能します。ただし、別の場所で生の SQL（たとえば hog 関数）を使って設定する場合は、文字列リテラルが必要です。保存する前に、保存された値の分布を確認してください。

SELECT DISTINCT toString(properties.$ai_evaluation_result) AS result, count() AS n
FROM events
WHERE event = '$ai_evaluation'
  AND properties.$ai_evaluation_name = '<your eval name>'
  AND timestamp > now() - INTERVAL 1 HOUR
GROUP BY result

値が True／False／None のみで、True が大半を占めていれば、UI の equals true フィルターで一致します。それ以外の値がある場合は、適宜調整してください。

6.3 Slack 送信ステップ

• Add step → Slack dispatch
• チャンネル： #<your-team>-usage-feed
• 送信者／ボットの表示名： チャンネル内で見栄えのよい名前（例：PostHog Usage Feed）
• Blocks（Slack block-kit JSON） — これを貼り付け、<project_id> を実際の数値のプロジェクト ID（例：2）に置き換えます。

[
  {
    "text": {
      "text": "<emoji> *{event.properties.$ai_evaluation_name}* triggered by *{person.name}*",
      "type": "mrkdwn"
    },
    "type": "section"
  },
  {
    "text": {
      "text": "{event.properties.$ai_evaluation_reasoning}",
      "type": "mrkdwn"
    },
    "type": "section"
  },
  {
    "type": "actions",
    "elements": [
      {
        "url": "https://us.posthog.com/project/<project_id>/ai-observability/traces/{event.properties.$ai_trace_id}?event={event.properties.$ai_target_event_id}",
        "text": { "text": "View Trace", "type": "plain_text" },
        "type": "button"
      },
      {
        "url": "https://us.posthog.com/project/<project_id>/replay/{event.properties.$session_id}",
        "text": { "text": "View Trigger Session", "type": "plain_text" },
        "type": "button"
      },
      {
        "url": "{person.url}",
        "text": { "text": "View Person", "type": "plain_text" },
        "type": "button"
      }
    ]
  }
]

機能の内容に合った <emoji> を選びます。📊 はプロダクト分析、🐛 はエラー追跡、🎬 はセッションリプレイ、🔎 は検索／AI 検索、🧪 は実験、🚩 はフラグ、📋 はアンケート、🧠 は一般的な AI を表します。

{event.properties.X} と {person.X} のプレースホルダーは有効な PostHog テンプレート構文で、送信時に値が解決されます。

6.4 有効化する前にテストする

Workflows の Test パネルには 2 つのモードがあります。何も考えずに「Test」を押すと、実際には問題がないのに連携が壊れているように見えることがあるため注意してください。

• Synthetic event（デフォルト）— Test パネルが $ai_evaluation のペイロードを生成し、Slack の実 API を呼び出さずにフローを実行します。ブロックテンプレートのドライランには便利ですが、{event.properties.$ai_*} プレースホルダーが null として解決され、Slack のブロックバリデーターがペイロードを invalid_blocks で拒否することがあります。これはテストハーネスの影響であり、実際のバグではありません。原因を追わないでください。
• 「Make real HTTPS requests」 — このトグルをオンにします。Workflows は、フィルターに一致する最近の実際の $ai_evaluation イベントを取得し、実際の Slack 投稿を含めてフローをエンドツーエンドで実行します。実際に「動作する」ことを確認できるテストです。一致する実イベントがまだない場合（評価を有効にした直後によくあります）は、自分で機能を実行し、約 1 分待ってから再試行してください。

推奨手順：Synthetic event でブロックテンプレートの表示を確認 → real-requests をオンにする → チャンネルに実際の投稿が届くことを確認 → ワークフローを保存して有効化します。

ステップ 7 — 本番環境でエンドツーエンド検証する

ワークフローを有効にしたら、自分で機能を実行します。1〜2 分以内に、次のことを確認してください。

1. $ai_generation イベントが AI オブザーバビリティに表示される
2. 評価が自動実行され、$ai_evaluation イベントが出力される
3. ワークフローが実行され、Slack の投稿が設定済みのチャンネルに届く
4. 「View Trigger Session」をクリックすると、リプレイのホームページではなく、自分が機能を使っている録画が表示される

「View Trigger Session」をクリックしたときにリプレイのホームページが表示される場合、$ai_evaluation イベントに $session_id がありません（これは $ai_generation イベントとは別のもので、2 つのイベントへの紐付けはそれぞれ独立しています）。バックエンドの修正が必要です。前提条件を参照してください。

実例 A（パターン A）：グループセッション要約のユースケース

パターン：group_summary_use_case_feed 評価の結果を #<team>-usage-feed チャンネルにストリーミングします。トレースの接頭辞：session-summary:group:。冒頭文："A user ran a group summary on"。Slack チャンネルには、たとえば次のように表示されます。

📊 group_summary_use_case_feed が some user によって実行されました "ユーザーが、過去 7 日間のある企業のオンボーディングセッションをグループ要約しました。アカウントの有効化率が低い理由を理解しようとしていました。要約では、アカウント作成後に会社のオンボーディングウィザードで大半のユーザーが離脱することが明らかになりました。" [トレースを表示] [トリガーセッションを表示] [人物を表示]

これを実現した PR（スキルの手順ではなく、session_id の紐付けパターンの実例としてリンクしています）：

• PostHog/posthog#54952 — セッション要約バックエンドで trigger_session_id を $ai_generation イベントに渡します
• （後続の PR — $session_id を $ai_evaluation イベントに追加します）

実例 B（パターン B）：エラートラッキングモードの PostHog AI

パターン：agent_mode = 'error_tracking' に絞ったフィードを #<team>-usage-feed チャンネルにストリーミングし、「エラートラッキングモードで PostHog AI にチャットするとき、ユーザーは実際に何をしようとしているのか？」に答えます。エージェントモードによってモードの規模は 10 倍以上異なることがあるため、配線する前に §ステップ 1 に従ってボリュームを抜き取り確認します。ボリュームの多いモードはチャンネルを埋め尽くす可能性があります。冒頭文："A user asked PostHog AI about"。

有効化 PR：PostHog/posthog#55160 — チャットエージェントのループが出力するすべての $ai_generation に agent_mode と supermode を渡します。配線は ee/hogai/core/agent_modes/executables.py（AgentExecutable._get_model）にあり、ee/hogai/llm.py の MaxChatMixin にある既存の posthog_properties フィールドを通じて辞書を渡します。この PR より前は、特定のモードに PostHog AI の評価を絞ることはできませんでした。PostHog AI の生成をすべて評価することになり、ノイズの多いフィードと一桁台の低い PASS 率につながっていました。

設定時に確認された重要な点：agent_mode タグはターン実行時のモードを示しますが、ユーザーが会話の途中で話題を外れても、チャットの状態にはモード選択が保持されます。抜き取り確認では、agent_mode=error_tracking のサンプルに、最終的にセッションリプレイの料金について話していた会話が含まれていました。評価プロンプトの分類では、話題の逸脱を許容する必要があります。ターンがそのモードの対象範囲内だとはっきり判別できる場合にのみ PASS とし、会話がまったく別の話題に逸れている場合は FAIL とします。

公開後のシグナル品質の検証

フィードを1〜2日稼働させたら、評価結果を大規模に確認します。

posthog:llma-evaluation-report-create が公開されている場合： 評価の AI レポートをスケジュールし、こちらから依頼しなくても合否の概要が届くようにします。

posthog:llma-evaluation-report-create
{
  "evaluation": "<uuid>",
  "frequency": "scheduled",
  "rrule": "FREQ=WEEKLY;BYDAY=MO",
  "delivery_targets": [{ "type": "email", "value": "[email protected]" }]
}

posthog:llma-evaluation-report-generate は設定済みのレポートをすぐに実行し、posthog:llma-evaluation-report-run-list は過去の実行内容を返します。

UI での代替手順： AI observability → Evaluations で評価を開き、「Reports」タブを選択します。

FAIL の割合が大きい場合は、分類条件が厳しすぎるため、緩和してください。PASS に汎用的な推論が多い場合は、具体性を徹底するようプロンプトを調整してください。レポートを使えば、個々のイベントをスクロールして確認しなくても、すばやく状況を把握できます。

必要に応じて、生のイベントを抜き取り確認します（注：保存される結果の値は 'PASS' ではなく 'True' です。手順6を参照してください）。

SELECT
    properties.$ai_evaluation_reasoning AS reasoning,
    properties.$ai_trace_id AS trace_id,
    timestamp
FROM events
WHERE event = '$ai_evaluation'
    AND properties.$ai_evaluation_name = '<your eval name>'
    AND properties.$ai_evaluation_result = 'True'
    AND timestamp > now() - INTERVAL 1 DAY
ORDER BY timestamp DESC
LIMIT 25

ヒント

• reasoning フィールドがそのまま Slack メッセージになります。「分類前の思考連鎖」ではなく、その用途に合わせてプロンプトを設計してください。モデルは、Slack ですぐ使える構造化テキストを一度の処理で生成できます。
• LLM の判定結果は、再実行すると非決定的に変わります。プロンプトとモデルを固定しても、1〜5％程度の誤差が生じると想定してください。再現性が必要な場合は、model_configuration で決定論的なプロバイダー／シードを固定してください。
• $ai_trace_id のプレフィックスに対する conditions プロパティのフィルターを使い、評価の対象を厳密に絞り込んでください。そうしないと、プロジェクト内のすべての $ai_generation イベントが対象となり、LLM のコストがかさみます。
• 大量のイベントが発生する機能（週あたり10,000件を超えるトレース）では、サンプリングを検討してください。すべてのイベントではなく、一致するイベントの一定割合に対して評価を実行するよう設定します。Slack が大量の通知であふれるのは、実際に起こり得る障害です。
• アラート内で最も価値の高いリンクは「View Trigger Session」ボタンです。このボタンがないと、フィードは単なるテキストにすぎず、ユーザーが実際に何をしていたのか確認できません。フィードを公開済みにする前に、手順7で動作を確認してください。
• フィードを公開したら、PASS となった実行の reasoning を確認し続けてください（スケジュール済みレポート、または $ai_evaluation_result = 'True' を指定した上記の SQL を利用）。そうすることで、主要なユースケースのクラスターを見つけられます。これにより、フィードを単なる通知の配信ではなく、実際のプロダクトインサイトにつなげられます。