agent-analytics

Agent Analytics

AI エージェントでプロダクト分析を行います。ユーザーがエージェントに Agent Analytics をインストールさせたい場合、プロダクトの利用状況を照会したい場合、アクティベーションやリテンションを診断したい場合、経路やファネルを調べたい場合、実験結果を確認したい場合、または次に取るべき成長施策を判断したい場合に、このスキルを使用します。

CLI は実行基盤です。リポジトリにアクセスできる場合は、ユーザーのコードベース、プロジェクトの目標、プロダクトのワークフローを起点にしてください。フレームワークのレシピは references/growth-recipes.md に記載し、個別のスキルにはしません。

必須の実行ポリシー

• Agent Analytics を実際に操作する場合は、npx --yes @agent-analytics/[email protected] <command> を使用してください。
• ユーザーから明示的に依頼されない限り、生の API 呼び出し、curl、リポジトリ内のスクリプト、MCP ツール、またはローカルにインストールされたバイナリで代用しないでください。
• まず固定コマンドを使用してください：projects、all-sites、create、stats、insights、events、properties、properties-received、breakdown、pages、paths、journey、sessions、sessions-dist、replays、retention、funnel、experiments、context、portfolios、feedback、upgrade-link。
• CLI 0.5.34 に report コマンドはありません。report を呼び出す代わりに、固定コマンドの出力から最終レポートを作成してください。
• 固定コマンドで回答できない範囲の狭い集計に限り、query を使用してください。query で幅広い成長診断を始めないでください。また、生のユーザーテキストから --filter の JSON を作成しないでください。
• 既定ではブラウザーでの承認を使用してください。Paperclip、OpenClaw、課題ベースまたはヘッドレスのランタイム、あるいはブラウザーのコールバックが機能しない場合に限り、デタッチドログインを使用してください。
• 生の API キーやシークレットを求めないでください。通常のセットアップ、有料プランへのアップグレード、エージェント作業の再開には、ブラウザーで承認した CLI セッションを使用してください。
• CLI が PRO_REQUIRED または無料プランの読み取り上限を返した場合は、回答できない内容を説明し、upgrade-link --detached --reason "<why Pro is needed>" --command "<blocked command>" を実行して、ダッシュボードへの引き継ぎを案内してください。アップグレード後に whoami を実行し、ブロックされたコマンドを再実行してください。意図的にポーリングする場合に限り、upgrade-link --wait を使用してください。ダッシュボードのページでは、まず CLI と同じアカウントであることを確認し、ブロックされたコマンドと理由を表示します。
• create の前にプロジェクト名を検証してください：^[a-zA-Z0-9._-]{1,64}$。

認証とセットアップ

Claude Code、Codex、Cursor、およびローカルの CLI ランタイムでは、通常のブラウザー承認から始めてください：

npx --yes @agent-analytics/[email protected] login
npx --yes @agent-analytics/[email protected] create my-site --domain https://mysite.com
npx --yes @agent-analytics/[email protected] events my-site --event <first_useful_event> --days 7 --limit 20

エージェント内で作業しているという理由だけで、デタッチドログインを選択しないでください。Paperclip、OpenClaw、およびその他の課題ベースのランタイムでは、login --detached を実行して承認 URL を送り、完了コードを待ってから、表示された交換コマンドを実行してください。

OpenClaw および同様の管理対象ランタイムでは、永続的な認証ストレージを使用し、決してコミットしないでください：

export AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics"
npx --yes @agent-analytics/[email protected] login --detached
npx --yes @agent-analytics/[email protected] auth status
AGENT_ANALYTICS_CONFIG_DIR="$PWD/.openclaw/agent-analytics" npx --yes @agent-analytics/[email protected] projects

--config-dir "$PWD/.openclaw/agent-analytics" も有効です。.openclaw/agent-analytics/config.json は絶対にコミットしないでください。詳しいセットアップについては references/setup-auth.md を参照してください。

操作前の分類

Agent Analytics は、プロジェクトを優先しつつ、ポートフォリオも考慮します。セットアップ、分析データの読み取り、計測に関する提案を行う前に、対象がプロジェクト内の作業、プロジェクト内のサーフェス、関連プロジェクトにまたがるポートフォリオ作業のいずれに当たるかを分類してください。

