turning-engineering-analytics-into-insights

エンジニアリング分析をインサイトとサブスクリプションに変える

エンジニアリング分析ダッシュボードと MCP ツール（pull-requests、workflow-health、pr-lifecycle、engineering-analytics-broken-tests、…）は、 厳選された HogQL を内部で実行します。UI やツールの出力には基盤となるテーブル名が一切表示されず、 エンドポイント自体をインサイトとして保存したり、サブスクリプションを設定したりすることもできません。 ただし、データは次の 2 つの基盤を通じて直接クエリできます。

• 生のウェアハウステーブル — <prefix>github_pull_requests、<prefix>github_workflow_runs、 <prefix>github_workflow_jobs、<prefix>github_reviews、および <prefix>github_teams / <prefix>github_team_members（組織チームのメンバーシップ — 作成者からチームへの対応表）。HogQL でクエリする、通常のチームスコープのテーブルです。
• 固定名の厳選されたウェアハウスビュー 3 つ — engineering_analytics_job_costs、 engineering_analytics_ci_job_history、engineering_analytics_ci_failures。接続された GitHub ソースごとにチームへプロビジョニングされます。 非マテリアライズドのため、クエリ時に計算され、常に最新です。他のテーブルと同様に、インサイトやサブスクリプションの基盤として使用できます。

これらのビューが存在する理由は 1 つだけです。ランナーティアのコストモデル、失敗フィンガープリントの作成方法、ジョブと実行のコミット帰属ルールなどのプロダクトコードを SQL に変換するためです。これらのロジックは独自に実装すると知らないうちにずれが生じるため、コードが変更されるたびにチームのビューに再反映されます。それ以外はすべて単なるテーブルデータであり、生テーブルに対する純粋な HogQL だけで常に十分です。エンジニアリング分析データ用の追加のウェアハウスビューは作成せず、3 つのビューにすでに反映されている内容を SQL で再導出しないでください。

プロダクトに表示されるもの	実際のデータの格納先	インサイトの基盤にできるか
PR リスト、マージ時間、CI ステータス、ワークフローの健全性	データウェアハウステーブル <prefix>github_pull_requests、<prefix>github_workflow_runs	はい（テーブルを使った SQL インサイト）
レビューと承認	<prefix>github_reviews	はい
チーム単位の PR 指標（作成者からチームへの帰属）	PR 作成者に対してセミ結合した <prefix>github_team_members	はい（チーム単位の集計のみ）
ジョブの所要時間、キュー時間、ランナーティア	<prefix>github_workflow_jobs	はい
CI コスト（ランナーティアの価格表）	engineering_analytics_job_costs ビュー	はい（ビューをクエリし、コストを再計算しない）
コミット帰属情報を含むジョブ単位の CI 履歴	engineering_analytics_ci_job_history ビュー	はい
グループ化（フィンガープリント化）された CI 失敗ログ行	engineering_analytics_ci_failures ビュー（保持期間が短い Logs プロダクトを参照）	はい（直近の短期間のみ）
PR または実行の間引き済み CI 失敗ログ	Logs プロダクト（service_name = 'github-ci-logs'）＋間引きロジック	いいえ（MCP ツールをアドホックに使用）
不安定なテストのランキング、失敗テストのトリアージ、チームの CI 健全性	CI トレーススパン＋プロダクトコード内のランキング／分類ロジック	いいえ（MCP ツールをアドホックに使用）
そのため、作業は明確に分けられます。
データウェアハウスに基づくメトリクス（生テーブルまたは3つのビュー）は、SQL のインサイトにします（その後、ダッシュボードを作成し、サブスクリプションを設定します）。
リクエスト時にプロダクトロジックで計算されるものはすべて MCP ツールに残し、必要に応じて AI サブスクリプションで定期的に配信します。

ステップ 1：チームのテーブルを確認する

データウェアハウスのテーブル名にはユーザーが選んだプレフィックスが付くため、名前をハードコードしないでください。 engineering-analytics-sources MCP ツールを呼び出します。接続されている GitHub ソースごとに、id、repo、prefix が返されます。 テーブル名は <prefix>github_pull_requests、<prefix>github_workflow_runs、<prefix>github_workflow_jobs、<prefix>github_reviews、および <prefix>github_teams / <prefix>github_team_members です。 プレフィックスが空の場合は、通常の github_* という名前になります。 複数のソースがある場合は、ユーザーがどのリポジトリを指しているのか確認してください。各ソースは1つのリポジトリに対応します。

3つの engineering_analytics_* ビューは、名前にプレフィックスがなく固定されているため、確認は不要です。チームのすべての GitHub ソースをまとめて対象にします。特定のリポジトリに絞り込むには、job_costs と ci_job_history では repo_owner / repo_name、ci_failures では repo を使います。ci_failures はソースごとのテーブルではなく Logs プロダクトを読み込みます。

ステップ 2：選別済みのセマンティクスを反映した HogQL を記述する

まず、3つのビューのいずれかで質問に答えられるか確認します。対象はコスト、ジョブごとの履歴とコミットへの帰属、フィンガープリント付きの失敗行です。答えられる場合は、ビューを直接クエリしてください。以下のルールは生テーブルを対象としています。

生テーブルには GitHub の JSON がそのまま取り込まれるため、単純な SELECT ではドメインルールが正しく反映されません。references/hogql-recipes.md の基本サブクエリをコピーしてください（プロダクト独自の選別済みビルダーと同じ内容です）。また、次のルールに従ってください。

