taxonomy

タクソノミーの生成とデータ監査

使用するタイミング

• ユーザーがトラッキングプランまたはイベントタクソノミーの作成やレビューを依頼した場合
• ユーザーがイベントやプロパティの命名規則を検証したい場合
• ユーザーがプランやブランチを「自社の標準」、命名設定、または AI Context に照らして監査またはレビューしたい場合
• ユーザーがデータ品質（重複、古いイベント、メタデータの欠落）を監査する必要がある場合
• ユーザーがファネル設計やイベント間の関係について質問した場合
• エージェントがイベント名やプロパティ名を生成する際に、標準に従う必要がある場合
• ユーザーがタクソノミーのガバナンスを理解または改善したい場合
• ユーザーがイベント数や種類数の削減について質問した場合
• ユーザーがイベントの非推奨化、ブロック、削除、非表示について質問した場合
• イベントを推奨する前に、タクソノミーのベストプラクティスを確認する「信頼できる情報源」が必要なエージェント
• ユーザーが AI 対応状況、AI Controls、または AI 機能の精度向上について質問した場合

---

レイヤー 1：基礎概念

中核となる理念

タクソノミーに関するすべての作業は、次の 6 つの原則に従います。

1. 証拠を最優先し、捏造しない。 すべての調査結果は、ツールから取得したデータに基づく必要があります。検証できないことは、必ずその旨を明示してください。
2. 徹底的にスキャンし、自信を持って提案し、書き込み前に確認する。 タクソノミー全体を自律的にページネーションして確認してください。修正が必要な点を優先順位付けし、明確な見解をまとめて提示します。ユーザーの明示的な確認なしに、書き込みツールを呼び出してはいけません。
3. 中立ではなく、明確な見解を示す。 「タクソノミーを監査して」といった一般的な依頼は、主導して進める機会です。スコアリングのフレームワークを使い、最も影響の大きいアクションを最初に推奨し、その理由を説明してください。どれも同等の選択肢として並べてはいけません。
4. 重大な問題は先回りして提示する。 関連する別の作業中に重要な問題を見つけた場合は、必ず報告してください。ユーザーが命名規則について尋ねただけだからといって、PII 違反を黙って無視してはいけません。
5. 質問を通じて組織の知識を引き出す。 Amplitude の仕組みではなく、ビジネス上の意図や現実世界での意味について尋ねてください。一度に尋ねる質問は 1 つに絞ります。目的は、人々の頭の中にある知識を引き出すことです。
6. 実行前に説明する。 書き込みツールを呼び出す前に、変更前と変更後の状態を含む具体的な変更案を提示し、明示的な確認を待ってください。

データ品質のライフサイクル

タクソノミーのガバナンスは、次の 4 段階のサイクルに従います。

1. 検出 — 体系的にスキャンします。タクソノミー全体をページネーションして確認します。すべての調査結果を評価します。結論を出す前に、証拠とともに問題を提示します。
2. 明確化 — 意味上の事実を把握するため、焦点を絞った質問を 1 つ尋ねます。まだアクションを提案してはいけません。まず理解を深めます。
3. 解決 — メタデータのみの改善を適用します。構造的な変更については、段階的な非推奨化を人間が進められるよう案内します。破壊的な操作を独断で実行してはいけません。
4. 予防 — 同じずれが繰り返されないよう、規約やガバナンスの習慣を推奨します。

イベント量と分類体系のタイプ数

これらは別々の問題であり、それぞれ異なる解決策が必要です。

• イベント量 ＝ 請求期間中に取り込まれたイベントインスタンスの合計数（イベントが発生した回数）。プロパティはイベント量に含まれません。
• 分類体系のタイプ数 ＝ すべてのスキーマの次元（イベントタイプ、イベントプロパティタイプ、ユーザープロパティタイプ、グループタイプ、グループプロパティタイプ）にわたる個別の名前の数。それぞれに独自の上限があります。

請求モデル — 案内する前に、どちらが適用されるか確認してください：

• イベント量に基づく請求：顧客には、請求期間ごとに契約上のイベント割り当て数があります。これを超過すると、超過料金が発生します。この顧客には、イベント量の大幅な変更を必ず伝えてください。
• MTU に基づく請求：顧客には、1 か月間にいずれかのイベントを発生させた個別ユーザー数に基づいて請求されます。ユーザーあたりのイベント数はそれほど重要ではなく、ユニークユーザーの合計数のほうが重要です。

顧客が通常意図していること：

• 「イベント量を減らしたい」→ 請求を懸念している（イベント量に基づく請求の顧客）
• 「イベントタイプ数／スキーマ数を減らしたい」→ タイプ上限への到達を懸念している（新しいタイプをクエリできなくなります）

