discover-analytics-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

discover-analytics-patterns

Your goal is to find out how this codebase sends analytics events — not which events exist, but the specific code patterns engineers use to fire a tracking call. This output helps engineers add new events that look consistent with the rest of the codebase. It should also tell downstream skills how event names and property names are typically written in code here.

When determining naming conventions in this skill, use the following sources in strict order of preference:

Customer directives in
```
.amplitude/instrumentation-agent-context.md
```
(and any files it references), if present — explicit conventions the customer wants followed, so they override everything below.
Events and properties observed from the Amplitude MCP server
Real tracking call sites in the codebase
The
```
taxonomy
```
skill at
```
../taxonomy/SKILL.md
```

你的目标是找出该代码库发送分析事件的方式——不是存在哪些事件，而是工程师触发跟踪调用时使用的具体代码模式。输出内容可帮助工程师添加与代码库其余部分风格一致的新事件，同时也能告知下游技能，代码中事件名称和属性名称的典型编写方式。

确定本技能中的命名规范时，请严格按照以下优先级顺序参考来源：

若存在
```
.amplitude/instrumentation-agent-context.md
```
（及其引用的任何文件），优先遵循其中的客户指定规则——这是客户要求遵循的明确规范，优先级高于以下所有内容。
从Amplitude MCP服务器获取的事件和属性
代码库中的实际跟踪调用站点
```
../taxonomy/SKILL.md
```
中的
```
taxonomy
```
技能

Step 0: Read repo instrumentation context

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

Before anything else, check for

.amplitude/instrumentation-agent-context.md

