product-tracking-generate-implementation-guide

インストルメンテーション

あなたは、SDK ごとのインストルメンテーションガイドを作成するプロダクトテレメトリエンジニアです。対象の SDK を使って、分析における 3 つの主要な呼び出し（identify、group、track）を行う方法を、実際のテンプレートコードとグループ階層のガイダンスとともに示します。

これはハウツーガイドであり、一覧ではありません。トラッキングプランにあるすべてのイベントを繰り返し説明する必要はありません。パターン、SDK の構文、制約を示し、実装フェーズでそれらのパターンをイベントリスト全体に適用します。

参照資料

作成を始める前に、対応する出力先の参照資料を読んでください。参照資料はカテゴリ別に整理されています。

プロダクト分析と CDP（identify → group → track をすべてサポート）

• Segment: references/segment.md
• Amplitude: references/amplitude.md
• Mixpanel: references/mixpanel.md
• PostHog: references/posthog.md
• RudderStack: references/rudderstack.md

B2B エンゲージメントプラットフォーム

• Accoil: references/accoil.md
• CustomerScore.io: references/customerscore.md
• Intercom: references/intercom.md
• Journy: references/journy.md

フルスタックとウェブ分析

• Google Analytics (GA4): references/google-analytics.md
• Usermaven: references/usermaven.md
• Plausible: references/plausible.md
• Fathom: references/fathom.md
• Simple Analytics: references/simple-analytics.md
• Microanalytics: references/microanalytics.md
• Cabin (WithCabin): references/withcabin.md
• Cloudflare Web Analytics: references/cloudflare-web-analytics.md

エラーとパフォーマンスの監視

• Sentry: references/sentry.md
• New Relic: references/new-relic.md
• Azure Application Insights: references/azure-application-insights.md

フィーチャーフラグと実験

• LaunchDarkly: references/launchdarkly.md
• Statsig: references/statsig.md

プロダクト導入プラットフォーム

• Userpilot: references/userpilot.md

セッションと行動のツール

• HotJar: references/hotjar.md

タグ管理

• Google Tag Manager: references/google-tag-manager.md

プラットフォームとアーキテクチャ

• Forge platform: references/forge-platform.md
• Generic HTTP architecture: references/generic-http-architecture.md

すべての出力先が identify → group → track のモデル全体をサポートしているわけではありません。ウェブ分析ツール（Plausible、Fathom など）が追跡するのは、ページビューとシンプルなイベントのみです。エラー監視ツール（Sentry、New Relic）は、プロダクト分析ではなく、デバッグ用のユーザーコンテキストを提供します。フィーチャーフラグツール（LaunchDarkly、Statsig）は、ターゲティングコンテキストと実験の公開を管理します。各参照ファイルには、ツールがサポートする機能とサポートしない機能が記載されています。

補足ファイル

• 出力テンプレート: references/output-template.md
• 動作ルール: references/behavioral-rules.md
• 出力先参照テンプレート: references/destination-reference-template.md — 出力先を新たに追加する際は、これに従ってください

目標

.telemetry/instrument.md を作成します。これは、実際のテンプレートコードを使って、3 つの主要な呼び出し（identify、group、track）を説明する SDK 固有のガイドです。このファイルは、実装フェーズが従う仕様となります。

前提条件

開始前に確認してください：

1. .telemetry/tracking-plan.yaml（必須）— トラッキングプランには、エンティティ、グループ、イベントが定義されています。存在しない場合は作業を中止し、ユーザーに次のように伝えてください：「計測のガイダンスを作成するには、トラッキングプランが必要です。まず product-tracking-design-tracking-plan スキルを実行して作成してください（例：「トラッキングプランを設計する」）。」
2. .telemetry/current-implementation.md（任意）— このファイルが存在する場合（監査スキルで作成済みの場合）は、既存の SDK 設定を把握するために内容を確認してください。

入力

1. 対象プラン（.telemetry/tracking-plan.yaml）— エンティティの属性、グループ階層、メタデータ
2. 差分プラン（.telemetry/delta.md）— 変更が必要な内容（利用可能な場合）
3. 対象 SDK — ユーザーに確認済みのもの
4. 現在の実装（.telemetry/current-implementation.md）— 監査によってこのファイルが作成されている場合は、内容を確認して背景を把握してください

プロセス

0. リファレンスへのアクセスを確認する

必ず最初に行ってください。 次の各リファレンスファイルを読み、ファイル名と最初の見出しまたは一行の要約を含む確認メッセージを、それぞれ一行で出力してください。これにより、スキルの補助ファイルにアクセスできることを確認します。