それぞれを実際に減らす方法：

目標	操作	イベント量を減らす？	タイプ数を減らす？
イベント量を減らす	イベントをブロックする	はい	いいえ
イベント量を減らす	イベントを削除する	はい	はい
タイプ数を減らす	イベント／プロパティ／グループタイプを削除する	—	はい
タイプ数を減らす	イベントをブロックする	いいえ	いいえ
タイプ数を減らす	イベントを非表示にする	いいえ	いいえ

重要なルール：

• ブロックや非表示にしても、タイプ数は減りません。クォータに制約のある顧客には、ブロックではなく削除を案内してください。
• サンプリングは絶対に推奨しないでください。 サンプリングすると、ファネルチャート、ジャーニーパス、コホート、下流の宛先、Guides に支障が出ます。
• カスタムイベントと統合イベントは分析を簡素化しますが、生のイベント量は減らしません。
• 意図が曖昧な場合は、次のように尋ねてください：「送信されるイベントの数を減らしたいのか、それとも分類体系にある異なるイベントタイプとプロパティタイプの数を減らしたいのか、どちらでしょうか？」

イベントの状態とメタデータの権限

ステータス	意味	メタデータを編集できる？
Planned	トラッキングプランに登録済み。まだ計測されていません	はい
Live	データを継続的に受信中	はい
Blocked	新たな取り込みを停止。過去のデータにはアクセス可能	はい
Unexpected	データを受信中ですが、トラッキングプランには登録されていません	いいえ — まずトラッキングプランに追加する必要があります
Deleted	取り込みを停止。新しいチャートのドロップダウンから削除済み	いいえ — まず復元する必要があります

Unexpected イベントには特別な制限があります。 イベントをトラッキングプランに追加するまで、メタデータを更新できません。Unexpected イベントに遭遇した場合：

• 正当なイベントに見える場合（実際のプロダクト操作、一貫したイベント量）：まずトラッキングプランに追加してから、メタデータを適用するよう案内してください。
• 無効なイベントに見える場合（単日の急増、テスト用文字列、セキュリティスキャンによる痕跡）：標準の安全な非推奨化プロセスに沿って、非推奨化の候補として扱ってください。操作を推奨する前に、「正当だが文書化されていない」イベントと「実際に無効な」イベントを必ず区別してください。

アクティビティの状態は、非推奨化の判断材料ではありません。 Inactive とマークされたイベントは、意図されたとおりに動作しています。

実際の非推奨化の判断材料：

判断材料	解釈
最近のイベント量がない	イベントが古くなっています
最近のクエリがない	イベントが使われていません
両方に該当	非推奨化の有力な候補です

Planned イベント： イベント量とクエリがゼロなのは想定どおりです。代わりに、イベントの経過期間、Live イベントとの名前の重複、テスト用と思われる名前に基づいて評価してください。

カスタムイベント、ラベル付きイベント、マージされたイベント

いずれもイベント量を減らすものではありません。それぞれ動作が異なります。

• カスタムイベント（ce: プレフィックス、タイプ = custom）：分析を容易にするため、基になるイベントを論理的に組み合わせたものです。基になるイベントは引き続き存在し、個別に発生します。イベントの削除を推奨する前に、そのイベントがカスタムイベントの基礎として使われていないか、必ず確認してください。基になるイベントを削除すると、カスタムイベントが気付かないうちに機能しなくなる場合があります。許可される対応：定義が同じ重複したカスタムイベントの統合、名前・説明・カテゴリー・タグの改善。カスタムイベントを削除するとイベント量が減ると決して主張しないでください。
• ラベル付きイベント（ce: プレフィックス、タイプ = labeled）：Autocapture での使用を想定しており、別個のメタデータフラグによってカスタムイベントと区別されます。追加や削除によってイベント量に影響が生じることはありません。
• マージされたイベント（Transform/Merge）：マージ後、ソースイベントは分析で個別に利用できなくなります。結合したイベントの分析とソースイベントの個別分析の両方が必要な場合は、マージではなくカスタムイベントを推奨してください。許可される対応：意味が同じで、個別の分析が不要な重複イベントのマージ。マージするとイベント量が減ると決して主張しないでください。

保護対象のデータカテゴリー

命名規則からカテゴリーを特定する方法： 角括弧のプレフィックス（[...]）が付いたイベントには、一貫したパターンがあります。角括弧内のテキストが識別可能なサードパーティ製品のブランドであれば、インテグレーションです。それ以外は Amplitude のシステムイベントです。

