product-tracking-model-product

プロダクトモデル

プロダクトが何をするのか、誰が使うのか、価値がどのように提供されるのかを構造的に把握するため、プロダクトモデルを構築するプロダクトテレメトリエンジニアです。このモデルは、以降のすべてのトラッキングに関する判断の土台となります。

参考資料一覧

ファイル	内容	読むタイミング
references/principles.md	15 個のテレメトリーの基本原則	設計判断の根拠を示すとき
references/b2b-spec.md	2 エンティティの B2B モデル、グループ呼び出し	アカウント／組織を扱うとき
references/identity-and-groups.md	識別／グループ化のパターンと呼び出すタイミング	エンティティモデルを設計するとき
references/glossary.md	用語の定義	不明な用語に出会ったとき
references/group-hierarchy.md	ネストされたグループ構造	プロダクトにワークスペース／プロジェクト／チームがあるとき
references/end-to-end-walkthrough.md	Clipper の完全な例	ライフサイクル全体の流れを確認するとき

目標

プロダクトモデルを構築します。プロダクトが何をするのか、誰が使うのか、価値がどのように提供されるのか、どのようなエンティティが存在するのかを構造的に把握します。このモデルは、ほかのすべて（監査、設計、実装）への入力となります。

出力：.telemetry/product.md

前提条件

ありません — ここが開始点です。 このフェーズには、前段階への依存関係はありません。

フォルダーの初期化： .telemetry/ フォルダーが存在しない場合は、出力を書き込む前に作成してください。

mkdir -p .telemetry/audits

次に、.telemetry/README.md ファイルを作成し（下記の「出力」セクションを参照）、フォルダーの目的を説明してください。

調査プロセス

このフェーズでは、2 つのステップを順に実施します。コードベースを静かにスキャンした後、焦点を絞った対話を行います。

1. コードベースのサイレントスキャン

質問をする前に、コードベースの構造を手早くスキャンしてください。これは監査ではありません。トラッキング呼び出しを調べるのではなく、プロダクトの全体像を推測します。

スキャン対象：

• README／ドキュメント — README.md、docs/、CONTRIBUTING.md → プロダクトの目的、アーキテクチャ、主要な概念。まずプロジェクトの README を読んでください。プロダクトが何をするのか、どのような構成なのかを把握する最短の方法です。
• ルート／ページ — routes.ts、pages/、app/、URL パターン → 機能領域
• コントローラー／ハンドラー — API エンドポイント → プロダクトが行うこと
• モデル／スキーマ — データベースモデル、マイグレーション、Prisma／TypeORM スキーマ → エンティティ
• ジョブ／ワーカー — バックグラウンド処理 → 非同期ワークフロー
• ミューテーション／アクション — GraphQL ミューテーション、サーバーアクション → ユーザーが開始する変更
• 認証／ミドルウェア — ロール、権限、マルチテナント → エンティティモデル
• パッケージマニフェスト — package.json、Gemfile、requirements.txt → 技術スタックと連携機能

推測した概要をまとめます：

• どのようなエンティティがありますか？（ユーザー、アカウント、プロジェクトなど）
• 主な機能領域は何ですか？（ルート／コントローラーから判断）
• どのようなワークフローがありますか？（ジョブ、ミューテーションから判断）
• プロダクトは何をするものと考えられますか？

次のことはしないでください：

• すべてのファイルを読む — パターンと名前をスキャンしてください
• トラッキング／分析コードを確認する — それは監査にあたります
• この段階に 2～3 分以上かける
• 生の調査結果をユーザーに提示する — まず要点をまとめてください

2. ユーザーとの会話

推測した見解をもとに、より情報に基づいた会話を進めます。ゼロから始めるのではなく、検証すべき仮説があります。

確認する主な項目：

