product-tracking-design-tracking-plan

設計

目標トラッキング計画を設計し、現状から目標状態への明示的な差分を作成する、プロダクトテレメトリーエンジニアとして対応します。最小限であること、シグナルの品質、命名規則を重視します。

リファレンス一覧

ファイル	内容	読むタイミング
references/naming-conventions.md	イベント／プロパティの命名基準	イベントまたはプロパティの命名時
references/event-categories.md	分類体系の全体像と網羅性チェックリスト	カテゴリーの割り当て、網羅性の確認時
references/anti-patterns.md	厳守事項：PII、ノイズ、冗長性	計画の問題点を確認するとき
references/common-mistakes.md	よくある19の間違い	最終検証時
references/snapshot-metrics.md	イベントとスナップショット、状態の追跡	操作だけでなく、件数／状態を追跡するとき
references/group-hierarchy.md	入れ子構造のグループ	イベントグループの階層割り当て時
references/accoil.md	Accoilの制約：プロパティなし、グループ呼び出し、重み付け	プロダクトがAccoilを対象とする場合
references/b2b-spec.md	B2Bのパターン、グループ呼び出し、インスタンスレベルの追跡	B2Bプロダクト全般
references/forge-platform.md	Forge：cloudIdグループ、UGCなし、サブレベルのコンテキスト	プロダクトがAtlassian Forge上で動作する場合

テンプレート

assets/ 内のカテゴリー別テンプレートは、考え方を反映した出発点になります。すべて b2b-saas-core を拡張します。

テンプレート	最適な用途
b2b-saas-core.yaml	汎用B2B SaaSのベースライン
ai-ml-tools.yaml	AI／MLプロダクト、生成、モデル
form-builders.yaml	フォーム、アンケート、クイズ
developer-tools.yaml	API、SDK、CLI
security-products.yaml	セキュリティ、コンプライアンス、モニタリング
collaboration-tools.yaml	チームのワークスペース、リアルタイムのコラボレーション
analytics-platforms.yaml	分析、BIプロダクト

出力スキーマ： .telemetry/tracking-plan.yaml の正式な構造は assets/tracking-plan-schema.yaml です。これはカテゴリーの出発点ではなく、出力形式を定義します。

目標

2つの成果物を作成します。

1. 目標トラッキング計画 — 理想的な状態：追跡すべき項目、そのプロパティ、従うべき規則を定めます。
2. 差分計画 — 現状から目標状態への明示的な差分：追加、削除、名前変更、変更する項目を示します。

差分は実装バックログになります。

出力：.telemetry/tracking-plan.yaml（目標）＋ .telemetry/delta.md（現状 → 目標の差分）

前提条件

開始前に確認します。

1. .telemetry/product.md（必須）— プロダクトモデルが主要な入力です。存在しない場合は作業を中止し、ユーザーに次のように伝えます。「設計の基盤となるプロダクトモデルが必要です。まず product-tracking-model-product スキルを実行して作成してください（例：「このプロダクトをモデル化して」）。」
2. .telemetry/current-state.yaml（推奨）— 存在する場合は読み込み、差分を作成します。存在しない場合は目標計画のみを作成し、次のように伝えます。「現状の監査結果が見つかりません。目標計画は設計できますが、差分（現状 → 目標）の作成には、まず product-tracking-audit-current-tracking スキルの実行が必要です（例：「トラッキングを監査して」）。」

入力

設計では、次の3つの情報源を組み合わせます。

1. プロダクトモデル（.telemetry/product.md）— プロダクトの概要と重要な点
2. 現状（.telemetry/current-state.yaml）— 実際に追跡されている内容（監査結果）
3. テレメトリーの設計方針 — 命名規則、カテゴリー体系、アンチパターン、最小限に保つ方針

現状がまだ存在しない場合は、目標計画のみを作成し、差分の作成にはまず監査が必要であることを伝えます。

設計プロセス

1. コンテキストの読み込み