Amplitude のシステムイベント（[Amplitude]、[Guides-Surveys]、[Experiment] など）：プラットフォームの機能に不可欠です。一般的なクリーンアップへの対応として、ブロック、削除、非表示、変更を推奨しないでください。

インテグレーションのプレフィックスが付いたデータ（[Appboy]、[Adjust]、[Intercom] など）：クリーンアップできますが、まずインテグレーション元で無効にすることを推奨してください。ネイティブイベントより優先度は低くなります。

Experiment のデータ： TTL や自動削除を推奨しないでください。削除すると、過去の Experiment の解釈に支障が出ます。

使用状況のシグナルの解釈

クエリ数には、ユーザーが作成したオブジェクト（チャート、ダッシュボード、ノートブック、コホート、メトリクス）での使用状況が反映されますが、AI ツール、Chat、Global Agent、MCP、Alerts は含まれません。クエリ数がゼロであることは、確認すべき強いシグナルですが、対応を確定するものではありません。

主なパターンは3つあります：

パターン	定義	対応
古いイベント	以前は取り込まれていたが、発生量が止まった	廃止する前に顧客に確認する
テストイベント	初回確認日 = 最終確認日で、発生は1日のみ	廃止の有力候補。ただし、まず確認する
発生しているがクエリされていないイベント	発生量はあるが、クエリ数はゼロ	確認対象として提示する。すぐに削除しない

対応しても安全なもの： 6～12か月間、発生量がないもの。クエリの利用があっても、そのクエリの結果はゼロです。

AI 対応

メタデータの整理やクリーンアップを、AI 対応の向上として位置付けてください。すべての AI 機能は、可視化された分類体系を評価してイベントを選択します。分類体系の品質が、AI の出力品質を直接左右します。

以下を AI の品質に関する問題として指摘してください：

• 説明のない、解釈しにくいイベント名 — AI が意味を解釈できません
• 重複または類似した名前のイベントが集中している — AI が誤って選択する可能性があります
• 実装に重点を置いた説明（例：「POST /purchase が 200 を返したときに発火」） — ユーザーが尋ねるのは行動に関する質問であり、バックエンドに関する質問ではありません
• 非推奨イベントが大量に引き続き表示されている — ノイズが増え、AI による誤選択につながります

イベントの説明の構成（順序どおり）：

1. 技術用語を使わない行動の定義 — ユーザーが行ったことを、平易な言葉で説明します
2. 発火条件 — 正確な条件、UI と API のどちらか、成功時のみか失敗時も含むか、ページ／URL のパターン
3. 区別点 — 名前が似ているイベントとの違い
4. 主なユースケース — ファネルのステップ、成功指標、主要な分析入力のいずれに当たるか
5. よく使用されるプロパティ — 最もよく検索されるプロパティを 2〜3 個、簡単な説明を添えて記載します
6. 技術的な詳細（任意）— 実装に関する注記、ソースシステム、エンドポイント

プロパティの説明： 明確な定義から始め、その後に値の例を記載します。例：「ユーザーが閲覧した商品のカテゴリです。例：'electronics'、'apparel'、'home & garden'。」

計測時の AI 対応：

• 表示名がなくても解釈できる、明確で説明的なイベント名とプロパティ名を選んでください。計測時に表示名を追加することは推奨しないでください。表示名が必要になるのは、元の名前がすでに定着していて、曖昧な場合に限られます。
• 上記の構成に従って説明を記述してください：技術用語を使わない行動の定義 → 発火条件 → 区別点 → 主なユースケース → よく使用されるプロパティ → 任意の技術的な詳細。
• コード化された値（SKU、ID、ステータスコード）を持つプロパティについては、コードを人が理解できるラベルに対応付けるルックアップテーブルの作成を推奨してください（Growth および Enterprise のお客様が利用できます）。

AI Controls の推奨事項：

• Organization context（10,000 文字）：全社的な標準、KPI の定義、標準用語、グローバルフィルター、会計年度カレンダー
• Project context（10,000 文字）：プロダクト固有のイベント／ファネル、プロジェクト固有の指標、セグメントの定義
• 監査結果を使って、これらの推奨事項を具体化してください。複数のイベントで繰り返し使われている専門用語や略語は、個々の説明だけでなく、組織／プロジェクトのコンテキストに記載してください。一貫した構造パターン（命名規則、イベントのグループ分け）は、AI が分類体系全体を解釈するのに役立つ、プロジェクトコンテキストとして有用です。

---

レイヤー 2：アクションタイプ別のルール

読み取りと分析を行う場合（常に安全）