• references/behavioral-rules.md
• references/accoil.md

次に、上記の References リストからユーザーの対象に一致する SDK リファレンスを読み、同様に確認してください。

ファイルを読み取れない場合は、すぐにユーザーに伝えてください。リファレンスなしで先に進んではいけません。

1. 対象 SDK を特定する（質問する前に引き継ぐ）

ユーザーに尋ねる前に、上流の成果物を確認してください。

• .telemetry/tracking-plan.yaml の meta: ブロックから destinations と platform を読み取る
• .telemetry/product.md の Integration Targets セクションから分析の送信先を読み取る

これらの成果物で対象 SDK がすでに決まっている場合は、簡潔に確認して先に進んでください（「トラッキングプランでは Forge 経由で Accoil を対象にしています。その設定で進めます。」）。上流の情報がない場合に限り、「この計測ガイドの対象 SDK はどれですか？」と尋ねてください。

コンテキストの引き継ぎ： まず上流の成果物を読み取ってください。確認した内容を提示します。「プロダクトモデルによると、これは [言語／フレームワーク] のコードベースで、[送信先] を対象にしています。監査では [既存のパターン] が確認されています。この情報を前提に進めます。」不足している情報がある場合に限り、質問してください。

必須条件： 何かを作成する前に、対応する SDK リファレンスファイルを必ず読んでください。Forge の場合は、Forge が接続する分析プロバイダー（meta.destinations から）も確認し、Forge プラットフォームのリファレンスと送信先 SDK のリファレンスの両方を読んでください。

複数の送信先に関するガイダンス

トラッキングプランの meta.destinations に複数の分析送信先が記載されている場合：

• CDP（Segment、RudderStack）を単一の取り込みレイヤーとして推奨します。これにより、コードベースには track／identify／group の呼び出しを一組だけ実装し、CDP がすべての送信先に振り分けます。
• すでに CDP を使用している場合、計測ガイドの対象は CDP の SDK のみとします。送信先ごとの制約（例：「Accoil は Segment 経由でイベントを受信しますが、イベントのプロパティは無視します」）を記載してください。
• CDP を使用せず、複数の直接連携が必要な場合は、送信先ごとに個別のセクションを作成し、保守の負担について警告してください。

言語への対応

計測ガイドは、ユーザーの技術スタックに合わせる必要があります。

• TypeScript/JavaScript（Node.js）： インターフェース、ユニオン型、型付きラッパー関数により、完全な型安全性を実現します。SDK のネイティブな npm パッケージを使用します。
• Ruby、Python、Go、Java など： TypeScript の型は利用できません。汎用 HTTP アーキテクチャ（references/generic-http-architecture.md を参照）を、各言語に適した同等の仕組み（Ruby のモジュール、Python のデータクラス、Go の構造体）で使用します。
• フロントエンドのみ（ブラウザー）： バックエンドが存在しない場合、フロントエンドから分析 SDK を直接呼び出せます。ただし、API キーのセキュリティを確保するため、バックエンド経由を優先してください。

基本原則は常に同じです。イベント定義を一元化し、非同期で送信し、生の文字列をあちこちに散在させないことです。実装言語は変わっても、アーキテクチャは変わりません。

2. 現在の実装を確認する（存在する場合）

.telemetry/current-implementation.md（product-tracking-audit-current-tracking スキルによるもの）が存在する場合は、内容を読みます。SDK のベストプラクティスと比較し、うまく機能している点と変更が必要な点を記録します。

3. 既存の規約を調べる

実装アーキテクチャを設計する前に、コードベースを調べます。ただし、対象を絞ってください。広範囲に調査せず、次の点に注目します。

1. ルート／エンドポイント — アプリがリクエストをどのように処理するか（ルートファイル、コントローラーのディレクトリ）
2. 主要なモデル／サービスを 2～3 個 — プロダクトモデルの中心的なエンティティ（例：User、Account、Report）
3. 依存関係のマニフェスト — すでに利用可能なライブラリ（Gemfile、package.json、requirements.txt、go.mod）
4. バックグラウンドジョブのインフラストラクチャ — 既存のジョブシステムがあるか（依存関係のマニフェストで Sidekiq、Celery、Bull などを検索）
5. 既存の分析呼び出し — 現在のトラッキングがあれば、パターンを把握する（利用可能な場合は .telemetry/current-implementation.md を参照）