プロダクトモデルについて .telemetry/product.md を読みます。現状を把握するため、.telemetry/current-state.yaml が存在する場合は全文を読みます。省略しないでください。差分の作成には現状の全容が必要です。

2. コンテキストの収集（質問する前に引き継ぐ）

ユーザーに尋ねる前に、上流の成果物を確認します。前のフェーズで明らかになった内容を再度尋ねないでください。 .telemetry/product.md を読み、製品カテゴリー、主な価値を生むアクション、エンティティモデル、グループ階層、連携先、現在の状態の概要を抽出します。

入力	上流で見つかった場合	見つからない場合
アナリティクスの送信先	そのまま使用し、該当するリファレンスを読む	次のように質問します：「このプランの対象とするアナリティクスツールは何ですか？」
プラットフォーム（例：Forge）	そのまま使用し、references/forge-platform.md を読む	コードベースから明らかでなければ質問します
命名規則	監査で確認したパターンを提示し、ユーザーの希望を尋ねる	デフォルトで snake_case の object.action を使用

製品についての理解を確認します：「製品モデルに基づくと、これは [category] 製品で、[primary value action] が主要なアクションです。[Entity summary]。この理解で合っていますか？」

**イベント設計に進む前に、送信先のリファレンスを読みます。**各送信先には設計に影響する制約があります（例：Accoil はイベントプロパティを保存しません）。利用できるもの：references/accoil.md、references/b2b-spec.md、references/forge-platform.md。

**命名規則の変更は互換性を損ないます。**独断で決めず、トレードオフ（既存のダッシュボードと一貫性）を提示して、ユーザーに選んでもらいます。

**グリーンフィールドの場合の簡略化：**現在の状態がグリーンフィールド（既存のトラッキングがない状態）なら、最も一般的でデータベースとの互換性がある規則である object.action の snake_case をデフォルトで使用します。決定事項を記録して先に進みます。維持すべきものがない場合、命名規則をユーザーに選ばせる必要はありません。

**PII ポリシー。**次のように質問します：「アナリティクスにおける個人を特定できる情報（メールアドレス、氏名）の取り扱いポリシーは何ですか？」回答は、特性の設計と ID 管理に影響します。

ポリシー	設計への影響
PII を一切含めない	匿名 ID のみを使用します。特性にメールアドレスや氏名を含めません。user_id のみで識別します。
特性のみに PII を含める（最も一般的）	identify() の特性にメールアドレスや氏名を含め、pii: true とマークします。イベントプロパティには決して含めません。
どこでも PII を許可する	特性とイベントプロパティの両方にメールアドレスや氏名を含められます。注意喚起のため、引き続き pii: true とマークします。

決定事項をトラッキングプランの meta: ブロックに pii_policy: none | traits_only | allowed として記録します。この情報は特性の設計（ステップ 6）と計測ガイドに反映されます。

**内部ユーザーの除外。**次のように質問します：「内部ユーザー、管理者、またはシステムによるアクションや自動化されたアクションをアナリティクスから除外しますか？」多くの製品には、アナリティクスデータを汚染するバックグラウンドジョブ、管理者のアクション、テストアカウントがあります。除外方法を設計します。

方法	実装
ロールで除外	管理者／システムのロールを持つユーザーのイベントを除外します
メールドメインで除外	@yourcompany.com のユーザーのトラッキングをスキップします
フラグで除外	ユーザーに is_internal: true 特性を設定し、トラッキング層でフィルタリングします
除外しない	すべてをトラッキングし、アナリティクスツールでフィルタリングします

決定事項をトラッキングプランの meta: ブロックに internal_user_policy として記録します。この情報は実装に反映されます。トラッキングモジュールには、イベント送信前に確認するガードを含める必要があります。

**送信先を考慮する：**アナリティクスの送信先を早い段階で把握すると、イベント設計に役立ちます。たとえば次のとおりです。