• タイムスタンプは文字列です。 比較や差分の計算を行う前に、必ず parseDateTimeBestEffort(created_at) などで変換してください。
• ネストされた JSON は Nullable です。 JSONExtractArrayRaw / splitByChar の前に ifNull(...) で Nullable を解除してください。ClickHouse では Nullable の内部に Array を含められません。
• CI と PR の関連付けには PR 番号を使います（run の pull_requests 関連付け）。head SHA では決して関連付けないでください。PR スナップショットには現在の head のみが保存されるため、SHA で結合すると最新以外のすべての push が暗黙のうちに除外されます。head SHA を使うのは、PR の現在の CI ステータス（(head_sha, workflow_name) ごとの最新の run）を確認するときだけです。
• ボットの判定： author_handle LIKE '%[bot]' OR author_handle IN ('dependabot', 'github-actions', 'posthog-bot', 'renovate')。デフォルトでは、スループットやマージ所要時間のメトリクスからボットとドラフトを除外してください。
• 名前は実態に即したものにしてください。 merged_at - created_at は open_to_merge_seconds です（ドラフトの時間とレビューの時間が合算されています）。インサイトに「サイクルタイム」や「レビュー時間」という名前を付けないでください。
• 結論が古い場合があります。 run の同期では created_at をウォーターマークとして使用するため、完了が遅れた run では古い conclusion が表示されることがあります。status = 'completed' の行だけを対象に率を計算してください。
• レビューは pr_number で結合します。 github_reviews の state は APPROVED / CHANGES_REQUESTED / COMMENTED / DISMISSED です（保留中のドラフトは同期時に除外されます）。注入された pr_number を、PR テーブルの number に結合します。
• 作成者からチームへの帰属には、メンバーシップのセミ結合を使います。 github_team_members に対して author_handle IN (SELECT member_handle FROM …) で絞り込みます（チームのレシピを参照してください）。これはプロダクト独自のチーム別マージ傾向で使われている方法です。GitHub のチームには複数所属できる人がいるため、通常の JOIN ではチーム間でその人の PR が重複してカウントされます。また、クエリから出力するのはチーム単位の集計のみとし、メンバーごとの数値は出力しないでください。

保存する前に、execute-sql MCP ツール（または SQL エディター）でクエリをテストしてください。

ステップ 3：インサイトとして保存する

SQL インサイトで insight-create を使用します：

{
  "name": "Weekly PR open→merge time (hours)",
  "query": {
    "kind": "DataVisualizationNode",
    "source": { "kind": "HogQLQuery", "query": "<tested SQL>" }
  }
}

display（ChartDisplayType。例：ActionsLineGraph）と chartSettings（xAxis／yAxis 列）を指定すると、テーブルがチャートになります。 迷った場合は、いったん保存して、UI でユーザーに可視化方法を選んでもらい、返されたインサイト URL をリンクしてください。 SQL に相対期間を含めます（>= now() - INTERVAL 90 DAY）。 日付フィルターをハードコードすると、このタイルではダッシュボードの日付指定が適用されない点に注意してください。 複数のインサイトをまとめるには、dashboard-create を使用します。

ステップ 4：サブスクリプションを設定する

インサイト（またはダッシュボード）を保存したら、通常のサブスクリプション設定に進みます。subscriptions-create のペイロード、チャンネル、頻度、AI 要約のオプションについては、managing-subscriptions スキルに従ってください。

「X が起きたら通知して」（スケジュールではなく条件）の場合、アラートにはトレンドインサイトが必要なため、現時点では SQL インサイトにアラートを設定できません。 代わりにスケジュール済みサブスクリプションを提案するか、プロンプト種別の AI サブスクリプション内でしきい値をチェックしてください。

SQL で再構築してはいけないもの

不安定なテストのランキング、失敗テストの分類、チーム CI の健全性の集計、失敗ログの間引きは、インサイトからアクセスできないデータ（CI トレーススパン、未加工のログ本文）に基づくプロダクトロジックです。 手書きの SQL で再現すると、ダッシュボードの表示と気づかないうちにずれていきます。 これらについて定期レポートを作成する場合は、関連するエンジニアリング分析を各期間に読み取るようプロンプトで指示する、プロンプト種別の AI サブスクリプション（creating-ai-subscription スキルを参照）を作成してください。 または、MCP ツール（engineering-analytics-flaky-tests、engineering-analytics-broken-tests、engineering-analytics-team-ci-health、engineering-analytics-ci-failure-logs、engineering-analytics-run-failure-logs）を必要に応じて直接呼び出してください。

CI のコストはこの一覧に含まれません。プロダクトロジックが engineering_analytics_job_costs ビューに反映されているためです（プロダクト独自のモデルと照合するテストが行われ、モデルが変更されると再生成されます）。したがって、コストインサイトはビューに対する通常の SQL で作成できます。また、コスト MCP ツール（engineering-analytics-pr-cost、engineering-analytics-workflow-runner-costs）も同じ生成済み SELECT を読み取るため、数値は一致します。それでも、ランナーのラベルからドル建てコストを自分で再計算しないでください。

すべてのインサイトに引き継ぐ注意事項

今後読む人にも伝わるよう、インサイトの説明に以下を明記してください。 open_to_merge_seconds は大まかな値です（ドラフト期間とレビュー期間が統合されています）。 CI の結論は、実行の Webhook 処理が完了するまで遅れることがあります。 estimated_cost_usd が NULL の場合は、課金対象外または実行中を意味し、ゼロではありません。provider と completed_at を使って区別してください。 ci_failures は pytest のみを対象とし、失敗のみを数えるため、その件数は絶対的なシグナルであり、率ではありません。 ボットとドラフトを除外するかどうかも明記してください。 また、作成者別のリーダーボードや作成者間のランキングは決して作成しないでください。開発者ごとの監視は、プロダクトの明確な非目標です。 チーム単位の内訳が必要な場合は、github_team_members のメンバーシップによるセミジョインを通じてグループ化してください。