読み取りと分析の操作にリスクはありません。自律的かつ明確に判断して進めてください。標準に照らして名前とメタデータを監査するには、以下の「顧客の標準に照らした監査」に従ってください。

どの標準が適用されるか

名前を監査、提案、レビューする前に、次の両方から顧客の標準を確認してください。

• Data → Settings naming conventions： ワークスペース設定の読み取り結果（eventNC、propertyNC）。 それぞれに大文字・小文字の形式があり、イベントには構造もあります（下の表を参照）。または、カスタム正規表現が設定されています。Data UI はこれらを適用します。設定が空、または none の場合、ルールはありません。
• AI Context： プロジェクトコンテキストの読み取り結果に含まれる組織レベルおよびプロジェクトレベルのテキストです。プロジェクトコンテキストは組織コンテキストに優先します。

次の順序で情報源を適用してください。後の情報源は、前の情報源で決まっていない部分のみを補います。

順序	情報源	適用対象
1	Data → Settings	イベント名とプロパティ名の大文字・小文字の形式および構造
2	AI Context（プロジェクト、次に組織）	設定で定められていないすべて：許可される値、必須プロパティ、接頭辞、略語、ブール値の命名、説明文の表現、カテゴリ
3	既存のタクソノミーで一貫して使用されている慣例	1～2で定まっていない部分
4	このスキルの標準（「新しい計測を推奨する場合」）	それでも定まっていない部分すべて

Data UI が確認する設定値は次のとおりです。

大文字・小文字の形式	形式	例	使用不可
upper_case	単語をスペースで区切り、すべて大文字	PLAY SONG、IS PREMIUM	小文字、_、-
lower_case	単語をスペースで区切り、すべて小文字	play song	大文字、_、-
title_case	単語をスペースで区切り、各単語の先頭を大文字	Song Played	_、-
sentence_case	単語をスペースで区切り、先頭の文字を大文字	Song played	_、-
camel_case	区切り文字なし、各単語の先頭を大文字	SongPlayed	スペース、_、-
lower_camel_case	区切り文字なし、最初の単語は小文字	songPlayed	スペース、_、-
snake_case	単語を _ でつなぎ、すべて小文字	song_played	大文字、スペース、-
custom	設定の正規表現に一致する必要があります

構造（イベントのみ）：noun_past = Song Played、past_noun = Played Song、 infinitive_noun = Play Song。

ルールを一つだけ選ぶのではなく、組み合わせて適用してください。AI Context のルールを Settings の形式に当てはめます。upper_case で is_ のブール値接頭辞が必須の場合は、IS （IS PREMIUM）となり、IS_PREMIUM にはなりません。

Settings と AI Context で名前の大文字・小文字の形式または構造が異なる場合は、Settings に基づいて名前を判定してください。 ユーザーが「当社の標準」と呼ぶ場合も、AI Context が自らを標準と呼ぶ場合も同様です。調査結果を示す前に、両方のルールを引用して矛盾を一度報告し、整合させることを推奨してください。矛盾を確認した後、ユーザーから指示があった場合に限り、AI Context のルールに切り替えてください。

どちらの情報源にもルールがない場合は、「顧客の標準が見つかりません — Amplitude のデフォルトを使用します」と伝え、このスキルの標準を使用してください。

顧客の標準に照らした監査

1. 上記の両方の情報源を読みます。レポートは、見つかったルールをそれぞれ情報源とともに記載して始めます。
2. 次に、Settings と AI Context の競合を報告します。競合は採点しません。
3. 対象範囲内のすべてのイベントとプロパティを、すべてのルールに照らして確認します。
4. 各違反は、次の形式で記載します。 <event or property>: <what's wrong>. Rules: <rule text> (<source>); <rule text> (<source>). Fix: <compliant value>. 重大度を定めるルールを含め、その項目が違反しているルールをすべて列挙します。<source> は次のいずれかです。 Data → Settings、project AI Context、org AI Context、existing convention、Amplitude default。
5. 「Scoring and Prioritizing Issues」に従って優先順位を付けます。顧客が宣言したルール（Settings または AI Context）への違反は影響度 MEDIUM とし、さらに名前が曖昧になる場合、または1つの概念が複数の名前に分かれる場合は HIGH とします。 指摘を HIGH と評価する場合、Rules リストには HIGH とした根拠のルールを含める必要があります。概念が分かれている場合は、その分割に該当する各項目に「one name per concept (Amplitude default)」を記載します。
6. 修正案は、トラッキングプランのブランチに対する1つの変更セットとして提示します。ユーザーの確認後、新しいブランチ、またはユーザーが指定したブランチに適用します。main には適用せず、レビューとマージは顧客に委ねます。
   • 予定されているイベントとプロパティ：ブランチ上で名前を変更します。
   • ライブ（取り込み済み）の名前はメタデータ上で変更できません。それぞれ、準拠する名前を記載した計測変更として列挙し、工数を High とします。表示名の変更は一時的な回避策にすぎません。
   • 説明、カテゴリー、許容値、必須プロパティはブランチに反映します。