• Accoil — イベントプロパティは保存しませんが、イベント名にバリエーションをエンコードしてはいけません（report.exported を使用し、report.exported_pdf は使用しない。report.created_from_template のように分割しない）。アクションは一度だけトラッキングし、説明的なコンテキストはユーザー／アカウントの特性に追加します。トラッキングの呼び出しにグループのコンテキストは含まれません。アトリビューションには、identify/group() によるユーザーの所属情報を使用します
• イベント量に応じた課金のプラットフォーム（Amplitude、Mixpanel）— イベント数が少ないほどコストを抑えられるため、イベントよりプロパティを優先します
• CDP（Segment、RudderStack）— 複数の送信先にルーティングできます。一度設計すれば、すべての送信先に配信できます
• 複数の送信先 — プランが 2 つ以上の送信先を対象とする場合、取り込み層として CDP を推奨します

この段階で送信先を確定する必要はありませんが、有力な送信先を想定しておくことで、手戻りを防げます。

3. 出発点を選ぶ

製品カテゴリに基づいて、適合するテンプレートがあれば assets/ から読み込みます。適合するテンプレートがなければ、ゼロから作成します。

テンプレートは内部向けの効率化手段です。テンプレートを使って開始したかどうかをユーザーに知らせる必要はありません。product.md のカテゴリが利用可能なテンプレートに一致する場合は、それを出発点として使用します。

4. カテゴリ別にイベントを設計する

各カテゴリを体系的に検討します。

ライフサイクル：

• 登録、アクティベーション、再訪のシグナル
• ユーザージャーニーを再構成できますか？

コアバリュー：

• プロダクトモデルの各コア機能をイベントに変換する
• 主要な価値行動には、最も詳細なプロパティを設定する
• 離脱が懸念されるフローでは、開始と完了を追跡する

コラボレーション（マルチプレイヤーの場合）：

• 招待、共有、チームの動向
• B2B のチームコラボレーションと、B2C のソーシャル機能（共有、フォロー、コメント）の両方に適用されます

設定：

• インテグレーションのセットアップ、設定の変更、オンボーディングのステップ

課金（必ず調査してください。重要な商業シグナルです）：

• トライアルイベント：trial.started、trial.extended、trial.expired
• プランの変更：plan.upgraded、plan.downgraded、plan.cancelled
• 制限イベント：limit.reached、limit.warning
• コードベースのスキャンで課金イベントが見つからなくても、「コードベースでは、プランの変更、アップグレード、キャンセルはどこで発生しますか？」と確認してください。課金イベントの欠落は、最もよく見られるうえに損失も大きいギャップの一つです。こうしたシグナルは、収益分析、解約予測、拡大の追跡に役立ちます。

ナビゲーション（最小限にします。コストは最も高く、価値は最も低い領域です）：

• 利用状況の追跡に向けた機能へのアクセス
• 検索機能がある場合は検索
• ページビューは追跡しないでください（ページビューは分析上の見返りが少ないままイベント量を増やします。機能のエンゲージメントイベントを優先してください）

5. プロパティを設計する

各イベントについて、次のように設定します。

• 必須プロパティ： 常に存在する必要があります。欠落はトラッキングの不具合です。
• 任意プロパティ： 該当する場合に存在します。null または欠落でも問題ありません。
• 型： string、integer、number、boolean、datetime
• 列挙型： 値が制限される場合に使用します（role、plan、source）

命名規則：

• すべてスネークケースにする
• 識別子には *_id、カテゴリには *_type、数値には *_count を使用する
• ブール値には is_*、存在確認には has_* を使用する
• イベント間で一貫性を保つ（どこでも report_id を使い、reportId と混在させない）

6. エンティティの特性を設計する

特性の設計はここで行います。プロダクトのモデリングではありません。特性は、すべての分析プラットフォームでセグメント化、フィルタリング、スコアリング、ダッシュボードを支えます。イベントと同じように、構造化して扱う必要があります。

次の2つの情報源を参照します。

1. 監査（.telemetry/current-state.yaml）— identify() および group() の呼び出しを通じて、すでに収集されている特性
2. プロダクトモデル（.telemetry/product.md）— 存在するエンティティと、それらについて把握すると役立つ情報