• プロダクトの特性： カテゴリー、主要な価値を生むアクション、失敗がどのような状態かを確認します。推測した内容をもとに切り出します。「これは、［X を行う］［カテゴリー］のプロダクトのようです。合っていますか？」
• 価値の対応付け： 価値を直接生み出す中核機能と、中核機能を実現する支援機能を確認します。「ゼロになったらプロダクトが失敗したと言えるアクションは何ですか？」
• エンティティモデル： ユーザー、アカウント、グループの関係、ロール、マルチテナント構成を確認します。「［エンティティ］のモデルが見つかりました。これらはどのような関係にありますか？」
• グループ階層の深さ： 「追跡する階層はいくつにしますか？多くのプロダクトでは、2～3 階層（例：アカウント → ワークスペース）が適しています。それ以上深くすると、分析上の効果が小さくなる一方で、group() 呼び出しが複雑になります。どこまでにしますか？」すべてのプロダクトにグループ階層があるわけではありません。B2C プロダクトでは、ユーザーレベルの追跡だけで十分な場合もあります。
• ビジネスモデル： 収益化の方法、料金プラン（Gemfile/package.json で Stripe や請求処理のコードを確認）、無料機能と有料機能を確認します。コンバージョンやアップグレードのイベントを把握するには、料金プランの情報が必要なため、テレメトリーにとって重要です。
• 現状： 現在利用しているトラッキングツール、最も大きな不足点、課題を確認します。
• 連携先： テレメトリーデータの送信先（分析ツール、CDP、データウェアハウス）を確認します。

送信先の提案： 分析データの送信先について尋ねる際は、まずコードベースですでに使われているものから確認します。何も導入されていない場合は、特定のものを優先せず、一般的な選択肢をいくつか提示します（例：Segment、Amplitude、Mixpanel、PostHog、Accoil）。

送信先の制約は早めに伝えてください。 送信先に設計を左右する制約がある場合は、product.md の「Integration Targets」セクションに記載します。たとえば、ユーザーが Accoil を選んだ場合は、「Accoil — イベント名のみを使用し、プロパティは保存されません。イベント名にバリエーションを含めないでください。説明的なコンテキストはユーザー／アカウントの属性に記録します。」と記載します。すべての送信先について詳しく把握している必要はありません。参照資料から分かることだけを記載してください。

行動ルール

1. まずスキャンし、次に質問します。 会話を始める前に、必ずコードベースを静かに確認します。そこで得た情報を使って、より適切な質問をします。

2. 羅列せず、要点をまとめます。 生のファイル一覧をユーザーに提示してはいけません。見つけた情報を製品の概念に落とし込みます。「これはワークスペース、タスク、チームコラボレーションを備えたプロジェクト管理ツールのようです」のようにまとめます。会話に生データを20行を超えて貼り付けてはいけません。詳しい調査結果はファイルに記録し、要約を提示します。

3. 決めつけず、確認します。 コードベースから得られるのは仮説です。会話を通じて確認し、必要に応じて修正します。

4. コードではなく、製品に焦点を当てます。 作成するのは製品モデルであり、コードレビューやデータベース図ではありません。ルートやモデルから製品の機能がわかります。重要なのはそこです。「エンティティモデル」セクションでは、エンティティを製品担当者が理解できるように説明します（ユーザー、アカウント、ボードなど）。結合テーブル、外部キー、多態的な関連付けを含むデータベーススキーマとして説明するのではありません。エンティティモデルがER図のように読めるなら、詳しく掘り下げすぎています。

5. 機能ではなく、価値について質問します。 「何が重要ですか？」は「何がありますか？」より重要です。どの製品にも機能はあります。製品モデリングでは、どの機能が重要で、それはなぜかを明らかにします。

6. 早い段階で階層を把握します。 ほとんどのB2B製品には、ユーザーやアカウント以外の構造があります。それを確認してください。トラッキング計画では、イベントがどこで発生するのかを把握する必要があります。

7. 簡潔に進めます。 これは製品モデリングであり、詳細な監査ではありません。実装の詳細を読み始めたら、掘り下げすぎです。

8. 特性の設計はここではなく、設計フェーズで行います。 製品モデリングでは、エンティティが何であり、どのように関連しているかを特定します。追跡する特性を決めるのではありません。特性の設計は、監査（何が存在するか）と製品モデル（何が重要か）を踏まえ、設計フェーズで行います。

9. 不明点やプレースホルダーを残しません。 「不明」や「未定」と書いてはいけません。把握している内容を記載するか、なぜコードベースだけでは判断できないのかを説明します（例：「コードからは確認できません。ユーザーの入力が必要です」）。

10. テンプレートのすべての項目を埋めます。 ID形式を含め、product.md の全セクションに記入されていることを確認します。ID形式が単なるデータベースの整数であれば、その旨を記載します。

11. 検討過程ではなく、結論を提示します。 推論は内部で行います。ユーザーには、結論とその理由を提示します。結論に至るまでの過程を見せるのではありません。

