instrument-error-tracking

PostHog のエラートラッキングを追加する

このスキルを使用すると、アプリケーションの例外をキャプチャして監視するための PostHog エラートラッキングを追加できます。機能の実装後やプルリクエストのレビュー後に使用し、完全なスタックトレースとソースマップでエラーが追跡されるようにします。PostHog がまだインストールされていない場合、このスキルでは SDK の初期設定についても説明します。あらゆるプラットフォームや言語に対応しています。

対応プラットフォーム：React、Next.js、Web（JavaScript）、Node.js、Python、PHP、Ruby、Ruby on Rails、Go、Elixir、Angular、Svelte、Nuxt、React Native、Flutter、iOS、Android、Hono。

手順

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

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

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

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

• 既存の PostHog セットアップ（SDK の初期化、環境変数など）を確認します。PostHog がすでにインストールされ、初期化されている場合は、STEP 4 に進みます。

STEP 2: インストルメンテーションについて調査します。（PostHog がすでにセットアップされている場合はスキップします。） 2.1. 特定したプラットフォームに一致する以下のリファレンスファイルを探してください。このファイルは、SDK の初期化、例外の自動キャプチャ、フレームワーク固有のエラートラッキングパターンの正式な参照元です。すぐに読み込んでください。 2.2. 一致するリファレンスがない場合は、一般知識とウェブ検索を利用してください。主な検索先として posthog.com/docs を使用してください。

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

• 特定したプラットフォーム用の PostHog SDK パッケージを追加します。package.json を手動で編集せず、パッケージマネージャーのインストールコマンドを使用してください。
• フレームワークのリファレンスに従って、初期化する場所と方法を決めてください。

STEP 4: 例外の自動キャプチャを有効にします。

• プラットフォームのリファレンスに従って、例外の自動キャプチャを有効にしてください。追加のコードなしで、未処理の例外が自動的にキャプチャされます。

STEP 5: 手動でエラーをキャプチャします。

• エラー境界、catch ブロック、エラーを明示的にキャプチャすべき重要なユーザーフローを特定します。
• 該当箇所に posthog.captureException() またはプラットフォームに相当する機能を追加してください。
• 既存のエラー処理の基本的なアーキテクチャは変更しないでください。追加は最小限にとどめ、対象を絞ってください。
• ファイルに書き込む直前に、必ずそのファイルを読み込んでください。

STEP 6: ソースマップをアップロードします（フロントエンド／モバイルのみ）。

• スタックトレースが圧縮されたバンドルではなく、元のソースコードに対応するよう、ソースマップのアップロードを設定してください。
• アップロード設定（ビルドプラグイン、CI スクリプトなど）については、プラットフォーム固有のリファレンスに従ってください。

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

• プロジェクトに 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 8: 検証して整理します。

• プロジェクトにエラーがないか確認します。package.json に型チェックまたはビルドのスクリプトがあるか確認してください。
• 作成したコンポーネントが実際に使用されていることを確認してください。
• package.json にリントまたは Prettier のようなスクリプトがある場合は、今回のセッションで編集または作成したファイルに対してのみ実行してください。プロジェクト全体を対象にフォーマットやリントを実行してはいけません。

リファレンスファイル

• references/react.md - React のエラートラッキングのインストール
• references/web.md - Web のエラートラッキングのインストール
• references/nextjs.md - Next.js のエラートラッキングのインストール
• references/node.md - Node.js のエラートラッキングのインストール
• references/python.md - Python のエラートラッキングのインストール
• references/django.md - Django
• references/flask.md - Flask
• references/php.md - Php のエラートラッキングのインストール
• references/laravel.md - Laravel
• references/ruby.md - Ruby のエラートラッキングのインストール
• references/ruby-on-rails.md - Ruby on rails のエラートラッキングのインストール
• references/ruby-on-rails.md - Ruby on rails
• references/go.md - Go のエラートラッキングのインストール
• references/dotnet.md - .net のエラートラッキングのインストール
• references/dotnet.md - .net
• references/elixir.md - Elixir のエラートラッキングのインストール
• references/angular.md - Angular のエラートラッキングのインストール
• references/svelte.md - Sveltekit のエラートラッキングのインストール
• references/nuxt-3-7.md - Nuxt のエラートラッキングのインストール（v3.7 以降）
• references/nuxt-3-6.md - Nuxt のエラートラッキングのインストール（v3.6 以前）
• references/react-native.md - React native のエラートラッキングのインストール
• references/flutter.md - Flutter のエラートラッキングのインストール
• references/ios.md - Ios のエラートラッキングのインストール
• references/android.md - Android のエラートラッキングのインストール
• references/hono.md - Hono のエラートラッキングのインストール
• references/fingerprints.md - フィンガープリント
• references/alerts.md - エラートラッキングのアラートを送信する
• references/monitoring.md - 問題を監視して検索する
• references/assigning-issues.md - チームメイトに問題を割り当てる
• references/upload-source-maps.md - ソースマップをアップロードする
• references/COMMANDMENTS.md - インテグレーションが従う必要のあるフレームワーク固有のルール

各プラットフォームのリファレンスには、SDK 固有のインストール方法と手動キャプチャのパターンが記載されています。ユーザーのスタックに合ったものを確認してください。

主な原則

• 環境変数：PostHog のキーには必ず環境変数を使用してください。ハードコードしないでください。
• 変更は最小限に：既存のエラー処理にエラートラッキングを追加してください。既存のコードを置き換えたり、構成し直したりしないでください。
• まずは自動キャプチャ：手動キャプチャを追加する前に、例外の自動キャプチャを有効にしてください。
• ソースマップ：スタックトレースが縮小されたバンドルではなく、元のソースコードに対応するよう、ソースマップをアップロードしてください。
• 境界では手動キャプチャ：グローバルハンドラーに伝播しないエラーについては、エラー境界や catch ブロックで captureException() を使用してください。