omnibus-instrument-product-analytics

PostHog のプロダクト分析イベントを追加する

このスキルを使って、新規または変更したコードに、ユーザーの重要なアクションを追跡するプロダクト分析イベント（capture 呼び出し）を追加します。機能の実装後や PR のレビュー後に使用すると、重要なユーザー行動が記録されていることを確認できます。PostHog がまだインストールされていない場合は、初期 SDK セットアップについても説明します。あらゆるフレームワークや言語に対応しています。

対応フレームワーク：Next.js、React Router、Nuxt、Vue、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、Ruby on Rails、Android、iOS、React Native、Expo など。

手順

以下の手順を順番どおりに実行してください。

STEP 1: コードベースを分析し、プラットフォームを特定します。

• 依存関係ファイル（package.json、requirements.txt、Gemfile、composer.json、go.mod など）を確認し、フレームワークと言語を特定します。
• ロックファイル（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb）を確認し、パッケージマネージャーを特定します。
• 既存の PostHog のセットアップを確認します。PostHog がすでにインストールされ、初期化されている場合は、STEP 5 に進みます。

STEP 2: 統合方法を調査します。（PostHog がすでにセットアップされている場合はスキップします。） 2.1. 特定したフレームワークに一致する以下のリファレンスファイルを見つけます。このファイルは、SDK の初期化、プロバイダーのセットアップ、イベントキャプチャのパターンに関する信頼できる情報源です。今すぐ読みます。 2.2. 一致するリファレンスがない場合は、一般的な知識とウェブ検索を利用します。主な検索先として posthog.com/docs を使用します。

STEP 3: PostHog SDK をインストールします。（PostHog がすでにセットアップされている場合はスキップします。）

• 特定したプラットフォーム用の PostHog SDK パッケージを追加します。package.json を手動で編集せず、パッケージマネージャーのインストールコマンドを使用します。
• パッケージのインストールは必ずバックグラウンドタスクとして実行します。完了を待たず、インストールを開始したらすぐにほかの作業を進めてください。

STEP 4: PostHog を初期化します。（PostHog がすでにセットアップされている場合はスキップします。）

• 初期化する場所と方法は、フレームワークのリファレンスに従ってください。これはフレームワークによって大きく異なります（例：Next.js 15.3+ の instrumentation-client.ts、Django の AppConfig.ready()、Flask の create_app()）。

STEP 5: イベント追跡を計画します。

• プロジェクトのファイル一覧から、イベント追跡にビジネス上の価値がありそうなファイルを 10～15 個選びます。特に、コンバージョンイベントとチャーンイベントを重視してください。
• ユーザーの識別に使えるログイン関連のファイルと、エラーハンドリング関連のファイルも探します。
• 既存の posthog.capture() コードがないか確認します。イベント名の形式を記録してください。既存のイベントを重複させず、補完するイベントを追加します。
• ページビューではなく、アクションを追跡します（ページビューは自動的にキャプチャできます）。コンバージョンファネルの最上部における「閲覧」タイプのイベントは例外として追加できます。
• プロジェクトに計測可能なサーバーサイドコード（API ルート、サーバーアクション、Webhook ハンドラー、決済／チェックアウト完了処理、認証エンドポイント）が含まれる場合は、サーバーサイドイベントが必須です。

STEP 6: イベントキャプチャを実装します。

• 計画した各イベントについて、役立つプロパティを指定して posthog.capture() 呼び出しを追加します。
• 既存ファイルにほかのツールやサービスとの統合コードがある場合、そのコードを上書きしたり削除したりしないでください。PostHog のコードはその下に配置します。
• 既存ファイルの基本的なアーキテクチャは変更しないでください。追加は最小限かつ対象を絞って行います。
• ファイルを書き込む前に、必ずそのファイルを読みます。

STEP 7: ユーザーを識別します。

• ログイン時とサインアップ時に、クライアント側で PostHog の identify() 呼び出しを追加します。送信時にログインフォームとサインアップフォームの内容を使ってユーザーを識別します。
• フロントエンドとバックエンドの両方がある場合は、クライアント側のセッションと distinct ID を X-POSTHOG-DISTINCT-ID および X-POSTHOG-SESSION-ID ヘッダーでサーバーサイドコードに渡します。サーバー側では、イベントに一致する distinct ID が含まれるようにします。

STEP 8: エラー追跡を追加します。

• 関連するファイル、特に重要なユーザーフローや API 境界で、PostHog の例外キャプチャによるエラー追跡を追加します。

STEP 9: 環境変数を設定します。

• env-file-tools MCP サーバーが接続されている場合は、check_env_keys を使って既存のキーを確認し、続いて set_env_values を使って PostHog の API キーとホストを作成または更新します。
• ハードコードする代わりに、コード内でこれらの環境変数を参照します。