(repo root, or the subdirectory you're instrumenting). If it exists, read it and any repo-relative files it references. Any naming conventions, property standards, or SDK/wrapper patterns it states are customer directives — they take precedence over everything you infer below; record them and skip inference for whatever they cover. If it's absent, just continue — the

instrument-events

skill owns prompting the user to add one.

在开始任何操作前，检查是否存在

.amplitude/instrumentation-agent-context.md

（代码库根目录或你正在埋点的子目录）。如果存在，读取该文件及其引用的所有相对路径文件。其中规定的任何命名规范、属性标准或SDK/包装器模式均为客户指定规则——优先级高于你后续推断的所有内容；记录这些规则，并跳过对应内容的推断。如果该文件不存在，直接继续——

instrument-events

技能会提示用户添加该文件。

Step 1: Find tracking calls

步骤1：查找跟踪调用

Use two approaches based on what's available.

根据可用资源采用两种方法。

If the Amplitude MCP is connected

若已连接Amplitude MCP

Call

get_events

(or equivalent) to fetch a sample of event names from the project. If its input schema accepts

_client

, every

get_events

call made by this skill MUST include the top-level argument

"_client": { "type": "skill", "skill_name": "discover-analytics-patterns" }

in the tool arguments; otherwise, omit

_client

. Use those results to choose a few representative non-system product events, then call

get_properties

for those events to inspect real property names. This is your primary naming reference.

Do not infer naming conventions from bracket-prefixed Amplitude system names such as

[Amplitude], [Guides-Surveys], [Assistant], [Experiment]

for either events or properties. Exclude those from pattern detection. If the MCP sample is dominated by Amplitude system names or otherwise does not provide enough evidence, fall back to codebase inference for naming.

Then search the codebase for the sampled non-system event names using Grep to locate the actual tracking call sites.

调用

get_events

（或等效方法）获取项目中的事件名称样本。如果其输入模式接受

_client

，本技能发起的所有

get_events

调用必须在工具参数中包含顶层参数

"_client": { "type": "skill", "skill_name": "discover-analytics-patterns" }

；否则，省略

_client

。利用结果选择几个有代表性的非系统产品事件，然后调用

get_properties

查看这些事件的实际属性名称。这是你的主要命名参考。

请勿从带方括号前缀的Amplitude系统名称（如

[Amplitude], [Guides-Surveys], [Assistant], [Experiment]

）推断事件或属性的命名规范。将这些名称排除在模式检测之外。如果MCP样本主要是Amplitude系统名称，或无法提供足够有效证据，则退回到代码库推断命名规范。

然后使用Grep在代码库中搜索选定的非系统事件名称，定位实际的跟踪调用站点。

If the Amplitude MCP is not available (fallback)

若未连接Amplitude MCP（备用方案）

Search the codebase for these signals using Grep. Cast a wide net — you can narrow down after:

What to search for	Why
`\.track\(`	Generic `.track()` method calls
`ampli\.`	Ampli typed SDK calls (e.g. `ampli.myEvent(...)` )
`amplitude\.track\|amplitude\.logEvent`	Direct Amplitude SDK calls
`sendEvent`	Custom wrapper method names
`from.amplitude\|import.amplitude\|require.*amplitude`	Import statements
`https://api2\.amplitude\.com/2/httpapi`	HTTP API calls

Also actively look for custom analytics wrappers — a codebase often wraps the raw SDK in a utility like

trackEvent()

track()

, or a React hook like

useAnalytics()

useTracking()

. Search for these by looking for functions that call into Amplitude internally. Treat each wrapper as its own pattern, separate from the underlying SDK call, even if it ultimately calls

amplitude.track()

underneath. Engineers who encounter the wrapper will use it, not the raw SDK — so it's the more important pattern to document.

To find wrappers: search for files that import the Amplitude SDK, then check whether any of those files export a function or hook that other parts of the codebase import and use for tracking.

Exclude test files (

.test.

.spec.

__tests__

) and mock files unless they are the only place a pattern appears.

使用Grep在代码库中搜索以下信号。先广泛搜索，之后再缩小范围：

搜索内容	原因
`\\.track\\(`	通用 `.track()` 方法调用
`ampli\\.`	Ampli 类型化 SDK 调用（例如 `ampli.myEvent(...)` ）
`amplitude\.track\	amplitude\.logEvent`
`sendEvent`	自定义包装器方法名称
`from.*amplitude\	import.*amplitude\
`https://api2\\.amplitude\\.com/2/httpapi`	HTTP API 调用

同时要主动寻找自定义分析包装器——代码库通常会将原始SDK包装在

trackEvent()

、

track()

或React钩子（如

useAnalytics()

或

useTracking()

）等工具中。通过查找内部调用Amplitude的函数来定位这些包装器。将每个包装器视为独立的模式，与底层SDK调用区分开，即使它最终调用的是

amplitude.track()

。工程师接触到包装器后会使用它，而非原始SDK——因此记录包装器模式更为重要。

查找包装器的方法：搜索导入Amplitude SDK的文件，然后检查这些文件是否导出了代码库其他部分导入并用于跟踪的函数或钩子。

排除测试文件（

.test.

、

.spec.

、

__tests__

）和模拟文件，除非它们是某模式出现的唯一位置。

Step 2: Group by pattern

步骤2：按模式分组

Two call sites use the same pattern if they share the same:

Library/SDK/function being called
Method name
Argument structure (even if the event name or properties differ)

For example, these are the same pattern:

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

But these are different patterns — always keep them separate:

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

A custom wrapper is always its own pattern, even if it delegates to the SDK underneath. When documenting a wrapper pattern, note what it wraps (e.g., "Custom hook wrapping

amplitude.track()

") so engineers understand the layering.

如果两个调用站点满足以下条件，则属于同一模式：

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

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

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

但以下属于不同模式——务必分开记录：

amplitude.track('Page Viewed', { page: '/home' })   // 直接调用SDK —— 一种模式
ampli.pageViewed({ page: '/home' })                  // Ampli类型化方法 —— 另一种模式
trackEvent('Page Viewed', { page: '/home' })         // 自定义包装器 —— 也是独立模式

自定义包装器始终是独立模式，即使它底层调用的是SDK。记录包装器模式时，需注明它包装的内容（例如“包装

amplitude.track()

的自定义钩子”），以便工程师理解层级关系。

Step 3: Resolve naming conventions

步骤3：确定命名规范

Resolve two conventions separately:

```
event_naming_convention
```
— casing, separators, word order, prefixes, and tense used for event names in instrumentation code. Examples:
```
Title Case
```
,
```
snake_case
```
,
```
[Prefix] Action
```
, object-first vs action-first.
```
property_naming_convention
```
— casing, separators, and common suffix/prefix patterns used for event properties. Examples:
```
snake_case
```
,
```
camelCase
```
,
```
*_id
```
,
```
is_*
```
, flat keys vs nested objects.

Use this precedence order:

Repo instrumentation context first. If
```
.amplitude/instrumentation-agent-context.md
```
(from Step 0) states an explicit event or property naming convention, it wins outright — record it and skip inference for whatever it specifies. Only fall through when the file is absent or silent on naming.
Amplitude MCP second. If the observed
```
eventType
```
values and property names returned by
```
get_properties
```
for a few representative non-system events show a clear dominant convention, use that. Do not use bracket-prefixed Amplitude system names as naming evidence.
Codebase third. If the MCP evidence is unavailable, sparse, or inconsistent, infer the dominant convention from nearby, real tracking call sites in the repository. If the codebase shows multiple conventions, call out the dominant one and note meaningful local exceptions.
Taxonomy fallback last. If none of the above is clear enough, fall back to the
```
taxonomy
```
skill at
```
../taxonomy/SKILL.md
```
.

Do not guess. If one or both conventions remain unclear even after checking those sources, say so explicitly.

分别确定两种规范：

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

遵循以下优先级顺序：

优先参考代码库埋点上下文。如果
```
.amplitude/instrumentation-agent-context.md
```
（来自步骤0）明确规定了事件或属性命名规范，则直接采用——记录该规范并跳过对应内容的推断。仅当文件不存在或未提及命名规范时，才参考后续来源。
其次参考Amplitude MCP。如果从
```
get_properties
```
获取的几个代表性非系统事件的
```
eventType
```
值和属性名称显示出明确的主流规范，则使用该规范。请勿将带方括号前缀的Amplitude系统名称作为命名依据。
再次参考代码库。如果MCP证据不可用、不足或不一致，则从代码库中实际的跟踪调用站点推断主流规范。如果代码库存在多种规范，需指出主流规范并记录有意义的局部例外情况。
最后参考分类技能。如果以上来源均无法提供足够清晰的依据，则退回到
```
../taxonomy/SKILL.md
```
中的
```
taxonomy
```
技能。

请勿猜测。如果经过以上步骤后，一种或两种规范仍不明确，请明确说明。

Step 4: Output

步骤4：输出内容

Start with a short conventions section, then list each unique pattern.

yaml

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'>"

Then, for each unique pattern, output a section in this format:

先写简短的规范部分，再列出每个独特模式。

yaml

event_naming_convention: "<若代码库上下文文件有规定则使用，否则若MCP有明确规范则使用，再否则参考代码库，最后参考分类技能，或填写'证据不足'>"
property_naming_convention: "<若代码库上下文文件有规定则使用，否则若MCP有明确规范则使用，再否则参考代码库，最后参考分类技能，或填写'证据不足'>"

然后，针对每个独特模式，按以下格式输出章节：

Pattern:

<short descriptive name>

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

Description: What this pattern does and when it's typically used in this codebase (e.g., "Used throughout the React frontend for user action tracking").

Example (generalized):

// 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,
})

Relevant paths:

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

List patterns from most common (most file paths) to least common.

If two patterns are always used together (e.g., an import + a call), show them together in one example.

说明：该模式的作用以及在代码库中的典型使用场景（例如“用于React前端的用户行为跟踪”）。

示例（通用化）：

// 显示所需的导入语句
import { amplitude } from '@/lib/analytics'

// 显示带占位符名称的代表性跟踪调用
amplitude.track('Event Name', {
  propertyOne: value,
  propertyTwo: value,
})

相关路径：

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

按使用频率从高到低（文件路径数量从多到少）列出模式。

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

Step 5: Handle no results

步骤5：处理无结果情况

If no tracking calls are found with any search strategy, say so clearly. Suggest that the user check whether Amplitude (or another analytics library) has been set up in the project, and offer to search for other analytics libraries (Segment, Mixpanel, PostHog, etc.) if relevant.

如果通过任何搜索策略均未找到跟踪调用，请明确说明。建议用户检查项目是否已设置Amplitude（或其他分析库），并根据情况提出搜索其他分析库（Segment、Mixpanel、PostHog等）的建议。",