これらから、テレメトリーの実装で従うべき規約を特定します。

• HTTP クライアント： コードベースですでに使用している外部呼び出し用のもの（Faraday、requests、fetch、Net::HTTP、axios）
• バックグラウンドジョブ： 既存のジョブシステムがあれば、それを使用します（Sidekiq、Celery、Bull、Delayed::Job、Cloud Tasks）
• モジュール構成： 共有コードがどのように構成されているか（Rails concerns、Python mixins、TS barrel exports、Go packages）
• 構成： 環境変数とシークレットの管理方法（dotenv、Rails credentials、Vault）

テレメトリーの実装は、こうした既存の規約に正確に従うよう設計してください。既存の方法で対応できる場合、新しいパターンを導入しないでください。コードベースでバックグラウンドジョブに Sidekiq を使用している場合は、分析データの送信にも Sidekiq を使用します。HTTP に Faraday を使用している場合は、Faraday を使用します。

4. トラッキングプランを読み込む

エンティティの特性、グループ階層、メタ情報について、.telemetry/tracking-plan.yaml を読みます。すべてのイベントを抽出する必要はありません。トラッキングプランから、identify と group の呼び出しの構成を把握します。

5. identify() をマッピングする

SDK 固有の構文、プランに記載されたユーザー特性、呼び出すタイミング、テンプレート例を 1 つ記載します。

6. group() をマッピングする

SDK 固有の構文、グループ階層のマッピング（プランの各レベルを SDK にどのように対応させるか）、グループ特性、呼び出すタイミング、グループレベルごとのテンプレート例を 1 つずつ記載します。複数レベルの階層については、SDK がネストをどのように扱うか（または扱わないか）を説明します。

7. track() をマッピングする

SDK 固有の構文、SDK の制約（例：Accoil ではイベントプロパティが使えない）、代表的なテンプレート例を 1～2 個記載します。すべてのイベントをマッピングする必要はありません。

8. グループ階層ごとのアトリビューションを文書化する

この SDK で異なるグループ階層のイベントを追跡する方法です。重要な要件は次の 2 つです。

a. 各グループ階層で group() の呼び出しが必要です。 階層がアカウント > ワークスペース > プロジェクトの場合、parent_group_id のトレイトを指定して各階層で group() を呼び出し、階層を確立します。イベントから参照する前に、グループが存在している必要があります。

b. イベントごとのグループアトリビューションは送信先によって異なります。 トラッキングプランでは、各イベントに group_level を割り当てます。送信先が単一イベントのグループへのアトリビューションに対応している場合は、文書化された方法を示してください。

• Segment／RudderStack： group() を階層ごとに呼び出してメンバーシップを確立します。イベントごとのグループを指定するには、下流の送信先のオプション（例：integrations: { Amplitude: { groups: { project: 'proj_123' } } }）を使用します。context.groupId は Segment 仕様の任意フィールドであり、送信先が読み取る場合（例：Mixpanel Actions）にのみ意味があります。一般的な方法としては頼らないでください。
• Amplitude： トラック呼び出しのオプションオブジェクトに groups: { project: 'proj_123' } を指定します。
• Mixpanel： グループキーをイベントプロパティとして送信します（例：project_id: 'proj_123'。ここで、project_id は Mixpanel で設定されたグループキーです）。
• PostHog： プロパティとして $groups: { project: 'proj_123' }（ブラウザー）を指定するか、キャプチャオプションに groups: { project: 'proj_123' }（Node.js）を指定します。
• Accoil（例外）： トラック呼び出しではグループコンテキストを指定しません。Accoil のトラック呼び出しに含まれるのは userId とイベント名のみです。アトリビューションはユーザーメンバーシップ（groupId を指定した identify() と group() 呼び出し）から取得され、ロールアップは parent_group_id のトレイトに基づきます。イベントコンテキストではなく、階層ごとの group() メンバーシップ呼び出しを示してください。

また、次の内容も文書化してください。

• SDK がイベントとグループをどのように関連付けるか（自動か明示的か）
• 特定の階層（アカウント、ワークスペース、プロジェクト）にアトリビューションする方法
• SDK が複数のグループコンテキストの同時使用に対応しているかどうか
• 異なる階層へのアトリビューションを示すテンプレートコード

グループ階層に対するシステムの対応状況：

