product-tracking-implement-tracking

実装

プロダクトテレメトリエンジニアとして、差分プランを実行します。現在のトラッキングと目標プランの差分を、実際に動作するインストルメンテーションコードに変換します。

リファレンス一覧

ファイル	内容	読むタイミング
references/naming-conventions.md	イベント／プロパティの命名規則	生成コードが規約に準拠していることを確認するとき
references/sdk-comparison.md	SDK の相違点の比較	SDK のトレードオフを把握するとき
references/implementation-architecture.md	一元化された定義、キューベースの配信	インストルメンテーションコードを構成するとき
references/tracking-plan-location.md	コードベース内で型を配置する場所	出力先を決めるとき

目標

差分プラン（または目標プラン全体）を実装可能なコードに変換します。具体的には、以下のとおりです。

1. トラッキングプランに一致する型付きイベント定義
2. 各イベントの SDK ラッパー関数
3. ID 管理（identify/group）
4. 検証ヘルパー（任意、開発時用）
5. 既存のコードベースへの統合ガイダンス

出力：トラッキングコードと、実装内容を反映して更新したトラッキングプラン

前提条件

コンテキストの継承： 質問する前に .telemetry/instrument.md と .telemetry/product.md を読みます。インストルメンテーションガイドには、SDK のパターン、アーキテクチャの決定事項、フックの配置場所が記載されています。プロダクトモデルには、技術スタックと言語が記載されています。見つかった内容を提示します：「インストルメンテーションガイドでは、[言語／フレームワーク]のコードベースで[アーキテクチャパターン]を用いる[SDK]が対象です。この内容に沿って進めます。」不足している情報がある場合に限り、質問してください。

開始前に確認する項目：

1. .telemetry/instrument.md（必須）— SDK 固有のインストルメンテーションガイドです。存在しない場合は作業を中止し、ユーザーに次のように伝えます：「コードを生成するには、インストルメンテーションガイドが必要です。まず product-tracking-generate-implementation-guide スキルを実行してガイドを作成してください（例：「インストルメンテーションガイドを作成」）。」
2. .telemetry/tracking-plan.yaml（必須）— 目標トラッキングプランです。存在しない場合は作業を中止し、ユーザーに次のように伝えます：「型と関数を生成するには、トラッキングプランが必要です。まず product-tracking-design-tracking-plan スキルを実行して作成してください（例：「トラッキングプランを設計」）。」
3. .telemetry/delta.md（推奨）— 存在する場合は、差分の実装を優先します。目標プランのみが存在する場合は、プラン全体を実装します。

入力

1. インストルメンテーションガイド（.telemetry/instrument.md）— SDK 固有のパターン、テンプレートコード、API エンドポイント
2. 目標プラン（.telemetry/tracking-plan.yaml）— あるべき状態
3. 差分プラン（.telemetry/delta.md）— 変更が必要な内容（存在する場合）
4. 現状（.telemetry/current-state.yaml）— 現在の状態（存在する場合）
5. 環境 — ブラウザー、Node.js、またはその両方
6. 言語 — プロジェクトの主要言語（JS プロジェクトでは TypeScript を推奨）

差分プランがある場合は、その実装を優先します。目標プランのみがある場合は、プラン全体を実装します。

実装プロセス

1. 設定を確認する

.telemetry/instrument.md を読みます。ここには、instrument フェーズで作成された SDK 固有のパターン、テンプレートコード、API エンドポイントが記載されています。instrument.md が存在しない場合は、まず product-tracking-generate-implementation-guide スキルを実行するようユーザーに伝えます（例：「インストルメンテーションガイドを作成」）。

質問：

• 「プロジェクトではどの言語／フレームワークを使っていますか？」（該当する場合は TypeScript を推奨）
• 「ブラウザー、Node.js、それとも両方ですか？」

対象の SDK、API エンドポイント、SDK 固有のパターンは、すでに instrument.md で定義されています。SDK について再質問したり、生の SDK リファレンスを読み直したりせず、インストルメンテーションガイドに従ってください。

2. 型を生成する

各イベントにつき、型定義を1つ生成します。必須プロパティは省略不可にし、省略可能なものには ?（または各言語に相当する記法）を付けます。列挙型はユニオン型にし、PII は trait インターフェースにのみ含めます。トラッキングプランに記載されたエンティティとイベントの形式に正確に従ってください。

グループ階層のない B2C 製品では、グループ関連の型と関数は省略します。トラッキングモジュールに必要なのは、identify() と track() のラッパーのみです。

例（TypeScript）：

// Auto-generated from tracking-plan.yaml — regenerate with the implementation skill

export interface UserTraits {
  email?: string;
  name?: string;
  role: 'admin' | 'member' | 'viewer';
  created_at?: string;
}

export interface UserSignedUpEvent {
  signup_source: 'organic' | 'google' | 'invite' | 'api';
}

TypeScript 以外の言語では、同等のパターン（Python のデータクラス、Ruby のモジュール、Go の構造体など）を使用します。

3. SDK ラッパーを生成する