7. プロジェクトの Data → Settings の命名規則が none（命名ルールなし）で、AI Context に、ケーシング表の値のいずれかで正確に表現できる命名ルールがある場合、レポートの最後に、管理者にその値を Data → Settings に設定するよう推奨します。値は正確に記載します。例：イベントは sentence_case + infinitive_noun、プロパティは lower_camel_case。Data UI は Settings に照らして名前を確認しますが、AI Context は確認しません。既存の名前が一致しない場合、Data UI で違反として表示されることを警告します。設定にすでに値がある場合（競合として報告します）、また、許容値、必須プロパティ、プレフィックスなど、設定で表現できないルールの場合は、この手順を省略します。

メタデータの作成または更新時

すべての書き込みで事前・事後の確認が必要です。 自動適用は行いません。確認された項目だけを更新し、パターンから推測して類似項目にまで適用しないでください。

フィールドごとの既定値：

• 説明： 明らかな誤りでない限り、既存の内容を削除しないでください。既存の詳細に追記するか、取り込んでください。
• カテゴリー： 空の場合にのみ設定します。明らかに誤っている場合、またはユーザーが依頼した場合に限り、変更を提案します。
• タグ： 追加のみとし、明示的な依頼なしに削除しないでください。
• 表示名： プロジェクトで既存の命名規則に従います。

制限事項：

• 明示的な依頼がない限り、角括弧で始まるイベントやベンダーのプレフィックスが付いたイベントには書き込まないでください。
• Unexpected または Deleted イベントには書き込まないでください（先にプランへの追加、または復元が必要です）。

権限が原因で書き込みに失敗した場合：

• ユーザーに書き込み権限がないことを説明します。
• 実施可能な対応とその理由について、読み取り専用の案内を提供します。
• ユーザーが共有できる「Ask an Admin to apply this」の要約を提示します。

クリーンアップまたは非推奨化を推奨する場合

非推奨化は必ず段階的なプロセスに従います。削除を中心とした監査では、tracking-plan-audit スキルを使用します。

禁止事項：

• 削除、非表示、ブロックを、即時に実施する単一ステップの解決策として提示すること
• サンプリング、TTL、自動削除ルール、イベントのプロジェクト間移動を推奨すること
• ボリューム制御を目的として、上流の連携を再設定することを推奨すること
• 非推奨化を推奨する前に依存関係を確認する手順を省略すること

新たな計測を推奨する場合

これらは Amplitude の既定値です。顧客にルールがある場合（「Whose Standard Applies」を参照）、顧客のルールを優先します。

イベント命名規則

形式：タイトルケースの「[オブジェクト] [過去形の動詞]」

良い例	悪い例	理由
Song Played	Play Song	過去形は完了したアクションを表します
Form Submitted	Submit Form	名詞を先にすることで、一覧で見つけやすく、並べ替えやすくなります
Product Added	product added、product_added、productAdded	Amplitude は大文字・小文字の異なる表記を別のイベントとして扱います。必ずタイトルケースを使い、snake_case や camelCase は使わないでください

一貫性を最優先してください。 顧客に命名規則がなくても、タクソノミーで理想とは異なる規則が一貫して使われている場合は、新しいパターンを持ち込まず、その規則に合わせてください。

システム視点ではなく、ユーザー視点で命名します：

• Message Delivered（システムが配信）ではなく、Message Sent（ユーザーが送信）
• Payment Processed（システムが処理）ではなく、Purchase Completed（ユーザーが完了）

具体性のバランス — イベントを増やさず、1つのイベントとプロパティを使います：

• 良い例：プロパティ payment_method を持つ Order Completed
• 悪い例：Credit Card Order Completed、Apple Pay Order Completed

クロスプラットフォームでの一貫性： 同じユーザーアクションには、Web、iOS、Android で同じイベント名を使います。プラットフォームの違いは platform プロパティに記録します。

1つのアクションには1つのイベント名を使います。 コードベース内で重複させないでください。

オートキャプチャを優先します： Page Viewed、Element Clicked、Element Changed、Form Started など、すでにオートキャプチャで取得されているものに対して、カスタムイベントを推奨しないでください。

プロパティ命名規則

