discover-analytics-patterns

discover-analytics-patterns

このコードベースで分析イベントがどのように送信されるかを把握することが目的です。どのイベントが存在するかではなく、エンジニアがトラッキング呼び出しを行う際に使っている具体的なコードパターンを調べます。この出力は、エンジニアがコードベースの既存のパターンに沿って新しいイベントを追加するのに役立ちます。また、イベント名やプロパティ名がこのコードベースで通常どのように記述されるかを、後続のスキルに伝える必要があります。

このスキルで命名規則を判断するときは、次の情報源を優先順位の高い順に使用してください。

1. .amplitude/instrumentation-agent-context.md（およびそこから参照されるファイル）に記載された顧客の指示（存在する場合）。顧客が従うことを希望する明示的な規則であり、以下のすべてに優先します。
2. Amplitude MCP サーバーから確認できるイベントとプロパティ
3. コードベース内の実際のトラッキング呼び出し箇所
4. ../taxonomy/SKILL.md にある taxonomy スキル

---

ステップ 0：リポジトリの計測コンテキストを読む

何よりも先に、.amplitude/instrumentation-agent-context.md が存在するか確認してください（リポジトリのルート、または計測対象のサブディレクトリ）。存在する場合は、そのファイルと、そこから参照されるリポジトリ相対パスのファイルを読みます。そこに記載された命名規則、プロパティ標準、SDK／ラッパーのパターンはすべて顧客の指示であり、以下から推測する内容より優先されます。記録したうえで、指示が適用される範囲については推測を省略してください。存在しない場合は、そのまま続行してください。ユーザーに追加を促す役割は instrument-events スキルが担います。

---

ステップ 1：トラッキング呼び出しを探す

利用可能な情報に応じて、次の 2 つの方法を使ってください。

Amplitude MCP に接続されている場合

接続済みのカタログを調べ、現在のタクソノミーリーダーを使って、プロジェクトのイベント名のサンプルを取得してください。リーダーが提示するスキーマに従ってください。呼び出し元の識別に対応している場合は、このスキルの YAML フロントマターにある name を使って、このスキルを識別してください。取得した結果から、システムイベント以外の代表的なプロダクトイベントをいくつか選び、イベントプロパティの読み取り機能を使って実際のプロパティ名を調べてください。命名規則を判断するうえで、これは最優先の参照情報です。

イベント名とプロパティのどちらについても、[Amplitude], [Guides-Surveys], [Assistant], [Experiment] のように角括弧で始まる Amplitude システム名から命名規則を推測しないでください。パターン検出から除外してください。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 フックでラップしていることがよくあります。Amplitude を内部で呼び出している関数を探して、これらを検索してください。各ラッパーは、最終的に内部で amplitude.track() を呼び出している場合でも、基盤となる SDK 呼び出しとは別個のパターンとして扱ってください。 ラッパーを使うエンジニアは生の SDK ではなく、ラッパーを使うため、ドキュメント化するうえではこちらのパターンのほうが重要です。

ラッパーを見つけるには、Amplitude SDK をインポートしているファイルを検索し、そのファイルが、コードベースの他の部分からインポートされ、トラッキングに使われている関数やフックをエクスポートしているか確認してください。

パターンが現れる場所がそれらしかない場合を除き、テストファイル（.test.、.spec.、__tests__）とモックファイルは除外します。

---

ステップ 2：パターンごとに分類する

以下が共通している場合、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() をラップするカスタムフック）を記載してください。

Step 3: 命名規則を特定する

次の2つの規則を個別に特定します。

• 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を確認します。 有効なタクソノミーリーダーが返す、代表的な非システムイベントのイベント名とプロパティ名に明確な優勢パターンが見られる場合は、それを使います。角括弧で始まるAmplitudeのシステム名は、命名規則を判断する根拠にしないでください。
3. 3番目にコードベースを確認します。 MCPの情報を利用できない場合、情報が少ない場合、または一貫性がない場合は、リポジトリ内の近くにある実際のトラッキング呼び出し箇所から、優勢な規則を推測します。コードベースに複数の規則がある場合は、優勢な規則を示し、意味のあるローカルの例外にも言及します。
4. 最後にタクソノミーを代替手段として確認します。 上記のいずれからも十分に明確な規則を判断できない場合は、../taxonomy/SKILL.md にある taxonomy スキルを使用します。

推測してはいけません。これらの情報源を確認した後も、一方または両方の規則が不明確な場合は、その旨を明示してください。

---

Step 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

---

パターンは、最も一般的なもの（ファイルパスの数が最も多いもの）から順に列挙します。

2つのパターンが常に一緒に使われる場合（例：インポートと呼び出し）は、1つの例にまとめて示します。

---

Step 5: 結果がない場合の対応

どの検索方法でもトラッキング呼び出しが見つからなかった場合は、そのことを明確に伝えてください。Amplitude（または別の分析ライブラリ）がプロジェクトに設定されているか確認するようユーザーに提案し、必要に応じて他の分析ライブラリ（Segment、Mixpanel、PostHog など）も検索できることを伝えてください。