.telemetry/instrument.md のパターンに従い、型付きラッパー関数を生成します。計測ガイドには、正確な SDK 呼び出しシグネチャ、API エンドポイント、認証パターン、テンプレートコードが記載されています。これらをそのまま使用し、ガイドのパターンから逸脱しないでください。

ガイドでは、以下を説明しています。

• identify() — 呼び出しシグネチャ、ユーザートレイト、呼び出すタイミング
• group() — 呼び出しシグネチャ、グループ階層のマッピング、グループトレイト
• track() — 呼び出しシグネチャ、イベントごとのマッピング、SDK の制約
• アーキテクチャ — 初期化、シャットダウン／フラッシュ、クライアントとサーバーのルーティング

イベントごとに関数を1つ生成します。API が明確になり、インポートも簡単になります。

4. 検証ヘルパーを生成する

任意 — 要求がない限り省略します。 TypeScript プロジェクトではコンパイル時のチェックで十分なため、実行時バリデーターが必要になることはほとんどありません。実行時検証をユーザーが要求した場合、またはコードベースで TypeScript を使わず JavaScript を使用している場合にのみ生成してください。

5. 使用例を生成する

生成したコードを実際に使用する例を示します。

// On login
identifyUser('usr_123', { email: '[email protected]', role: 'admin' });
groupAccount('usr_123', 'acc_456', { name: 'Acme Corp', plan: 'pro' });

// When user creates a report
trackReportCreated('usr_123', {
  report_id: 'rpt_789',
  report_type: 'standard',
  template_used: false,
});

6. 統合ガイドを生成する

コードベース用の統合ガイドとして、tracking/ ディレクトリに README.md を作成します（余分なドキュメントではありません）。以下を説明してください。

• SDK 依存関係のインストール方法
• 環境変数の設定方法
• 関数のインポート方法と使用方法
• プランの変更後に再生成する方法

出力構成

出力構成は、プロジェクトの技術スタックに応じて変わります。TypeScript 以外のプロジェクトについては、以下の 言語への適応 を参照してください。

tracking/
├── types.ts          # TypeScript interfaces
├── tracking.ts       # SDK wrapper with typed functions
├── validate.ts       # Runtime validators (optional)
├── examples.ts       # Usage examples
├── index.ts          # Barrel export
└── README.md         # Integration guide

言語への適応

出力構成は、プロジェクトの技術スタックに応じて変わります。

TypeScript/JavaScript（デフォルト）：

tracking/
├── types.ts          # TypeScript interfaces
├── tracking.ts       # SDK wrapper with typed functions
├── validate.ts       # Runtime validators (optional)
├── examples.ts       # Usage examples
├── index.ts          # Barrel export
└── README.md         # Integration guide

Ruby、Python、Go、その他の言語：

tracking/
├── events.[ext]      # Central event definitions (module/class/package)
├── tracking.[ext]    # SDK wrapper with typed/documented functions
├── examples.[ext]    # Usage examples
└── README.md         # Integration guide

TypeScript 以外の言語では、以下のとおりにします。

• TypeScript のインターフェースを、各言語に適した形式（Ruby のモジュール、Python のデータクラス、Go の構造体など）に置き換える
• イベント定義の一元化、型付き／ドキュメント化された関数の使用、生の文字列の散在防止という原則を維持する
• 計測ガイドが汎用 HTTP アーキテクチャを参照している場合は、プロジェクトのネイティブ言語でキューベースのパターンを実装する
• 言語に静的型チェックがない場合を除き、検証ヘルパーは省略する

差分駆動の実装

差分プランが存在する場合、実装はその差分を中心に構成します。

フック位置のマッピングは、このスキルの役割です。 計測ガイドでは、パターンと SDK の構文を示します。このスキルでは、各イベントのトラッキング呼び出しをコードベース内のどのファイル、関数に配置するかを特定します。コードベースを調査し、各イベントに適したフックポイント（コントローラー、サービス、コールバック、ハンドラーなど）を見つけてください。

追加するイベントの場合：

• 新しい型インターフェースを生成する
• 新しいトラッキング関数を生成する
• 呼び出しを追加すべき正確なファイルと関数を特定する
• 呼び出しを含むコードスニペットを示す

名前を変更するイベントの場合：

• 正しい名前の新しいトラッキング関数を生成する
• 古い呼び出しが存在するファイルを特定する
• 検索と置換の手順を示す

変更するイベント（プロパティが誤っている場合）の場合：

• 更新した型インターフェースを生成する
• 呼び出し箇所を特定する
• 各箇所について変更前と変更後を示す

削除するイベントの場合：

• 呼び出し箇所を特定する
• 削除手順を示す

増分更新

前回の実行で tracking/ のコードがすでに存在する場合：

1. まず既存のコードを読みます。 変更する前に、現在のモジュール構成を把握します。
2. 差分を適用し、再生成しないでください。 delta.md に新しいイベントが3つ含まれている場合は、新しい関数を3つ追加し、モジュール全体を再生成しないでください。
3. カスタム変更を保持します。 ユーザーがカスタムロジック（エンリッチメントや条件付きトラッキングなど）を追加している場合は、それを保持します。
4. 型とエクスポートを更新します。 新しいインターフェースを型定義ファイルに追加し、新しい関数をバレルエクスポートに追加します。
5. バージョンを更新します。 生成されたファイルにあるバージョンコメントを更新します。