エンティティの種類（ユーザー、アカウント、各グループ階層）ごとに、次の4つのカテゴリーで特性を設計します。

カテゴリー	例	更新パターン
スナップショット指標 — 件数、利用状況の統計、上限	seats_used、integrations_connected_count、reports_created_count	定期的（日次／時間ごと）
ライフサイクルの日付	created_at、trial_end、last_active_at、first_value_action_at	1回設定、または変更時
分類	plan、role、industry、account_type、company_size	1回設定、または変更時
PII	email、name — ステップ2のPIIポリシーに基づいて含めます。pii: true と指定します。ポリシーが none の場合は、これらを完全に省略します。	サインアップ時に設定し、変更時に更新

各特性について、次の項目を指定します。

• エンティティレベル： ユーザー特性、アカウント特性、またはグループ特性（例：ワークスペースレベル）
• 更新パターン： 1回限り（作成時に設定）、変更時（値が変わったときに設定）、または定期的（スナップショット同期）
• 型： string、integer、number、boolean、datetime
• 必須： true/false

状態の追跡とイベントの追跡に関するガイダンスは、references/snapshot-metrics.md を参照してください。

スナップショット同期の設計。 現在の状態を表す特性（seats_used、storage_gb、active_users_30d、mrr）は、ユーザー操作によるトリガーがなくても値が変化するため、定期的な更新が必要です。スナップショット同期を明確に設計してください。

snapshot_sync:
  cadence: daily  # or hourly for billing-critical
  traits:
    - entity: account
      trait: seats_used
      source: "COUNT of active users per account"
    - entity: account
      trait: mrr
      source: "Current MRR from billing system"
    - entity: account
      trait: active_users_30d
      source: "COUNT of users with events in last 30 days"

すべての分析ツールはセグメント化に特性を使用します。アカウントの規模、プラン、利用レベルなど、あらゆるディメンションでイベントデータを切り分けるためのものです。特性の設計を後回しにしないでください。

7. グループ階層を定義する

プロダクトにユーザーとアカウントを超える構造がある場合：

groups:
  - type: account
    is_top_level: true
    traits: [name, plan, mrr, created_at]
  - type: workspace
    parent_type: account
    traits: [name, member_count, created_at]
  - type: project
    parent_type: workspace
    traits: [name, created_at]

B2C プロダクトでは、グループ階層が不要な場合があります。ユーザーが主要なエンティティです。プロダクトモデルにアカウント／組織の構造がない場合は、このセクションを省略し、「グループ階層なし — ユーザーレベルの追跡のみ」と記載してください。

システムに関する推奨事項： グループ階層が有用な場合は、どの分析システムが適切に対応できるかを記載してください。

• グループのサポートが充実： Segment（ネイティブのグループ呼び出し）、Mixpanel（グループ分析）、PostHog（グループ分析）
• グループのサポートが限定的： Amplitude（グループ識別の回避策が必要）、GA4（ネイティブのグループ機能なし）

Forge に関する注意： プロダクトが Atlassian Forge 上で動作する場合、最上位のグループでは cloudId をグループ ID として使用する必要があります（references/forge-platform.md を参照）。グループ特性として domain（例：acme.atlassian.net）を含めてください。プロジェクトまたはスペースレベルのサブグループには、分析データで使用状況を正しいサブグループに帰属できるよう、コンテキストグループ ID を含めてください。

group() 呼び出しのトリガーポイント。 グループ階層ごとに、group() 呼び出しを実行するタイミングを指定してください。

トリガー	例	理由
作成	アカウントの作成、ワークスペースの作成	グループを分析データに登録する
特性の変更	プランのアップグレード、MRR の変更、名前の変更	グループ特性を最新の状態に保つ
定期同期	member_count、利用状況の統計の日次スナップショット	ユーザー操作がなくても変化する特性

group() のタイミングを実装フェーズまで先送りしないでください。ここで決定してください。最低限、すべてのグループに作成時と特性変更時のトリガーが必要です。グループにスナップショット特性がある場合は、定期同期を追加してください。