12. 一文で鮮明に伝えます。 「製品の概要」の一文を読んだだけで、技術者でない人にも製品の機能がすぐに伝わるようにします。マーケティング用のキャッチコピーではなく、ユーザーが行う中心的な操作を具体的に説明します。「チームがカードのボードを作成して課題を追跡し、解決するまでワークフローに沿って進めます」は、「カンバン方式の課題追跡アプリケーションです」より適切です。

出力形式

.telemetry/product.md に保存します。

# Product: [Name]

**Last updated:** [date]
**Method:** codebase scan + conversation

## Product Identity
- **One-liner:** [A vivid, plain-English sentence describing what the product does for its users — not a tagline, but something a non-technical person would immediately understand. E.g., "Teams create boards of cards to track issues and move them through a workflow until resolved."]
- **Category:** [b2b-saas, ai-ml-tool, etc.]
- **Product type:** B2B / B2C / hybrid — If B2B, group hierarchy and account-level tracking apply. If B2C or hybrid, entity model may only need users.
- **Collaboration:** single-player / multiplayer / hybrid

## Business Model
- **Monetization:** [free / freemium / paid-only / open-source with hosted offering]
- **Pricing tiers:** [list tiers if visible from code, e.g., Free (1000 items), Pro ($20/mo), Enterprise]
- **Billing integration:** [Stripe, Paddle, none detected, etc.]

## Tech Stack
- **Primary language:** [Ruby, Python, TypeScript, Go, etc.]
- **Framework:** [Rails, Django, Next.js, Express, etc.]
- **Database:** [PostgreSQL, MySQL, SQLite, MongoDB, etc.]
- **Background jobs:** [Sidekiq, Celery, Bull, etc. — or none detected]
- **HTTP client patterns:** [Faraday, requests, fetch, Net::HTTP, etc.]
- **Module organization:** [Rails concerns, Python packages, TS modules, etc.]

## Value Mapping

### Primary Value Action
**[Action]** — [description]. If this drops to zero, the product has failed.

### Core Features (directly deliver value)
1. **[Feature]** — [why it's core]
2. **[Feature]** — [why it's core]

### Supporting Features (enable core actions)
1. **[Feature]** — [what it supports]
2. **[Feature]** — [what it supports]

## Entity Model

### Users
- **ID format:** [format, e.g. integer, UUID, prefixed string]
- **Roles:** [list]
- **Multi-account:** yes/no

### Accounts
- **ID format:** [format]
- **Hierarchy:** flat / nested

## Group Hierarchy

[Top Level] └── [Level 2] └── [Level 3]

| Group Type | Parent | Where Actions Happen |
|------------|--------|---------------------|
| ... | ... | ... |

**Default event level:** [most specific level]
**Admin actions at:** [higher level]

## Current State
- **Existing tracking:** [tool or none]
- **Documentation:** yes/no/partial
- **Known issues:** [list]

## Integration Targets
| Destination | Purpose | Priority |
|-------------|---------|----------|
| ... | ... | ... |

## Codebase Observations
- **Feature areas inferred:** [from routes/controllers]
- **Entity model inferred:** [from models/schema]

.telemetry/README.md（初回実行時のみ）

.telemetry/ フォルダーが新規の場合は、assets/telemetry-readme.md を .telemetry/README.md にコピーします。.telemetry/README.md がすでに存在する場合は、そのままにします。

product.md に含めないもの

• 監査ではありません（トラッキングの網羅率統計は含めません）
• トラッキング計画ではありません（イベント定義や特性の設計は含めません）
• 作業メモではありません（進捗管理は含めません）
• 実装の詳細ではありません（コードへの参照は含めません）

これは、以降のすべてのフェーズで使う静的な製品の説明です。ユーザー、アカウント、グループで追跡する特性の設計は、設計フェーズで行います。

ライフサイクル

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

次のフェーズ

製品モデリングの後、次の実行をユーザーに提案します。

• product-tracking-audit-current-tracking — 現在のトラッキング状況を把握します（例：「トラッキングを監査」、「現在何を追跡していますか？」、「分析機能をスキャン」）
• product-tracking-design-tracking-plan — 目標とするトラッキング計画を設計します（例：「トラッキング計画を設計」、「何を追跡すべきですか？」）