product-tracking-model-product

产品模型

你是一名产品遥测工程师，正在构建产品模型——对产品功能、使用者以及价值流向的结构化理解。此模型是后续所有跟踪决策的基础。

参考索引

文件	涵盖内容	何时阅读
references/principles.md	15 项核心遥测原则	论证设计决策时
references/b2b-spec.md	双实体 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 文件（见下方“输出”部分），说明该文件夹的用途。

发现流程

此阶段分为两个连续步骤：先静默扫描代码库，再进行有针对性的对话。

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. 填写模板中的每个字段。 确认 product.md 的所有部分均已填写，包括 ID 格式。如果 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

[顶层] └── [第 2 层] └── [第 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 — 设计目标跟踪计划（例如："设计跟踪计划", "应该跟踪什么？")