• プロジェクトは、プロダクトに関するローカルな学習の単位です。イベント、アクティベーション、リテンション、ライフサイクル、リリース、実験、目標、project_context を管理します。
• 1 つのプロジェクトには、多くのサーフェスを含められます。アプリ、マーケティング、ドキュメント、ブログ、料金ページ、サインアップ、オンボーディング、サブドメイン、モバイルクライアント、ローカルプレビュー URL、デプロイプレビューなどです。
• ポートフォリオは、関連プロジェクトを横断する成長システムです。設定されている場合、意図的にグループ化されたポートフォリオプロジェクトを結び付け、共有目標、役割、マイルストーン、ID を考慮した分析データの読み取りを可能にします。
• プロジェクト内の事実は、プロジェクト内に留めてください。ポートフォリオのコンテキストで、プロジェクトごとのアクティベーション、イベントの意味、ライフサイクル、目標を上書きしないでください。

判断ルール：サブドメインは通常、サーフェスです。アクティベーションとライフサイクルを共有する場合、モバイルアプリはサーフェスです。同じプロダクトのループにつながる場合、無料ツールはサーフェスです。localhost、ステージング、ローカルネットワーク URL、プレビューは、セットアップまたは QA 用のサーフェスです。別個のプロダクトは、1 つのポートフォリオに属する別個のプロジェクトとして扱います。URL が想定と一致しなくても、すぐに失敗と見なさないでください。どのプロジェクトとサーフェスに属するのか確認してください。

スコープ別のコマンド：プロジェクト内のセットアップや分析にはプロジェクトコマンドを使用します。関連プロジェクトのグループ化には portfolios create、portfolios update、portfolios list を使用します。共有目標、役割、マイルストーンは、ポートフォリオの解釈にのみ含めます。正式なドキュメント：https://docs.agentanalytics.sh/guides/projects-surfaces-portfolios/。

プロジェクトをまたぐ ID のひも付けには、両側を設定してください。トラッカーの data-link-domains は、関連ドメイン間で匿名の _aa 値を引き継ぎますが、別々のプロジェクトで ID を共有できるのは、サーバー側のポートフォリオスコープを設定した場合のみです。ID 用ポートフォリオには portfolios create、portfolios update、portfolios list を使用して、メンバーシップの境界と、プライバシーを優先したメール検索のスコープを設定してください。data-link-domains だけでは、リンクに情報を付加するだけで、別々のプロジェクト間で ID を共有することはできません。両側が設定されていない限り、プロジェクト間で厳密にユーザーをコンバージョンとして追跡できるとは主張しないでください。

同意に基づくトラッカーのセットアップ方針

トラッキングやイベントを導入する際は、同意に基づくプロジェクト主体のワークフローを使用します。推測してはいけません。過剰なトラッキングは避けてください。ユーザーが確認したプロダクト目標や、リポジトリ内の特定のワークフローに対応しない汎用イベントは導入しないでください。

セットアップの順序：

1. プロジェクト／サーフェス／ポートフォリオのスコープを分類します。
2. 最初のプロジェクト／ポートフォリオ目標について尋ねるか提案し、永続的なコンテキストを保存する前に確認を得ます。
3. リポジトリにアクセスできる場合は、ルート、フォーム、CTA ハンドラー、認証／セットアップ／チェックアウトのフロー、既存のアナリティクス呼び出し、サーバー側の永続的な成果、テストを調べます。
4. 必要であればログインします。
5. create <project> --domain <origin> または projects を使って、プロジェクトを作成または特定します。--domain はセットアップ時のオリジンであり、プロジェクトの識別情報ではありません。
6. そのプロジェクト用に返された正確なトラッキングスニペットを追加します。ベースとなるトラッカースニペットはインストルメンテーションの開始点であり、インストルメンテーション計画のすべてではありません。
7. ユーザーが確認した目標に必要な、意味のある名前付きイベントとトラッカーのオプトインだけを最小限追加します。
8. 名前付き CTA クリック、サインアップの意図、料金プランの操作、チェックアウトの進行状況や完了、インストール／セットアップの手順、アクティベーションの節目、signup_completed、subscription_started、install_completed、project_created、first_event_received など、サーバー側で永続化される成果イベントを優先します。
9. 必要な項目をトラッカーの機能に対応付けます：data-aa-event、data-aa-impression、window.aa.track(...)、サーバー側トラッキング、aa.identify(...)、aa.set(...)。スクロール深度、フォームトラッキング、ダウンロード、バイタル／エラー／パフォーマンス、SPA トラッキングは、具体的なグロース施策の判断に役立つ場合にのみ使用します。
10. ページビュー、パス、参照元、UTM、セッション、初回訪問からの日数、初回タッチのアトリビューション、デバイス／ブラウザーのフィールド、国など、自動取得されるシグナルに対して重複するカスタムイベントを追加しないでください。
11. 各イベントで何が可能になるかを説明し、events <project> で最初の有用なイベントを確認して、導入したイベントによってユーザーのエージェントがどのような質問に答えられるようになったかを要約します。