• すべてのプロパティ名に snake_case を使用します
• 説明的で具体的な名前にします： type ではなく payment_type、message ではなく error_message
• 単位が曖昧な場合は含めます： video_duration_seconds、file_size_mb、price_usd
• タイムスタンプの規則： [event_name]_at（例：product_added_at）
• イベント間で一貫させます： 同じ概念には、どのイベントでも同じプロパティ名を使います。product_name はすべてのイベントで product_name とし、name や prod_name などは使いません
• 異なる概念には異なる名前を使います： login_method と payment_method を使い、両方に汎用的な method は使いません
• ドット記法： ネストされたオブジェクトが渡されたことを意味します（Amplitude が自動的に作成します）。ネストされたオブジェクトを意図する場合を除き、プロパティ名にドット記法を直接使わないでください。監査時にドット記法のプロパティが集中している場合は、整理が必要な兆候です。実際にクエリで使われているものを確認してください。未使用のものがかなりの割合を占める場合は、タクソノミーのノイズを減らすため、データソース側でオブジェクトを絞り込むことを推奨します。

プロパティ型の規則

型	形式	例
ID	常に文字列	"user_id": "12345"。12345 ではありません
件数／金額	数値	"order_total": 59.99
フラグ	ブール値	"is_premium": true
タイムスタンプ	ISO 8601 形式の文字列	"2024-03-10T14:30:00Z"
列挙値／ステータス	文字列	"status": "In Progress"
null の扱い	プロパティごとに1つの方法を選びます	省略、null、または "Unknown" のようなセンチネル文字列のいずれかを使い、混在させないでください。明示的なセンチネル文字列を使うと、意図的に利用できない値と計測の不具合を区別できます。null の扱いに一貫性がないことは、プロパティフィルターの誤りやファネルの破損を引き起こす最も一般的な原因の1つです。

ユーザー識別の規則

• 匿名ユーザー： device_id のみを設定します。user_id は設定しないでください。
• 認証済みユーザー： 確認済みのユーザーごとに、一意で安定した user_id を設定します。ログイン／確認の前に設定しないでください。
• サーバーサイドイベント： 重複排除のため、イベントごとに一意の insert_id を含めます（7日間のウィンドウ）。
• セッション： セッション内では一貫した session_id を使います。サーバーサイドでは、最初のセッションイベントの UNIX タイムスタンプを使用します。

構造パターン

• A/B 実験： イベントではなく、リスト形式のユーザープロパティとして記録します
• エラー： error_type／error_categoryプロパティを持つ単一のError Encounteredイベントを使用します
• Eコマース： product_engagement（このアクションのアイテム）とcart_contents（カート全体のスナップショット）の配列を使用します
• B2B： 少なくとも1種類のグループ（org_id、account_id）を計測します
• ファネルのプロパティ一貫性： ファネル内のすべてのイベントで、同じプロパティ（例：product_id）を記録します

カテゴリの割り当て

Amplitude のカテゴリメタデータフィールドを使用し、イベント名に接頭辞を埋め込まないでください。一般的なカテゴリは次のとおりです。

カテゴリ	目的	例
Lifecycle	ユーザージャーニーの節目	Signup Completed, Trial Started, Subscription Cancelled
Feature	中核的な製品機能	Task Created, Document Edited, Report Generated
Engagement	ナビゲーションとUI操作	Page Viewed, Button Clicked, Search Performed
Transaction	収益イベント	Purchase Completed, Checkout Started, Refund Requested
System	技術的な健全性	Error Occurred, API Request Completed, Timeout Occurred
Growth	獲得と紹介	Invite Sent, Share Completed, Referral Reward Earned

割り当てのヒューリスティック：

• イベントが初回または節目となるユーザーアクション（サインアップ、初回購入、初回招待）を表す場合は、FeatureやTransactionよりもLifecycleを優先します。
• イベントが中核的な製品アクションではないクリックや閲覧を記録する場合は、FeatureよりもEngagementを優先します。
• インテグレーション由来のイベント（[Appboy]、[Adjust]など）は、明確に分類しにくい場合があります。インテグレーションの目的に応じてSystemまたはGrowthを割り当てるか、未割り当てのままにします。
• 適切なカテゴリが曖昧な場合は、推測せず顧客に確認します。

問題のスコアリングと優先順位付け

3つの観点：

1. 問題の影響度

レベル	点数	定義	例
HIGH	3	名前が曖昧で、アナリストが確実に解釈できない	専門用語、頭字語、意味の曖昧な語、混同しやすい名前
MEDIUM	2	名前は解釈できるが、分類体系が乱雑になる	顧客が宣言した標準からの逸脱、命名規則の例外、計画にない予期しないイベント
LOW	1	名前は明確で、問題は仕上げの不足に限られる	名前から明らかな場合の説明の欠如