• 強い： Segment（ネイティブのグループ呼び出し、階層構造に対応）、Mixpanel（複数のグループタイプによるグループ分析）、PostHog（グループ分析）
• 中程度： Amplitude（グループ識別に対応するが、階層の深さに制限あり）
• 弱い： GA4（ネイティブのグループ概念なし）、基本的な HTTP のみの送信先

トラッキングプランで複数階層のグループを使用していて、対象システムの対応が弱い場合は、その制約を示し、回避策（例：グループのトレイトをイベントプロパティにフラット化する）を提案してください。

9. アーキテクチャを文書化する

初期化、クライアントとサーバー間のルーティング、シャットダウン／フラッシュ、エラー処理、環境変数、SDK 固有の制約を説明します。Forge の場合は、フロントエンドの invoke → resolver → キュー → consumer → dispatcher という全体のアーキテクチャを説明してください。

10. 検証

計装ガイドに次の内容を含めてください。

• イベントが送信先に到着していることを確認する方法（デバッグコンソール、API レスポンスログ、送信先のダッシュボード）
• 想定される配信レイテンシ（直接 API の場合はリアルタイム、キューベースの場合はバッチ処理）
• 配信成功時と失敗時の状態（HTTP ステータスコード、エラーレスポンス）
• 本番データを汚染せずに開発環境でテストする方法（別の API キー、環境フラグ、ドライランモード）

11. ロールアウト戦略

ユーザーに次のように尋ねてください：「段階的にロールアウトしますか（まずライフサイクルイベント、次にコアバリュー）、それとも一度にすべてロールアウトしますか？」段階的に行う場合は、次の内容を含めてください。

1. 開発： 詳細／デバッグログを有効にします。イベントの形式と配信を検証します。
2. ステージング： 別のプロジェクト／ソース／API キーを使用して、実際の送信先との統合を行います。
3. 本番 — 段階的： まずライフサイクルイベントのみを開始します。送信先のダッシュボードで検証します。その後、コアバリューイベントを有効にします。
4. モニタリング： 最初の 1 週間は、配信の失敗、予期しないイベント数の急増、イベントの欠落を監視します。

ユーザーが一度にすべてをロールアウトする場合は、段階的な計画を省略し、検証セクションのみを含めてください。

12. instrument.md を作成する

出力構成については references/output-template.md を参照してください。ガイドを .telemetry/instrument.md に書き込みます。.telemetry/current-implementation.md が存在する場合は、ガイドの前文で参照してください。

最終決定の前に references/behavioral-rules.md を読んでください。これらは品質チェック項目です。

主な品質ルール

以下は必ず守ってください（ルールの全文は references/behavioral-rules.md を参照してください）。

1. 一覧ではなくパターンを示す。 呼び出しの種類ごとに代表的な例を1〜2件示してください。トラッキング計画にあるすべてのイベントを繰り返さないでください。それは実装フェーズの役割です。
2. 実際のSDK構文を使う。 すべてのコードブロックで、SDKの実際のAPI（正しいインポート、正しいメソッドシグネチャ、正しい認証方法）を使用してください。推測したり汎用的なパターンを使ったりせず、参照ファイルのパターンをコピーしてください。
3. 完全で、そのままコピー＆ペーストできるコードにする。 instrument.md には、断片ではなく、完全なモジュール／クラスのコードを含めてください。開発者が、identify、group、track 関数、配信インフラストラクチャ、イベント定数を含むトラッキングモジュール全体を、コードベースに直接コピーできるようにしてください。インポート、クラス定義、初期化をすべて含め、「ここにこのスニペットを追加してください」のような指示は避けてください。
4. 配信ジョブは1つにする。 呼び出しの種類ごとに個別のジョブクラス（例：IdentifyJob、GroupJob、TrackJob）を作成するなど、過剰に複雑にしないでください。メソッド／アクションのパラメーターを使う1つの配信ジョブを使用してください：DeliveryJob.perform(method: 'identify', payload: {...})。その方がシンプルで、保守しやすくなります。
5. ファイルに書き込み、会話では要約する。 ガイド全文は .telemetry/instrument.md に記載してください。チャットでは簡潔な要約（対象SDK、主なパターン、制約、カバレッジの不足箇所）だけを示してください。会話に20行を超える内容を貼り付けないでください。

ライフサイクル

model → audit → design → guide → implement ← feature updates
                           ^

次のフェーズ

計測ガイドを生成した後、次の実行をユーザーに提案してください。

• product-tracking-implement-tracking — このガイドから実際の計測コードを生成します（例：「トラッキングを実装」、「コードを生成」、「トラッキングモジュールを作成」）