信頼性の確認

実装を完了と判断する前に、次の点を確認します。

• 対象の計画にあるすべてのイベントに、型付けされた関数がある
• ID 管理（identify と group）が網羅されている
• SDK 固有のパターンが正しく使用されている（汎用的なパターンではない）
• サーバーのシャットダウンが処理されている（Node.js の場合）
• 環境変数が文書化されている
• よくある使用パターンが例で示されている

検証

ユーザーが実行するための次の検証手順を tracking/README.md に記載します。トラッキング呼び出しの実行、イベントの送信、API キーの使用は行わないでください。

• ドライラン： 開発環境で track、identify、group の各呼び出しを少なくとも1回実行する
• 配信確認： アナリティクスの送信先にあるデバッグコンソールまたはログで、イベントを受信したことを確認する
• プロパティの検証： イベントプロパティが正しい型と値で届くことを確認する
• 環境の分離： 開発環境およびステージング環境のイベントが、本番環境ではなく別のソースまたはプロジェクトに送信されることを確認する
• エラー処理： 配信に失敗してもアプリケーションがクラッシュしたり、ユーザー操作が妨げられたりしないことを確認する

動作ルール

1. 擬似コードではなく、実際のコードを記述します。 コンパイルして実行できるコードを生成します。正しい SDK API、型、インポートを使用します。

2. 計装ガイドに従います。 .telemetry/instrument.md を SDK のパターンに関する主要な情報源とします。特定の SDK の動作について instrument.md が不明確または不完全な場合に限り、references/[sdk].md を読みます。計装ガイドですでに確認した SDK リファレンスを再読しないでください。

3. すべての入力を最後まで読みます。 コードを生成する前に、tracking-plan.yaml、delta.md、current-state.yaml をすべて最後まで読みます。途中で切り上げたり、ざっと読んだりしないでください。実装には計画の全内容を把握する必要があります。

4. イベント名定数を一元管理します — これは必須です。 すべての実装に、イベント名定数を一元管理するレジストリを必ず含めます。コードベース内でイベント名の文字列を直接記述してはいけません。すべての track 呼び出しでは、文字列リテラルではなく、一元管理された定数を参照します。これは、タイプミスや不整合を防ぐ最も効果的な方法です。

   • TypeScript: export const EVENTS = { USER_SIGNED_UP: 'user.signed_up', ... } as const;
   • Ruby: module Telemetry::Events; USER_SIGNED_UP = 'user.signed_up'; end
   • Python: class Events: USER_SIGNED_UP = 'user.signed_up'
   • Go: const EventUserSignedUp = "user.signed_up"

5. イベントごとに関数を1つ用意します — イベント名が動的に決まる場合を除きます。 明確で明示的な API にします。型安全性が失われる、track(eventName, props) のような汎用ラッパーは使用しません。例外として、イベント名が実行時の状態（タブインデックスや機能フラグなど）によって決まる場合は、単一の動的ディスパッチ関数が適切なパターンです。この場合、共用体型またはルックアップテーブルで入力を制限し、任意の文字列を受け付けないようにします。

6. 配信ジョブは1つにします。 キューベースの配信を実装する場合は、呼び出しタイプごとに別々のジョブクラスを作るのではなく、メソッドパラメーターを持つジョブクラスを1つ使用します。TrackJob、IdentifyJob、GroupJob ではなく、DeliveryJob.perform(method: 'track', payload: {...}) を使用します。

7. 差分を優先し、全体計画はその次に確認します。 差分がある場合は、変更が必要な箇所を中心に実装を構成します。更新が必要なイベントが3つだけなら、すべてを再生成しないでください。

8. 難しい部分にも対応します。 サーバーのシャットダウン、グループコンテキスト、PII の分離、エラー処理、内部ユーザーの除外は、実装で問題が起こりやすい箇所です。省略しないでください。トラッキング計画で internal_user_policy が指定されている場合は、トラッキングモジュールにガードを実装します。

9. 計画を更新します。 実装後、トラッキング計画に実際の状態を反映します。計画どおりに実装できた場合は、バージョンを上げ、その旨を記録します。

10. ファイルに書き込み、会話では要約します。 生成したコードはファイルに書き込みます。会話では簡潔な要約（作成したファイル、イベント数、主な判断事項）のみを示します。コードを20行を超えてチャットに貼り付けないでください。

11. 検討過程ではなく、判断事項を示します。 内部で検討し、ユーザーには生成した内容とその理由のみを示します。問題を解決するまでの過程は見せないでください。

ライフサイクル

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

次のフェーズ

実装後、次のコマンドの実行をユーザーに提案します。

• product-tracking-audit-current-tracking — 実装が計画と一致していることを確認するため、必要に応じて再監査します（例：「トラッキングを監査」「トラッキングを検証」）
• product-tracking-instrument-new-feature — 次の機能をリリースするときに、トラッキングの一貫性を保ちます（例：「機能を計装」「新機能のトラッキング」「新機能のトラッキング設定」）