2. イベントの重要度

• クエリ頻度： 30／60／90／180日間の件数。クエリ頻度の高いイベントは、より多くの分析に影響します
• ボリューム： ボリュームが大きいほど、コストとリスクが増加します
• 初回確認日： ごく最近の場合、問題が積み重なる前に早期に検証します
• 最終確認日： 古い場合、陳腐化の兆候です

3. 作業量

• 低： メタデータのみの変更（説明、表示名、カテゴリ、タグ、非表示設定）
• 中： 関係者の確認または依存関係のチェックが必要
• 高： コードベースの変更またはインテグレーションの再設定が必要

優先順位付け： 重要度の高いイベントに関する影響度の大きい問題から着手します。古いイベントやテストイベントはすぐに対処できます。実際のデータ品質の問題より下位に提示してください。

健全性評価：（獲得ポイント合計／獲得可能ポイント合計）x 100%

• 0-49%：改善が必要
• 50-79%：期待どおり
• 80-100%：期待を上回る

権限の境界（メタデータのみ）

許可される操作（非破壊的なメタデータのみ。ユーザーの承認が必要）：

• 表示名、説明、カテゴリ、タグを更新する
• 公式ステータスを設定する
• イベントを非表示にする（ブロックや削除はしない）
• Automated Tasks を設定する
• プロジェクト設定に AI Context を追加する
• 顧客がレビューしてマージするブランチでトラッキングプランを編集する（計画的な名前変更、許可値、必須プロパティ）

許可されない操作：

• イベントのブロック、削除、統合、変換
• Block／Drop フィルター
• 取り込みパイプラインまたは上流のインテグレーションの変更
• あらゆる種類のサンプリング戦略

---

レイヤー3：検出リファレンス

検出シグナルとしきい値

デフォルトの参照期間：180日。

シグナル	優先度	対応
意味が不明瞭な名前	HIGH	表示名と説明を追加
説明の欠落（名前が不明瞭）	HIGH	AI 対応の数式に従って説明を追加
意味上の重複（真の重複 — 大文字・小文字の違いのみ）	HIGH	統合するか、区別できるようにする
意味上の重複（類似 — 名前は異なるが、同じ操作）	HIGH	調査し、統合するか、区別できるようにする
ボリュームがゼロ（180日）	MEDIUM	対応する前に調査
クエリがゼロ（180日）	MEDIUM	まずアセットの依存関係を確認
イベントスコープとユーザースコープでプロパティが重複	MEDIUM	正しい信頼できる情報源を明確化
説明の欠落（名前は明確）	LOW	説明を追加。優先度は低く設定
カテゴリの欠落	LOW	カテゴリを追加
顧客が宣言したルールに違反（Data → Settings または AI Context）	MEDIUM	ブランチで修正し、ルールとその出典を明記
顧客の許可リストにない値	MEDIUM；取り込み済みデータですでにその値が使われている場合は HIGH	ブランチで許可値を修正し、想定外の値を何に対応付けるべきか確認
命名規則からの逸脱（顧客ルールなし）	LOW	今後の調整事項として記録
想定外のイベント／プロパティ	LOW	確認後、計画に追加するかブロック
古い（最終確認が参照期間より前）	LOW	手早く対処できる項目 — 廃止を予定
1日のみ（初回確認 = 最終確認）	LOW	手早く対処できる項目 — テストの可能性が高いため、まず確認
テスト／QA 用のアーティファクト（test_、debug_、tmp_、_qa）	LOW	手早く対処できる項目 — 標準の廃止プロセスに従う

例外： 顧客がクォータの上限に近い場合、「古い」「1日のみ」「テスト」のシグナルの優先度を引き上げます。

主要な監査指標

指標	影響
クォータ上限に達しているタイプの割合	90% 超の場合は HIGH
過去7日間に追加された新しいタイプの数（急増は動的値の漏えいの可能性）	急増時は HIGH
過去7日間のイベント総ボリュームの変化	予期しない変化の場合は HIGH
名前が重複するタイプの数	HIGH
インストルメンテーションされていないグループタイプ（B2B 製品）	HIGH
ユーザープロパティではなくイベントとして記録された A/B 実験	MEDIUM
過去180日間にクエリがゼロのイベント数	MEDIUM
過去180日間にボリュームがゼロのイベント数	MEDIUM
1日のみのイベント数	MEDIUM
説明が設定されたライブイベントの割合	LOW
カテゴリが設定されたライブイベントの割合	LOW
想定外のイベント／プロパティの数	LOW
命名規則の不整合	LOW

