Claude Media
Claude CodeのAmplitudeプラグインでイベント説明を一括で埋める
Claude CodeMCPClaude連携チュートリアル

Claude CodeのAmplitudeプラグインでイベント説明を一括で埋める

amplitude-experimentalプラグインが同梱するのは、説明のないイベントにコードを読んで説明文を提案するスキル1本です。導入コマンド、実行の流れ、書き込み前の確認点をまとめます。

読了目安 約9分

AmplitudeプラグインをClaude Codeで使うなら、まず名前を確認する必要があります。Amplitudeのリポジトリには amplitude と amplitude-experimental の2つが登録されていて、チャートやダッシュボードの分析スキルが入っているのは前者です。後者の同梱スキルは event-description-generator の1本だけで、説明文のないイベントに説明を付ける作業に特化しています。

Claude Codeから実験版を入れて使う流れと、書き込み前に確かめたい点を順に書きます。

amplitude-experimentalが入れるもの

マーケットプレイスのページには「Anthropic verified」の表示があり、説明は「Experimental skills from Amplitude」の一文だけです。READMEも「まだ実験段階のスキルを含む。注意して使う」と書かれています。

中身は次の3種類です。

同梱物

プラグインの構成

  • スキル1本

    event-description-generator。調整役で、自分では個々のイベントを分析しません。

  • サブエージェント2つ

    event-descriptions-worker が説明案を作り、event-descriptions-writer がAmplitudeへ書き込みます。

  • MCPサーバー1つ

    https://mcp.amplitude.com/mcp へのHTTP接続です。サーバー名は amplitude です。

通常版の amplitude プラグインは、チャート作成、ダッシュボード分析、実験の分析、セッションリプレイの調査、計測の設計など27のスキルを持ちます。MCPの接続先は実験版と同じです。分析をClaudeに任せたいだけなら通常版、イベント説明の整備だけが目的なら実験版、という分け方になります。

ClaudeやCoworkから同じAmplitudeに接続する運用は、Amplitudeコネクタで契約更新前の利用低下を洗う記事に書いてあります。ここで扱うのは、リポジトリの中でコードを読ませながら進める方です。

導入のコマンド

実験版のコマンドは、マーケットプレイスのページには載っていません。Claude Codeの公式手順に沿うと、リポジトリ側のマーケットプレイス名が amplitude であることから、次の形になります。

claude plugin install amplitude-experimental \
  --marketplace amplitude/mcp-marketplace

マーケットプレイスを指定したまま入れる書き方は、シェルからはv2.1.292以降、セッション内の /plugin install はv2.1.275以降が必要です。それより古い場合は、先に /plugin marketplace add amplitude/mcp-marketplace を実行してから、/plugin install amplitude-experimental@amplitude で入れます。

導入後は /reload-plugins で反映します。MCPサーバーの認証は、/mcp を開いて plugin:amplitude-experimental:amplitude を選び、ブラウザの案内に従います。プラグインが登録するMCPサーバーは plugin:<プラグイン名>:<サーバー名> という名前になる、という公式の仕様に沿った名前です。

必要なのは、API利用ができるAmplitudeアカウントです。通常版のREADMEにある要件で、実験版のREADMEに個別の要件は書かれていません。

実行の流れ: 監査から書き込みまで

スキルは「調整役のみ」と宣言していて、イベントの絞り込みもコード検索も説明の作成も、サブエージェントに任せます。流れは次の9段階です。

手順

event-description-generatorの9段階

  1. 1

    プロジェクトを決める

    projectId かプロジェクト名を受け取ります。名前なら get_context で解決し、候補が複数あれば自分では選ばず確認します。

  2. 2

    実行IDを作る

    <projectId>-<gitの短いSHA> の形です。出力は .agents/skills/event-description-generator/runs/<runId>/ の下に置かれます。

  3. 3

    カーソル範囲を決める

    既定は開始0、最大400件、1ワーカー50件、並列4です。400件なら8チャンクになります。

  4. 4

    ワーカーを起動する

    チャンクごとに event-descriptions-worker を起動し、並列数の上限で波状に回します。

  5. 5

    結果を集める

    取得数、書き出し数、CSVのパス、次のカーソル、エラーを回収します。

  6. 6

    CSVを1本にまとめる

    compress-run.py が説明案のある行だけを残し、チャンクのCSVを消します。

  7. 7

    報告する

    実行ID、ワーカー数、取得数、まとめたCSVのパス、続きのカーソルを返します。

  8. 8

    書き込むか尋ねる

    書き込みを頼んでいなければ、ここで確認します。

  9. 9

    書き込む

    頼まれた場合だけ、event-descriptions-writer が set_event_metadata を呼びます。

ここで大事なのは、第8段階までAmplitudeのデータは変わらない点です。頼んだ場合だけ第9段階へ進みます。スキル本体は set_event_metadata を呼びませんし、ワーカーにも同じ制約があります。書き込めるのは、サブエージェントの event-descriptions-writer だけです。

呼び出しの例を挙げます。プロジェクトIDは仮の値です。

プロジェクト123456のイベント説明を、カーソル0から200件、
1ワーカー50件で監査して。書き込みはまだしないで。