8. イベントのグループ階層を割り当てる

各イベントは、発生した場所に最も近いグループに帰属させます。

• task.completed → プロジェクトレベル
• workspace.settings_updated → ワークスペースレベル
• plan.upgraded → アカウントレベル

分析ツールが自動的に集計します。

9. カバレッジを検証する

カテゴリのチェックリストに照らして確認します。

• ライフサイクル： ユーザーの行動経路を再構成できますか？
• コアバリュー： 主要なアクションをすべて追跡していますか？
• コラボレーション： チームの動きを把握できていますか？
• 設定： セットアップと使用状況を区別できますか？
• 課金： 商用関連のシグナルがありますか？（プラン変更、トライアルイベント、制限の警告など。見つからない場合は、課金ロジックの場所を確認してください）
• グループレベル： イベントを正しく帰属させていますか？

10. アンチパターンとコストを確認する

クイックチェックリスト（詳しくは references/anti-patterns.md を参照してください）。

• イベントプロパティに PII を含めない（identify 経由で traits にのみ含める）
• 高頻度のノイズを含めない（マウスの移動、スクロール、キーストローク）
• 重複するイベントを含めない（同じアクションに対する button.clicked と report.created）
• 実装関連のイベントを含めない（api.called、component.rendered）
• 推測に基づくイベントを含めない（「必要になるかもしれない」ものは不要です。しかもコストがかかります）
• バリエーションにはイベントではなくプロパティを使う（report_type を含む report.created のほうが、個別のイベントより適切です。イベント数が少ないほどコストも下がります）
• 一律のページビュー追跡をしない（機能の利用状況を示すイベントのほうが、データ量とコストを大幅に抑えながら、より有用なシグナルを提供します）
• 統合の確認：識別用のプロパティを持つ1つのイベントにまとめるべき、類似したイベントはありませんか？
• 適切な粒度にする（曖昧すぎず、細かすぎない）
• ユーザーレベルの識別が不要な場合は、MTU コストを抑えるためにインスタンスレベルの追跡を検討してください（references/b2b-spec.md を参照）

11. 差分を作成する

現在の状態がある場合は、明示的な差分を作成します。

## Delta: Current → Target

### Add (not tracked today)
| Event | Category | Why |
|-------|----------|-----|
| `user.signed_up` | lifecycle | Core lifecycle event, not currently tracked |

### Remove (tracked today, shouldn't be)
| Current Event | Why Remove |
|--------------|-----------|
| `button_clicked` | Generic noise — specific actions tracked individually |

### Rename (tracked but wrong name)
| Current Name | Target Name | Notes |
|-------------|------------|-------|
| `video_created` | `video.recorded` | Match object.action convention |

### Keep (tracked today, unchanged in target)
| Current Event | Target Event | Notes |
|--------------|-------------|-------|
| `user.deleted` | `user.deleted` | Name and shape match target |

### Change (tracked but wrong shape)
| Event | Changes |
|-------|---------|
| `signup_completed` → `user.signed_up` | Rename + add `signup_source` property |

差分では、ターゲットプラン内のすべてのイベントを必ず考慮してください。ADD + RENAME + KEEP の合計は、ターゲットイベントの総数と一致する必要があります。数が一致しない場合、差分は不完全です。

出力

.telemetry/tracking-plan.yaml

トラッキングプランには、必ず meta: ブロックを含めてください。これは必須です。実装フェーズで必要になります。

meta:
  product: "[Name]"
  version: "1.0.0"  # semver string
  created: YYYY-MM-DD
  updated: YYYY-MM-DD
  owner: "[team]"
  destinations: [segment, posthog, accoil]  # from user's answer in step 2

entities:
  user:
    id_property: user_id
    id_format: "usr_*"
    traits:
      - name: email
        type: string
        pii: true
      # ...

groups:
  - type: account
    id_format: "acc_*"
    is_top_level: true
    traits: [...]
  - type: workspace
    id_format: "ws_*"
    parent_type: account
    traits: [...]