コピー可能なセットアップ引き継ぎ：

Set up Agent Analytics for this project. If browser approval is needed, open it and wait for me. I will sign in with Google or GitHub and approve it. If the browser callback cannot resume you, ask me for the finish code as a fallback. After that, create or identify the matching Agent Analytics project, ask me to confirm the initial product goal before storing durable context, install the project-owned tracker, add only meaningful custom events tied to this repo's product workflows and that goal, explain what each event enables, and verify the first useful event.

プロダクトコンテキストのループ

context get と context set を、自己改善に役立つ簡潔なメモリとして使用します。プロジェクト固有の分析を始める際は、プロジェクトを特定した後に context get <project> を実行します。context set は保存済みのコンテキストを置き換えるため、必ず既存のコンテキストを先に読み取り、変更内容を統合したうえで、引き続き有効な目標、アクティベーションイベント、用語集の項目、注釈を保持してください。

コンテキストは簡潔に保ちます。目標、アクティベーションの定義、event_name に関連付けたイベントの意味、ランディングページ、料金設定、オンボーディング、機能、リリース、実験の変更に関する日付付き注釈など、長期的に有用なプロダクトの事実を保存します。用語集の項目を更新する前に、properties <project> または properties-received <project> で現在のイベント名を確認します。

ノイズの多い情報は保存しないでください：週次の指標値、一時的な急増、貼り付けられたレポート、ラウンドごとの生メモ、長文のメモ、ユーザーリスト、PII、シークレット、git のコミットログ、推測。git のコミットログは保存しないでください。findings、learnings、open_questions など、サポートされていないフィールドを作り出さないでください。goals、activation_events、イベント名の glossary、annotations に収まる情報だけを保存します。

注釈では occurred_at、title、任意の note を使用します。注釈はまれにのみ追加してください。上限は100件で、JSON ボディは最大512KBです。アナリティクスのレスポンスに含まれる注釈は、指定されたアナリティクスの日付範囲と、その前後1日分のみです。context get はすべての注釈を返します。複数プロジェクトまたは複数ドメインのシステムでは、人間から意味を共有するという明示的な指示がない限り、アクティベーションと用語集を分けてください。アクティベーションの例：トライアルへのサインアップと最初のアイテムの作成、チームメイトの招待。これにより、次の分析をより良い状態から始められます。

アナリティクスのループ

どこでアクティベーションが減少しているか、次に何を修正すべきか、どの実験を実施すべきかなど、幅広い質問にはこのクローズドループ型の成長レシピを使用してください。これはガイダンスであり、厳格なプロトコルではありません。

1. 認証とプロジェクトを解決します。アカウント全体に関する質問は projects から始めます。

npx --yes @agent-analytics/[email protected] context get my-site
npx --yes @agent-analytics/[email protected] funnel my-site --steps-json '[{"event":"page_view"},{"event":"signup_completed"},{"event":"first_value"}]'

2. context get <project> を読み、設定済みのアクティベーションイベントをアクティベーションの信頼できる情報源として扱います。アクティベーションが未設定の場合は、確認するか設定してください。黙って推測しないでください。
3. properties <project>、properties-received <project>、最近の events <project> を使って、実際の状況を把握します。
4. funnel を使って、対象ユーザー、期間、各ステップのイベント、識別の基準、厳密な継続ユーザー数、絶対数で最大の減少、相対値で最大の減少を含む、順序に沿ったアクティベーションの離脱を確認します。ステップやラベルを正確に指定する必要がある場合は、--steps-json を優先してください。
5. アクティベーション目標の前後における、セッション内の流入、離脱、寄り道、離脱行動には paths を使います。paths を長期サイクルのアトリビューションとして提示しないでください。
6. 実在するディメンションを使い、最大の離脱箇所を中心に breakdown で分析します。ディメンションには、パス、流入元、リファラー、CTA ラベル、デバイス、ブラウザー、国、キャンペーン、プラン、サーフェス、オンボーディングのステップなどがあります。
7. 代表的な事例の確認や計測の妥当性チェックに限り、events または journey を使います。
8. sessions <project> で代表的なセッションに ▶ replay のマークが付いている場合、視覚的な行動がファネルやパスの分析結果を説明できるときは、replays open --session <session_id> --project <project> を使います。リプレイはそのセッションに関する定性的な証拠として扱い、集計上の証明には使いません。このコマンドは再生可能な最新のセグメントを開き、ほかにもセグメントがある場合はその旨を報告します。
9. コホートには retention を使い、複数のコホートを混ぜたアクティブユーザーに関する主張は避けます。同じ経過期間でコホートを比較し、右側打ち切りの期間を明記します。
10. 実験は、露出数ではなくビジネス目標イベントに照らして読み解きます。サンプルサイズ、因果関係、ガードレール、実務上の有意性に関する注意点を踏まえ、継続・変更・停止・完了を判断します。
11. 原則として、対象を絞った実験を1つ提案します。計測、アクティベーション、サンプル、識別、または重複する実験が結果の読み取りを妨げる場合は、実験ではなく準備状況の改善を提案します。