メタデータの適切な例と不適切な例

表示名：

変更前	変更後
catSelectClick	Category Selected
pgVw	Page Viewed
ord_compl_v2	Order Completed
usr_prop_acct_tier	Account Tier

説明：

不適切（実装に注目）	適切（意図とコンテキスト）
「ナビゲーションコンポーネントのクリックハンドラーで発火」	「顧客がナビゲーションメニューから商品カテゴリを選択したときに発火します。カテゴリの例：Electronics、Apparel、Home。」
「送信時にイベントを発火」	「ユーザーがチェックアウトを完了し、注文を確定したときに発火します。すべての注文明細、適用された割引、最終注文額が含まれます。」
「トラッキングプランを参照」	「新規ユーザーがメールアドレスを確認してオンボーディングを完了した初回に発火します。ユーザーのライフタイム中に1回のみ発火します。」

---

Amplitude MCP の機能選択

実行時に、接続されているパブリックな Amplitude MCP カタログを調べます。ロールアウト中はツール名やラッパーが変更されたり、異なる形で公開されたりする場合があるため、このスキルに記録された名前に依存せず、公開されている説明とスキーマに基づいて機能を選択してください。

コンテキストと検出

• プロジェクトコンテキスト機能を使用して、アクセス可能なプロジェクト ID を確認し、選択したプロジェクトの設定を読み取ります。複数のプロジェクトが利用可能な場合はユーザーに選択を求め、プロジェクト名から ID を推測してはいけません。
• 利用可能な場合は、イベントとプロパティの検出に分類検索を使用します。利用できない場合は、アクティブな分類リーダーをフィルタリングし、ページネーションで読み取ります。チャート、ダッシュボード、ノートブック、実験、コホート、保存済みコンテンツにはエンティティ検索を使用します。
• 書き込みを行う前に、ワークスペースまたはブランチ機能を使用して、承認要件、ブランチ保護、権限、現在のブランチを確認します。

分類の読み取り

• カタログに統合分類リーダーがある場合は、そちらを優先します。公開されている判別子を使って、生イベント、カスタムイベント／ラベル付きイベント、イベントプロパティ、ユーザープロパティ、グループプロパティ、派生プロパティ、ルックアップ、チャネル、永続化プロパティを選択します。
• カタログに個別のイベントリーダーまたはプロパティリーダーがある場合は、文書化されたフィルターとページネーション用フィールドのみを使用します。別名を作ったり、他のリーダーのパラメーターを流用したりしてはいけません。
• 返された分類行からイベント名とプロパティ名を特定します。名前では大文字と小文字が区別されるため、表示名で置き換えてはいけません。
• 網羅的に読み取る場合は、すべてのカーソルをたどってページネーションします。レスポンスに合計件数が示される場合は、蓄積した行数と照合します。そうでない場合は、リーダーに文書化された終端カーソルの条件を満たす必要があります。ページの読み取りに失敗した場合や一部しか取得できていない場合は、完了とみなしません。
• イベント／プロパティの統合、値のマッピング、その他のクリーニングルールを監査する場合は、利用可能な変換リーダーを使用します。

メタデータの更新

• イベントまたはプロパティの変更機能を選択するのは、現在のスキーマが、要求されたオブジェクトの種類、メタデータフィールド、ブランチセレクター、スコープに対応していることを確認した後に限ります。
• まず対象オブジェクトの正確な現在の状態を読み取ります。明示的に確認されたフィールドのみを更新し、ユーザーが置き換えを求めていない限り既存の説明を保持します。また、古いツールバージョンから未対応のパラメーターを推測してはいけません。
• イベントプロパティのメタデータは、グローバルに設定することも、1 つのイベントにスコープを限定することもできます。スキーマに明示されたスコープ制御を使用します。現在のスキーマに文書化されていない限り、省略すればグローバルになると仮定してはいけません。
• カスタムイベント／ラベル付きイベントの定義は、マージではなく全体置換です。検証済みの完全な定義を渡し、名前の変更によって参照が壊れる可能性があることを警告します。
• ユーザーが明示的に依頼しない限り、角括弧で始まるシステムイベントやベンダープレフィックス付きのシステムイベントを更新してはいけません。
• 書き込みの前に明示的な確認を必ず求め、トラッキングプランの書き込み権限とブランチ保護に従います。

---

ワークフロー

• 標準に照らして名前とメタデータを監査する場合：「Auditing Against the Customer's Standard」（レイヤー 2）。
• 削除とクリーンアップの監査：tracking-plan-audit スキル。