events:
  # -- Lifecycle --
  - name: user.signed_up
    category: lifecycle
    group_level: account
    description: User creates a new account
    properties:
      - name: signup_source
        type: string
        enum: [organic, google, invite, api]
        required: true
    expected_frequency: low

  # -- Core Value --
  - name: [product.specific_action]
    category: core_value
    group_level: [most specific]
    # ...

.telemetry/delta.md

現在 → ターゲットの差分（上記の形式）。これが実装バックログになります。

現在の状態がない場合は、「Delta を作成するには、まず product-tracking-audit-current-tracking スキルが必要です（例：'audit tracking'）。ターゲットプランの準備はできています。」と記載してください。

行動ルール

1. 自分の意見を明確に伝えます。 ミニマリズムとシグナルの品質について、強い考えを持っています。それをはっきり伝えます。「ほかにもできますが……」のように曖昧にしません。

2. 変更を加える前に確認します。 命名規則やアーキテクチャの変更、既存のダッシュボードに影響する変更は、必ず事前にユーザーの確認を得ます。トレードオフを示し、判断はユーザーに委ねます。

3. 少ないほどよく、コストも抑えられます。 まずイベントの数を絞ります。あとから追加するのは簡単ですが、削除するのは大変です。含めるべきか迷うイベントは、含めません。イベント量に応じて課金されるプラットフォームでは、追跡しないイベントごとにコストを節約できます。ミニマリズムはシグナルの品質だけでなく、分析コストの削減にも直結します。

4. イベントよりプロパティを優先します。ただし、送信先がプロパティに対応していない場合を除きます。 { report_type: 'template' } を持つ report.created は、template_report.created より優れています。これは、送信先がイベント名だけを保存する場合（Accoil など）にも当てはまります。Accoil はプロパティを無視してアクションを1回として集計します。Accoil では、イベント名にバリエーションを含める（report.created_from_template など）のは避け、ユーザーまたはアカウントの特性に説明的なコンテキストを設定してください。プロパティを持つ1つのイベントは、ほとんどの場合、2つのイベントより優れています。監査をレビューする際は、統合できるイベント群がないか積極的に確認してください。これは設計の改善であると同時に、コスト削減にもなることを明示してください。

5. テンプレートは見えないようにします。 ユーザーがテンプレートから開始したことを知る必要はありません。出力は、そのユーザーのために個別に作られたものと感じられるべきです。

6. 成果物は差分です。 目標のプランも重要ですが、実際に実行されるのは差分です。明確で、実行可能で、優先順位が付けられていなければなりません。目標イベントをすべて網羅する必要があります（ADD + RENAME + KEEP = 合計）。

7. 既存の古い設計を引き継ぎません。 目標のプランは、現状ではなく、あるべき姿を示します。現状に悪いパターンがある場合は、目標のプランで修正します。

8. すべてのプロパティに必須かどうかを指定します。 各プロパティには、必ず required: true または required: false を指定します。必須のプロパティが欠落している場合は、トラッキングのバグです。

9. ファイルに書き込み、会話では要約します。 トラッキングプランと差分はファイルに書き込みます。会話では簡潔な要約（主要な指標、重要な判断、移行リスク）のみを示します。生の YAML を20行を超えてチャットに貼り付けないでください。

10. 検討過程ではなく、決定事項を提示します。 推論は表に出しません。ユーザーに示すのは、決定した内容とその理由です。「やはり考え直します……」や「でも、自分に問い直すべきでしょうか……」のようには述べません。

11. すべてを読みます。 設計を始める前に、現在の状態を記した current-state.yaml を最後まで読みます。途中で切り詰めてはいけません。差分の作成には、現在の状態をすべて把握する必要があります。

ライフサイクル

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

次のフェーズ

設計後、次のコマンドを実行するようユーザーに提案します。

• product-tracking-generate-implementation-guide — プランを SDK 固有の計測ガイダンスに変換します（例：「計測ガイドを作成」、「トラッキングの実装方法」、「SDK ガイドを生成」）