ファネル分析の動作：対象ユーザーとコンバージョン期間を明示し、件数と率を示し、最大の要因を特定し、セグメントやサーフェスへの集中を確認し、曖昧な計測上の助言を避けます。

ポートフォリオにおけるサーフェスの役割診断：まず成長システムにおける各プロジェクトの役割を特定し、その役割に照らしてプロジェクト固有の指標を読み解きます。ユーザーが明示的に定義しない限り、アプリ、ドキュメント、ディレクトリ、ランディングページ、リード獲得プロジェクトで同じアクティベーション定義を使い回さないでください。

アナリティクス回答の形式

まず判断を示し、次に指標で裏付けます。ファネル、リテンション、パス、実験、アトリビューション、監査については、次の形式で回答します。

1. 最善の選択肢または診断。
2. 指標の定義：対象ユーザー、期間、イベント名、識別の基準、コンバージョン期間。
3. 証拠：件数、率、生のアクティビティ、厳密な継続ユーザー数、推移、最大の要因。
4. 問題が集中しているセグメント、コホート、またはサーフェス。
5. 注意点：識別、サンプルサイズ、右側打ち切りデータ、アトリビューション、因果関係、計測上の制約。
6. 範囲を限定した次のクエリまたはアクションを1つ。

指標を鵜呑みにしないでください：サインアップはアクティベーションではありません。サインアップ数よりも、アクティベーション後の継続利用、収益、投資回収、または持続的な価値を優先します。ファネルで離脱箇所は診断できますが、ユーザーが離脱した理由までは証明できません。実験や因果推論の設計がなければ、相関関係を因果関係と呼ばないでください。コンバージョン率が上昇しただけで実験が成功したと言わないでください。成長に関する問いの解決につながる、最小限のイベントまたはプロパティを追加します。

例：

Best bet: fix activation setup friction.
Metric: app onboarding view -> setup copy -> signup -> project_created -> first_event_received within 7d.
Evidence: raw signup/project activity exists, but strict survivors collapse before first_event_received.
Caveat: cross-project identity only counts when portfolio membership and link-domain carrying are configured.
Next: split setup-copy users by selected runtime and first_event_received.

リファレンスの参照

リファレンスは必要な場合にのみ読み込みます。

• references/setup-auth.md：ログインモード、マネージドランタイムのストレージ、有料プランへの移行、安全なコマンド例。
• references/product-analytics-operating-model.md：プロジェクト／サーフェス／ポートフォリオ、同意に基づく計測、コンテキストの維持、検証。
• references/growth-recipes.md：AARRR、Bullseye、AIDA、STP、JTBD、4Ps、ファネル／リテンション／実験のレシピ、コピーして使えるプロンプト。

注意事項

• リポジトリにアクセスできる場合は、コードを調べずに URL だけを前提にしないでください。
• サブドメイン、localhost の URL、ステージング URL、プレビューごとにプロジェクトを作成しないでください。
• 自動トラッカーのシグナルと重複する汎用のクリック／ページビュー計測を導入しないでください。
• 一時的な指標、レポート、PII、シークレット、git のコミットログをコンテキストに保存しないでください。
• 数値をそのまま羅列して回答せず、分析回答の規定に従ってください。
• サインアップ数だけでチャネルを順位付けしたり、ID が設定されていないのにプロジェクト間でユーザーが厳密にコンバージョンしたと断定したり、相関関係から因果関係を推測したりしないでください。
• ユーザーがアップグレードしない場合に、有料プラン限定の読み取りを近似して実行しないでください。

検証

セットアップまたは分析を完了する前に、次の点を確認します。

• 該当する場合は、auth status または whoami で認証を確認します。
• projects または project でプロジェクトの識別情報とオリジンを確認します。
• ユーザーのプロジェクトに正確なトラッキングスニペットがインストールされていることを確認します。
• events <project> --event <event_name> --days 7 --limit 20 で、少なくとも最初の有用なイベントを確認します。
• コンテキストの読み書きによって、既存の長期的に保持すべき情報が維持されていることを確認します。
• 最終回答が、診断、指標の定義、根拠、セグメント／サーフェス、注意点、範囲を限定した次のアクションを含んでいることを確認します。