STEP 10: 検証とクリーンアップを行います。

• プロジェクトにエラーがないか確認します。package.json 内の型チェック用またはビルド用スクリプトを探します。
• 作成したコンポーネントが実際に使われていることを確認します。
• package.json にリンターや Prettier のようなスクリプトがあれば実行します。

リファレンスファイル

• references/EXAMPLE-next-app-router.md - next-app-router のサンプルプロジェクトコード
• references/EXAMPLE-next-pages-router.md - next-pages-router のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-6.md - react-react-router-6 のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-framework.md - react-react-router-7-framework のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-data.md - react-react-router-7-data のサンプルプロジェクトコード
• references/EXAMPLE-react-react-router-7-declarative.md - react-react-router-7-declarative のサンプルプロジェクトコード
• references/EXAMPLE-nuxt-3.6.md - nuxt-3.6 のサンプルプロジェクトコード
• references/EXAMPLE-nuxt-4.md - nuxt-4 のサンプルプロジェクトコード
• references/EXAMPLE-vue-3.md - vue-3 のサンプルプロジェクトコード
• references/EXAMPLE-react-tanstack-router-file-based.md - react-tanstack-router-file-based のサンプルプロジェクトコード
• references/EXAMPLE-react-tanstack-router-code-based.md - react-tanstack-router-code-based のサンプルプロジェクトコード
• references/EXAMPLE-tanstack-start.md - tanstack-start のサンプルプロジェクトコード
• references/EXAMPLE-sveltekit.md - sveltekit のサンプルプロジェクトコード
• references/EXAMPLE-astro-static.md - astro-static のサンプルプロジェクトコード
• references/EXAMPLE-astro-view-transitions.md - astro-view-transitions のサンプルプロジェクトコード
• references/EXAMPLE-astro-ssr.md - astro-ssr のサンプルプロジェクトコード
• references/EXAMPLE-astro-hybrid.md - astro-hybrid のサンプルプロジェクトコード
• references/EXAMPLE-angular.md - angular のサンプルプロジェクトコード
• references/EXAMPLE-django.md - django のサンプルプロジェクトコード
• references/EXAMPLE-flask.md - flask のサンプルプロジェクトコード
• references/EXAMPLE-fastapi.md - fastapi のサンプルプロジェクトコード
• references/EXAMPLE-python.md - python のサンプルプロジェクトコード
• references/EXAMPLE-laravel.md - laravel のサンプルプロジェクトコード
• references/EXAMPLE-ruby-on-rails.md - ruby-on-rails のサンプルプロジェクトコード
• references/EXAMPLE-ruby.md - ruby のサンプルプロジェクトコード
• references/EXAMPLE-android.md - android のサンプルプロジェクトコード
• references/EXAMPLE-swift.md - swift のサンプルプロジェクトコード
• references/EXAMPLE-react-native.md - react-native のサンプルプロジェクトコード
• references/EXAMPLE-expo.md - expo のサンプルプロジェクトコード
• references/next-js.md - Next.js - ドキュメント
• references/react-router-v6.md - React router v6 - ドキュメント
• references/react-router-v7-framework-mode.md - React router v7 framework mode (remix v3) - ドキュメント
• references/react-router-v7-data-mode.md - React router v7 data mode - ドキュメント
• references/react-router-v7-declarative-mode.md - React router v7 declarative mode - ドキュメント
• references/nuxt-js-3-6.md - Nuxt.js (v3.0 to v3.6) - ドキュメント
• references/nuxt-js.md - Nuxt.js - ドキュメント
• references/vue-js.md - Vue.js - ドキュメント
• references/tanstack-start.md - Tanstack start - ドキュメント
• references/svelte.md - Svelte - ドキュメント
• references/astro.md - Astro - ドキュメント
• references/angular.md - Angular - ドキュメント
• references/django.md - Django - ドキュメント
• references/flask.md - Flask - ドキュメント
• references/python.md - Python - ドキュメント
• references/posthog-python.md - PostHog python SDK
• references/laravel.md - Laravel - ドキュメント
• references/ruby-on-rails.md - Ruby on rails - ドキュメント
• references/ruby.md - Ruby - ドキュメント
• references/android.md - Android - ドキュメント
• references/ios.md - Ios - ドキュメント
• references/react-native.md - React native - ドキュメント
• references/identify-users.md - ユーザーの識別 - ドキュメント

各フレームワークのリファレンスには、SDK固有のインストール、初期化、使用パターンが記載されています。ユーザーのスタックに一致するものを見つけてください。

重要な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。コードに直接記述しないでください。
• 変更は最小限に：既存の統合に PostHog のコードを追加してください。既存のコードを置き換えたり、再構成したりしないでください。
• ドキュメントに準拠：フレームワークのリファレンスに記載された初期化とキャプチャのパターンに正確に従ってください。