実際にどう動くかは環境で変わります。この例は、スキルの入力項目(プロジェクト、開始カーソル、最大件数、チャンクの大きさ)に沿って組んだ指示です。

ワーカーは何を拾い、何を書くか

ワーカーは get_events でイベントを取り、説明のない「実在しそうなイベント」だけを残します。除外の条件は具体的です。

  • 名前が空、1文字、3文字未満、数字や記号ばかり
  • 説明がすでにある
  • isInSchema が false
  • [Amplitude] Event Name のように角括弧で始まる
  • test、tmp、dummy、asdf などの使い捨てを思わせる語を含む
  • <script など、マークアップや注入の文字列に見える

残ったイベントについて、リポジトリから定義だけでなく呼び出し箇所を探します。コードに見つからないイベントは、説明を空のまま飛ばします。

説明の書き方にも条件があります。イベント名の言い換えは認められません。dashboard: pin chart を「ユーザーがチャートをダッシュボードにピン留めしたとき」と書き直しても、新しい情報がないためです。次の3点に答える必要があります。

  1. どこか(製品領域、ページ、コンポーネント)
  2. いつか(発火する具体的な操作や条件)
  3. 何のためか(分析上の意図)

文頭は「Tracked」、内部コードネームは使わず、コードに根拠のない推測は書かない、という指定もあります。

書き込む前に確認したい4点

説明はAmplitudeのイベントカタログに残り、チームの全員が読みます。書き込みの許可を出す前に、次の4点を見ておく価値があります。

まとめのCSVに目を通す

書き込みの入力は <runId>-<日付>.csv です。列は event_type、category、file_paths、suggested_description の4つで、file_paths が説明の根拠になったファイルです。根拠のファイルを開いて、説明と食い違わないかを数件見ます。

書き込み件数を確かめる

書き込みは event-descriptions-writer が set_event_metadata を1回呼び、1回で受けるのは最大100件です。ところが、この件数にはソース同士のずれがあります。

くらべる

書き込みチャンクの大きさの記述

固定値

SKILL.md

eventsPerWriter は100で変更できない、と書かれています。

既定値

writer-plan.py

--events-per-writer の既定は50で、引数で変えられます。

どちらの値で動くかは、実行して出てくる計画のJSONで確認できます。100件を超えるスライスをwriterは受け付けないため、どちらでも上限は守られます。

既存の説明が残るか見る

ワーカーは説明がないイベントだけを対象にします。一方、writerには「CSV行が説明案を持つなら上書きする」と読める制約があります。ワーカーの実行後にAmplitude側で誰かが説明を足した場合、同じ実行のCSVで古い案が上書きすることがあり得ます。実行から書き込みまでを日をまたがずに済ませれば、この食い違いは起きにくくなります。

実行用のファイルの場所を確かめる

SKILL.mdは .agents/skills/event-description-generator/ というワークスペース相対のパスを前提に、スクリプトの実行と出力先を書いています。プラグインとして入れた場合に、スクリプトが同じ場所に見つかるかは、手順の中では説明されていません。第6段階の compress-run.py でつまずいたら、プラグインの展開先にあるスクリプトの場所を確かめ、実行IDのディレクトリを合わせます。

CLAUDE.mdで運用の枠を決めておく

スキルを呼ぶたびに範囲を口で指示するより、作業するリポジトリの CLAUDE.md に枠を書いておくほうがぶれません。次は、公式の仕様から導いた一例です。

## Amplitudeのイベント説明
- イベント説明の作業は event-description-generator を使う
- 書き込みは、CSVをレビューした後に私が明示的に頼んだときだけ行う
- 1回の実行は400件までにし、実行IDと続きのカーソルを報告する
- 説明に根拠となるファイルが示せないイベントは、空のまま残す

スキルの規則(書き込みは明示的な依頼があるときだけ)をプロジェクト側でも繰り返しておく形です。サブエージェントは別のコンテキストで動くので、メインの会話だけで決めた方針は、サブエージェントに渡る指示に含まれているとは限りません。

向いている場面、向いていない場面

実験版が効くのは、計測コードが同じリポジトリにあり、説明のないイベントが数百件単位で溜まっている状態です。イベントを発火させているコードが手元にない、またはイベントの定義だけで呼び出しがほかのリポジトリにある場合、ワーカーは見つけられず、説明は空のままになります。

逆に、チャートの作成や実験の結果の読み解きは実験版の仕事ではありません。そちらは通常版の amplitude プラグインか、Claude側のコネクタの領分です。

小さな範囲で監査してから書き込む手順

  1. 作業ブランチで、200件程度の小さな範囲から始める
  2. まとめのCSVを開き、根拠のファイルと説明を数件突き合わせる
  3. 問題がなければ、同じ実行IDのまま書き込みを頼む
  4. 続きのカーソルで次の範囲に進む

READMEが「注意して使う」と書いているのは、書き込みが本番のカタログに及ぶためと読めます。監査と書き込みが別の段階に分かれている構造を使って、確認を挟んでから進めるのが、このプラグインとの付き合い方です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →