discover-analytics-patterns

discover-analytics-patterns

你的目标是找出此代码库如何发送分析事件——不是有哪些事件，而是工程师使用哪些具体代码模式来触发跟踪调用。此输出可帮助工程师添加与代码库其余部分风格一致的新事件。它还应告知下游技能，此处代码中事件名称和属性名称通常采用怎样的写法。

确定此技能中的命名约定时，请严格按照以下优先级使用这些来源：

1. .amplitude/instrumentation-agent-context.md 中的客户指令（以及该文件引用的任何文件）（如果存在）——这些是客户希望遵循的明确约定，因此优先级高于以下所有内容。
2. 从 Amplitude MCP 服务中观察到的事件和属性
3. 代码库中实际的跟踪调用位置
4. taxonomy 技能中的约定，路径为 ../taxonomy/SKILL.md

---

步骤 0：读取仓库埋点上下文

在进行任何其他操作之前，请检查 .amplitude/instrumentation-agent-context.md （仓库根目录或你要埋点的子目录）。如果该文件存在，请阅读它以及其中引用的所有仓库相对路径文件。其中说明的任何命名约定、属性标准或 SDK/包装器模式都是客户指令——其优先级高于你在下文推断出的所有内容；请记录这些指令，并跳过它们已涵盖部分的推断。如果该文件不存在，则直接继续——instrument-events 技能负责提示用户添加该文件。

---

步骤 1：查找跟踪调用

根据可用情况，采用以下两种方法。

如果已连接 Amplitude MCP

检查已连接的目录，并使用当前的分类读取器从项目中获取一组事件名称样本。只遵循该读取器公开的架构。如果它支持调用方归因，请使用其 YAML frontmatter 中的 name 标识此技能。使用这些结果选取几个具有代表性的非系统产品事件，然后使用其事件属性读取功能检查实际属性名称。这是你的主要命名参考。

不要根据带方括号前缀的 Amplitude 系统名称推断事件或属性的命名约定，例如 [Amplitude]、[Guides-Surveys]、[Assistant]、[Experiment]。如果 MCP 样本以 Amplitude 系统名称为主，或无法提供足够证据，请改为从代码库推断命名方式。

然后在代码库中使用 Grep 搜索抽样得到的非系统事件名称，以定位实际的跟踪调用位置。

如果 Amplitude MCP 不可用（备用方案）

使用 Grep 在代码库中搜索以下信号。尽量扩大搜索范围，之后再缩小：

搜索内容	原因
\.track\(	通用的 .track() 方法调用
ampli\.	Ampli 类型化 SDK 调用（例如 ampli.myEvent(...)）
amplitude\.track|amplitude\.logEvent	直接调用 Amplitude SDK
sendEvent	自定义封装方法名称
from.*amplitude|import.*amplitude|require.*amplitude	导入语句
https://api2\.amplitude\.com/2/httpapi	HTTP API 调用

还要主动查找自定义分析封装——代码库通常会将原始 SDK 封装在 trackEvent()、track() 之类的工具函数中，或封装在 useAnalytics()、useTracking() 之类的 React hook 中。搜索内部调用 Amplitude 的函数，以找到这些封装。将每个封装视为独立模式，与底层 SDK 调用分开记录，即使它最终在底层调用了 amplitude.track() 也是如此。遇到封装的工程师会使用封装本身，而不是原始 SDK，因此这是更重要的待记录模式。

查找封装：搜索导入 Amplitude SDK 的文件，然后检查这些文件是否导出了其他代码会导入并用于追踪的函数或 hook。

排除测试文件（.test.、.spec.、__tests__）和模拟文件，除非某个模式只出现在这些文件中。

---

第 2 步：按模式分组

如果多个调用点使用相同的以下内容，则属于同一模式：

• 被调用的库／SDK／函数
• 方法名称
• 参数结构（即使事件名称或属性不同）

例如，以下属于同一模式：

amplitude.track('Page Viewed', { page: '/home' })
amplitude.track('Button Clicked', { label: 'signup' })

但以下属于不同模式——始终分开记录：

amplitude.track('Page Viewed', { page: '/home' })   // direct SDK — one pattern
ampli.pageViewed({ page: '/home' })                  // Ampli typed method — different pattern
trackEvent('Page Viewed', { page: '/home' })         // custom wrapper — also a separate pattern

自定义封装始终属于独立模式，即使它在底层调用了 SDK。记录封装模式时，请说明它封装了什么（例如，“封装 amplitude.track() 的自定义 hook”），以便工程师了解其分层关系。

步骤 3：确定命名约定

分别确定以下两种约定：

• event_naming_convention —— 埋点代码中事件名称的大小写形式、分隔符、词序、前缀和时态。例如：Title Case、snake_case、[Prefix] Action、对象优先还是动作优先。
• property_naming_convention —— 事件属性使用的大小写形式、分隔符和常见后缀／前缀模式。例如：snake_case、camelCase、*_id、is_*、扁平键还是嵌套对象。

按以下优先顺序处理：

1. 首先查看仓库埋点上下文。 如果 .amplitude/instrumentation-agent-context.md（来自步骤 0）明确说明了事件或属性命名约定，则以其为准——记录该约定，并跳过对已明确说明部分的推断。只有在文件不存在或未提及命名约定时，才继续往下查找。
2. 其次查看 Amplitude MCP。 如果活动 taxonomy reader 返回的少数代表性非系统事件中，观察到的事件名称和属性名称呈现出明显的主流约定，就采用该约定。不要将带方括号前缀的 Amplitude 系统名称作为命名依据。
3. 第三步查看代码库。 如果 MCP 证据不可用、过少或不一致，就根据仓库中附近真实的埋点调用位置，推断主流约定。如果代码库中存在多种约定，指出其中的主流约定，并说明重要的局部例外。
4. 最后回退到 taxonomy。 如果以上来源都不足以明确结论，就使用 ../taxonomy/SKILL.md 中的 taxonomy 技能。

不要猜测。如果检查这些来源后，仍有一项或两项约定不明确，请明确说明。

---

步骤 4：输出

先简要说明约定，然后列出每种独特模式。

event_naming_convention: "<from repo context file if it specifies one, else MCP if clear, else codebase, else taxonomy skill, or 'insufficient evidence'>"
property_naming_convention: "<from repo context file if it specifies one, else MCP if clear, else codebase, else taxonomy skill, or 'insufficient evidence'>"

接着，为每种独特模式按以下格式输出一个章节：

---

模式：<简短的描述性名称>

描述：说明此模式的作用，以及它在此代码库中的典型用途（例如：“用于 React 前端各处的用户操作跟踪”）。

示例（泛化后）：

// show the import(s) needed
import { amplitude } from '@/lib/analytics'

// show a representative tracking call with placeholder names
amplitude.track('Event Name', {
  propertyOne: value,
  propertyTwo: value,
})

相关路径：

• src/path/to/file.ts
• src/another/file.tsx

---

按模式出现频率（涉及的文件路径数）从高到低列出。

如果两种模式总是一起使用（例如，导入 + 调用），请在同一个示例中展示。

---

步骤 5：处理无结果的情况

如果使用任何搜索策略都未找到埋点调用，请明确说明。建议用户检查项目是否已设置 Amplitude（或其他分析库），并在相关时主动提出搜索其他分析库（如 Segment、Mixpanel、PostHog 等）。