instrument-product-analytics

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

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

サポート対象のフレームワークと言語：Next.js、React Router、Nuxt、Vue、TanStack Start、SvelteKit、Astro、Angular、Django、Flask、FastAPI、Laravel、PHP、Ruby on Rails、Go、Elixir、Android、iOS、Flutter、React Native、Expo など。

手順

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

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

依存関係ファイル（package.json、pubspec.yaml、Podfile、Package.swift、requirements.txt、Gemfile、composer.json、go.mod、mix.exs など）を探して、フレームワークと言語を特定します。

ロックファイル（pnpm-lock.yaml、package-lock.json、yarn.lock、bun.lockb、go.sum、pubspec.lock、Podfile.lock、Package.resolved、mix.lock）を探して、パッケージマネージャーを特定します。

• 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: 環境変数を設定します。
• プロジェクトに PostHog の環境変数がすでに設定されているか（例：.env、.env.local、またはフレームワーク固有の環境変数ファイル）を確認します。有効な値がすでに存在する場合は、この手順をスキップします。
• PostHog プロジェクトトークンがない場合は、PostHog MCP サーバーの projects-get ツールを使って、プロジェクトの api_token を取得します。複数のプロジェクトが返された場合は、使用するプロジェクトをユーザーに尋ねます。MCP サーバーに接続されていない、または認証されていない場合は、代わりに PostHog プロジェクトトークンをユーザーに尋ねます。
• PostHog ホスト URL については、projects-get の MCP レスポンスで region フィールドを確認します。US は https://us.i.posthog.com、EU は https://eu.i.posthog.com に対応します。MCP レスポンスにも既存のプロジェクト設定にもリージョンがない場合は、「PostHog US Cloud と EU Cloud のどちらを利用していますか？」とユーザーに尋ねます。US Cloud と決めつけないでください。
• フレームワークの命名規則に従って、これらの値を適切な環境変数ファイルに書き込みます。
• ハードコードする代わりに、コード内でこれらの環境変数を参照します。

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-php.md - php のサンプルプロジェクトコード
• 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 フレームワークモード（remix v3）
• references/react-router-v7-data-mode.md - React router v7 データモード
• references/react-router-v7-declarative-mode.md - React router v7 宣言型モード
• references/nuxt-js-3-6.md - Nuxt.js（v3.0 から 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/dotnet.md - .net
• references/elixir.md - Elixir
• references/go.md - Go
• references/laravel.md - Laravel
• references/php.md - Php
• references/ruby-on-rails.md - Ruby on rails
• references/ruby.md - Ruby
• references/android.md - Android
• references/ios.md - Ios
• references/usage.md - Ios SDK の使用方法
• references/configuration.md - Ios SDK の設定
• references/flutter.md - Flutter
• references/react-native.md - React native
• references/identify-users.md - ユーザーの識別
• references/COMMANDMENTS.md - 統合が従う必要のあるフレームワーク固有のルール

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

重要な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 変更は最小限に：既存の連携機能に加えて PostHog のコードを追加してください。既存のコードを置き換えたり、構成し直したりしないでください。
• ドキュメントに従う：フレームワークリファレンスに記載された初期化とイベント取得のパターンに正確に従ってください。