ga-taxonomy

GA4 イベントタクソノミー スキル（ga-taxonomy）

マーケターが、（1）スプレッドシートからイベントタクソノミーを解析し、（2）GA4 が実際に収集している内容と照合し、（3）まだ何もない状態から始める場合は、実データをもとにタクソノミーを作成できるよう支援します。決定的な処理は scripts/ 内の Python が実行します。どのステップが該当するかはあなたが判断します。

言語

ユーザーの言語で回答してください。ユーザーが韓国語で書いた場合は韓国語で、 英語で書いた場合は英語で回答してください。これは、セットアップの案内、 進捗の更新、結果、エラーの説明など、すべてのステップに適用されます。

GA4 API の識別子（eventCount、sessionSource、runReport）、 ファイル名とディレクトリ名（.ga4/token.json）、シェルコマンド、JSON のフィールド名は 翻訳しないでください。

スクリプトの出力をそのままユーザーに見せてはいけません。 スクリプトが出力する error／hint の文字列は常に英語です。スクリプトが "ok": false を返した場合、 表示する前に hint を必ずユーザーの言語に書き換えてください。英語のまま 貼り付けたり、生の JSON を見せたりしてはいけません。書き換えた文章の中でも識別子、 パス、コマンドはそのまま維持し、周囲の文章だけを翻訳してください。

例 — スクリプトが次を返した場合： {"ok": false, "hint": "token.json is missing. Log in first with the ga-auth skill."} 韓国語を話すユーザーには、次のように伝えます： 로그인 정보(.ga4/token.json)가 없어요. ga-auth 스킬로 먼저 로그인할게요. 次のように伝えてはいけません：「token.json is missing. Log in first with the ga-auth skill.」

作業原則（重要）

対象となるのは技術者ではないマーケターです。次のルールに従ってください。

• 作業を小さなステップに分けます。 一度に1～2ステップ進め、結果を確認してから 次に進みます。

• 各ステップで「何をするか／なぜするか」を1行で説明します。

• ユーザーの負担をできるだけ減らします。 可能な場合は、ファイルの配置やコマンドの実行も 自分で行います。

• 運用テンプレートのヘッダー（9列）を優先します。ただし、列名や順序は多少異なっていてもかまいません。エイリアス辞書が自動認識します。 自動認識が曖昧な場合、パーサーは needs_mapping を出力します。その場合は --map "original-header=canonical-field,..." で列を対応付け、再実行して修正します（これは対応付けの修正であり、拒否ではありません）。

• --map では、スプレッドシートの列記号を指定できます — --map "B=up_ga4_name" — これは、ヘッダーセルが空白の列を指定する唯一の方法です。ヘッダーテキストが優先されます。つまり、シートに B という名前のヘッダーがある場合、そのキーはヘッダー名を意味し、列自体のヘッダーですでにフィールド名が示されているシートでは、列記号は受け付けられません。応答の map_resolution には、各キーが各シートでどのように解釈されたかが示されます（--map のキーはブック全体に適用され、同じ列記号でもタブごとに異なる列を指します）。数値インデックスは受け付けません。0始まりと1始まりのどちらも妥当であり、どちらが意図されたかを読み取り側で判断できないためです。

• 対応付けの指定は一度だけでかまいません。 タクソノミーとともに保存されるため、後で同じシートを再同期する際に --map は不要です。ソースを指定して再実行するだけです。対応付けが再利用された場合、応答には reused_column_map が示されます。これは同じソースにのみ適用されます。対応付けは1つのシートのヘッダーを記述するもので、シートをまたいで再利用すると、エラーにならずに誤った列が対応付けられてしまいます。この機能が導入される前に保存されたタクソノミーには対応付けが保存されていないため、--map をもう一度指定してください。それ以降は記憶されます。--sheet も同様に記憶されます。 保存された対応付けは、明示的に --map で置き換えるまで有効です。 フラグなしで再実行しても解除されず、--map "" でも解除されません。空の値はキーなしとして解析され、対応付けが再利用されます。解除するには、修正した対応付けを渡すか、taxonomy_restore.py でタクソノミーを以前の状態に戻してください。

インタープリターのルール

• taxonomy_diff.py、taxonomy_draft.py、taxonomy_restore.py：システムの python3（標準ライブラリ）
• parse_taxonomy.py：csv はシステムの python3 を使用します。xlsx には .ga4/venv/bin/python が必要です （openpyxl が必要です）。URL（Google Sheets）入力にも venv が必要です（sheets_reader が Sheets API を使用します）
• ga4_events.py：.ga4/venv/bin/python で実行する必要があります（google-analytics-data が必要です）
• sheets_reader.py：.ga4/venv/bin/python で実行する必要があります（Google Sheets API が必要です）
• custom_dims.py：.ga4/venv/bin/python で実行する必要があります（メタデータを取得します）
• param_naming.py：システムの python3（標準ライブラリ。直接実行するものではなく、ライブラリモジュールです）
• {SKILLS_DIR} = これらの ga スキルがインストールされているディレクトリ（このスキルの ディレクトリの親。Claude Code プロジェクトでは .claude/skills、ほかのエージェントでは各自の場所です）。 実際のパスに置き換えてください。コマンドはプロジェクトのルートから実行します。

ステップ 0：ステータス確認（必ず最初に行います）

.ga4/ を確認して、該当するシナリオを選びます。

• taxonomy.json はすでに存在しますか？（タクソノミーが用意されているか）
• token.json と config.json（property_id）は存在しますか？（ga-auth が接続済みかどうか。ライブデータ機能に必要です）

未接続でライブデータ機能またはドラフト機能が必要な場合は、まず ga-auth スキルを使って接続するようユーザーを案内してください。

ライブラリの準備状況を確認します（これがブロックされていると、Google Sheets／xlsx の処理で No module named ... エラーが発生します）：

python3 {SKILLS_DIR}/ga-auth/scripts/ga4_status.py

deps_ready が false で、missing_packages に ga-taxonomy が含まれている場合は、付属の deps_fix コマンドを自分で実行します（「タクソノミーシートの読み取りに必要なライブラリをインストールします」と一文で説明します）。その後、再確認してから続行してください。マーケターに pip の実行を依頼しないでください。

プラットフォームのコンテキスト

ステータス確認では platforms（このプロパティがデータを収集しているプラットフォーム）が、GA4 独自の表記（web、iOS、Android、unknown）で報告されます。存在しうるイベントやディメンションが変わるため、何かが欠けていると結論づける前に確認してください。

• null は、まだ照会されていないことを意味します。プラットフォームを推測しないでください。 推測を防ぐことこそ、このフィールドの目的です。.ga4/venv/bin/python {SKILLS_DIR}/ga-auth/scripts/ga4_admin.py get-property <PROPERTY_ID> を再実行し、ga-auth スキルの ステップ 4 の項目 4 と 5 を通じて保存してください。保存時には config.json が一から再構築されるため、同じコマンドで通貨、タイムゾーン、保持期間を再度渡さないと null になります。これにより、収益の報告通貨を ga-use が利用できなくなるほか（リアルタイムの応答にはメタデータが一切ありません）、空のファネルを確認する際に必要な保持期間の値も失われます。
• [] は、プロパティにデータストリームがなく、何も収集していないことを意味します。
• unknown の項目は、ストリームを分類できなかったことを意味するため、このリストだけでは完全な回答になりません。 unknown がある場合、web がないことを「アプリのみ」と解釈しないでください。ウェブのみ、またはアプリのみという判断を当てはめるのではなく、プロパティを分類できなかったと伝えてください。
• platforms_age_days が 180 を超えている場合、チームが後から追加したプラットフォームがリストに反映されていない可能性があります。これを根拠に判断する前に、再確認してください。
• platforms はストリームの設定状況を示します。platform ディメンションは、どのトラフィックが実際に到着したかを示します。設定済みのストリームにデータがない場合もあるため、両者を同じものとして記述しないでください。

シナリオ A：分類体系がすでに存在する場合（ファイルまたは Google Sheets の URL）

1. 入力を取得します — Google Sheets の URLまたはローカルの xlsx/csv パス。
2. 解析します（どちらも同じコマンドを使います。URL の場合は venv の python が必要です）：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-taxonomy/scripts/parse_taxonomy.py "<URL or file path>"
   

   • ok:true の場合、.ga4/taxonomy.json/taxonomy.md が作成されます。
   • replaced がある場合、既存の分類体系が置き換えられています。 replaced.event_count がある場合は、今回の実行の event_count と比較します — 大幅に減少している場合（例：31 -> 1）、誤ったファイルまたはシートが解析された可能性があります。そのまま先に進まず、ユーザーに次のように伝えてください： 「既存のイベントが31件から1件になりました。意図したファイルですか？」 （event_count がない場合、以前のファイルが破損していてサイズを読み取れなかったため、比較は行われません。）
     • ロールバックするには、ファイルを手作業でコピーせず、以下のコマンドを使ってください（json と md をまとめてロールバックします）：

       python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_restore.py            # 世代を一覧表示
       python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_restore.py -g latest  # ロールバック
       

       一覧の event_count を使い、どの世代に戻すかをユーザーと決めてください。 ロールバック直前の状態も undo_backup としてバックアップされるため、誤った世代を選んでも元に戻せます。 バックアップは .ga4/taxonomy_backups/<timestamp>/ の下に直近5世代分保持されます。
     • replaced.backup が null の場合、バックアップを作成できませんでした（ディスクまたは権限の問題）。 つまりロールバックする方法はありません。存在しない復旧手段を案内するのではなく、元のファイルから分類体系を再解析する必要があることをユーザーに伝えてください。
   • warnings がある場合、先に進む前にユーザーと内容を確認してください。 解析自体は成功していますが、各項目を無視すると後続のステップで気付かないまま問題が発生します。

     • unrecognized_scopes：スコープ列に、このパーサーが認識しない語句が入力されているため、それらのパラメーターにはスコープが設定されていません。スコープを推測せず、読み取れなかった正確な値と認識可能な語彙をユーザーに示し、シートを修正して再解析してください。そのままにすると、比較ステップでは「スコープが未指定」と報告され、すでに存在するスコープ列の追加を提案するため、ツールが壊れているように見えてしまいます。

     • case_only_duplicate_events：後述を参照してください。

     • 共通ブロックの警告： 「공통 매개변수」のようなカテゴリのパラメーターが、別にしておくべきところイベントに紐付いています。共通ブロックが個別のまま扱われるのは、最初のイベントより上にある場合だけです — イベントより下またはイベント間にあると、そのイベントのパラメーターとして気付かないまま扱われ、分析ではそのイベントだけがそれらを持つと判断されます。作成者にブロックを最初のイベントより上へ移動してもらい、再解析してください。

     • スコープなしの items 配列フィールドの警告：item_id/item_name/price/quantity などの名前のパラメーターで、スコープ列が空欄です。空欄のスコープはイベントが既定値となり、これらの名前では回答を少し変えるのではなく、まったく逆にしてしまいます — 実際のシートでは、同じ item_id がスコープを入力すると itemId (standard, item scope) に解決され、空欄だと customEvent:item_id に解決されました。これらは実際に異なる値です。イベントが本当に非コマースで、パラメーターも本当にイベントスコープである場合を除き、作成者に item を入力するよう依頼してください。

     • アプリプロパティでは、items 配列の警告は in_app_purchase に対して誤っている場合があります。 Firebase はこのイベントを自動的に収集し、product_id、price、quantity、currency、value、subscription、free_trial、introductory_price をフラットなイベントパラメーターとして送信します — items 配列はありません。そのため、空欄のスコープがイベントを既定値とするのは正しく、作成者に item を指定するよう促すと、price は itemRevenue に解決されますが、この値は決して設定されません。警告をそのまま伝えるのではなく、この説明をしてください。チームが独自に in_app_purchase と名付けたカスタムイベントには当てはまりません — どちらなのか明確でない場合は、どちらかを確認してください。

     • GA4 の収集上限の警告：分類体系が、GA4 の収集上限を超える項目を計画しています。解析時には何も失敗しません — 本番環境で数か月後に、気付かれないまま失敗します。 25個のイベントパラメーターに関する警告は特に影響が大きいケースです。Google の説明では、上限を超えると Analytics は「イベントをログに記録しない」とされています。つまり、余分なパラメーターだけでなく、イベント全体が消失します。シートが開発者に渡る前に、作成者と対応を検討してください。

     • レジストリの古さに関する警告：すべての Not registered — cannot query ラベルの根拠となるカスタム定義のスナップショットが古いか、日付がありません。ユーザーに登録が必要だと伝える前に、custom_dims.py fetch で再取得して再解析してください — そうしないと、すでに登録済みのものを登録するよう案内したり、削除済みでクエリ時に 400 エラーになる名前を渡したりすることになります。

     • GA4 名として無効であることを示す警告：GA4 の識別子として使用できない名前です。GA4 の名前は英字で始まり、英字、数字、アンダースコアのみを含むため、韓国語のラベルは明らかに該当しません。この警告に誤検知はありません。**これを分類上の問題としてユーザーに伝えないでください。**よくある原因は、人間向けのラベルと GA4 名を別々の列に保持しているシートで、ラベル列だけが認識されたことです。同じレスポンス内の unnamed_columns を確認してください。ヘッダーがなく、user_grade のような値が入っている列が名前の列です。スプレッドシートの列文字でマッピングして再解析します。ユーザープロパティには --map "<letter>=up_ga4_name"、イベントには ga4_name を指定してください。マッピングは保存されるため、同じシートを後で同期するときにフラグは不要です。

       続いてレスポンスを読んでください。マッピングが意図した場所に適用されたと思い込まないでください。--map のキーはブック内のすべてのタブに適用され、同じ列文字でもタブごとに異なる列を指します。実際に何が起きたかは、次の 2 つのフィールドで確認できます。

       • map_resolution — キーごと、シートごとに 1 つの項目があり、各項目は次の 2 種類のいずれかです。header（そのシートのヘッダーテキストと一致）または column <letter>（列文字で指定）であれば、そのキーはそこで読み取られています。ignored — で始まるものはそのタブでは何も読み取られていません。行の残りの部分に理由が記されています。

         • ignored — column <letter> from its own header <field> — その列は独自のヘッダーですでに名前が付いています。隣接するタブの通常の 타입／Type 列が列文字の影響を受けないのはこのためです。
         • ignored — column <letter> already explicitly mapped to <field> — 同じ --map 内の別のキーが、その列を先に取得しました。
         • ignored — <field> already read from column <letter> by key <key> — 1 つのタブで 2 つのキーが同じフィールドを要求しています。下記を参照してください。
         • ignored — no header or column on this tab matched this key — このキーに一致するヘッダーはなく、このタブの幅の範囲内にある列文字でもありません。数字は列の位置として使えません。--map "2=up_ga4_name" は何も指定していません。スプレッドシートの列文字である B を入力してください。
         • ignored — nothing was read from this tab (<reason>) — このタブには収集対象が何もない（または --sheet が別のタブを指定している）ため、マッピングは作成されたものの使用されませんでした。

         意図したタブに header または column <letter> と表示されていることを確認してください。それ以外の値の場合、そのタブは変更されていません。

       • unnamed_columns — ヘッダーのない列がどのシートのどの列にあるかを、サンプル値とともに示します。列文字が対応する列です。

       続いて警告自体をもう一度確認してください。マッピングしたタブの名前は表示されなくなっているはずです。別のタブの名前が引き続き表示されている場合、そのタブにも同じ問題があるということであり、このマッピングが失敗したわけではありません。それらのタブにも独自の unnamed_columns 項目があるか確認してください。 1 つのフィールドに割り当てられる列はタブごとに 1 列なので、同じフィールドに対する 2 つのキーが機能するのは、それぞれ別のタブに割り当てられる場合だけです。 --map "B=up_ga4_name,C=up_ga4_name" は、あるタブでは名前のない列が B、別のタブでは C で、かつそれぞれの文字がもう一方のタブでは通常の名前付き列になっている場合に適切です。そのようなワークブックで測定したところ、両方のタブがマッピングされ、4 つすべてのユーザープロパティに GA4 名が保持されました。同じタブで両方の文字を指定できる場合（名前のない列が 2 つある場合。たとえば名前列とメモ列）、--map 文字列の最初のキーが優先され、2 番目のキーは拒否されます。そのようなタブで測定したところ、"B=…,C=…" では列 B が保存され、"C=…,B=…" では列 C が保存されました。したがって、2 つのキーを渡す前に unnamed_columns を確認してください。候補の両方が同じタブにある場合は、sample_values が GA4 名である方の文字だけを渡してください。もう一方は同じ実行ではマッピングできず、通常は必要ありません。タブに GA4 名の列がまったくない場合、マッピングで列を作り出すことはできません。そのシートに列を追加する必要があるため、その時点でユーザーに伝えてください。

       --sheet で対象を絞り込むことはできません。 --sheet はイベントシートとして読み込むタブを選ぶだけです。ユーザープロパティは引き続きすべてのタブから収集され、--map のキーもすべてのタブに適用されます。ユーザープロパティのタブは --sheet の有効な対象でもありません。イベント列がないため、結果は needs_mapping になります。

       --map を指定せずに再解析しても、マッピングは取り消されません。 解析が成功するとマッピングは taxonomy.json に保存され、次回の実行時に再利用されます（レスポンスには reused_column_map と表示されます）。変更するには、修正した --map を渡してください。明示的に指定した値は常に保存済みの値を置き換えます。解析自体を取り消すには、タクソノミーをロールバックしてください。

       python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_restore.py            # 世代一覧を表示
       python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_restore.py -g latest  # ロールバック
       

       これにより taxonomy.json と taxonomy.md の両方が復元され、復元されたファイルにはその世代で有効だったマッピングが含まれます。そのため、次回フラグなしで再解析すると、その時点と同じ動作になります。一覧の user_property_count を使って、ユーザーが存在する世代を選んでください。 この警告が残っている間は、比較のステップに進まないでください — ラベルを名前として保存すると、すべてが「未登録」として返され、実装が壊れているように見えます。実際のタクソノミーで測定したところ、ユーザープロパティは24件あり、すべて正しく登録されているにもかかわらず、すべてが不足していると報告されました。 taxonomy_diff.py はこの問題を個別にチェックして invalid_names を報告するため、後のセッションで比較のステップから始めても警告が表示されます。ただし、これを理由に解析の修正を省略しないでください。

   • case_only_duplicate_events が存在する場合は、先に進む前にユーザーに確認してください。 大文字と小文字だけが異なる2つのイベント名（例：Purchase と purchase）が別々のイベントとして保持され、パラメーターもそれぞれに分割されました。GA4 では完全一致する名前が送信されるため、これはほぼ常にシートの誤記です。独断で表記を選ばず、実際に収集されている方を確認してください（GA4 に実際に登録されているイベントは ga4_events.py list で確認できます）。シートを修正して再解析してください。そのままにすると、使用されていない方の表記が後で比較のステップに「定義済みだが未収集」として表示され、実装が壊れているように見えます。
   • 1つのシートにイベント、共通パラメーター、ユーザープロパティが混在していても、行は個別に読み取られます。縦方向に結合されたセル（空欄）のカテゴリには、直前の値が設定されます。 Event 列と Event Name 列の両方がある場合、前者はラベル、後者は GA4 イベント名として扱われます。
   • 結果に共通パラメーターが含まれる場合（.ga4/taxonomy.json の common_parameters 配列、または taxonomy.md の記入済みの ## Common Parameters セクション）、元のシートでそのブロックがイベント一覧より上にあったかをユーザーに確認してください。途中にあった場合、通知なしに直前のイベントに取り込まれている可能性があります。
   • needs_sheet_choice:true の場合、イベントタクソノミーのように見えるタブが複数あります（例：Pixel の比較タブ）。ユーザーに candidates を提示して、どのタブがイベントタクソノミーかを尋ねてから、--sheet "<tab name>" を指定して再実行してください。独断でタブを選ばないでください。
   • needs_mapping:true の場合、自動で列を認識できませんでした。レスポンスの sheets[].headers を確認し、各列を標準フィールド（category、event_label、ga4_name、event_description、param_name、param_type、param_description、param_example、param_scope）に対応付けてから、--map "original-header=canonical-field,..." を指定して再実行してください。
   • unmapped_headers が存在する状態で needs_mapping:true の場合、イベント列は認識されましたがパラメーター列が認識されなかったため、すべてのパラメーターが破棄されていたことになります。unmapped_headers と mapped_fields を確認し、対応付けられていないヘッダーのどれがパラメーター名の列かを判断してから、--map を指定して再実行してください。これは「このタクソノミーにはパラメーターがない」という意味ではなく、列が認識されなかったという意味です。
   • Google Sheets へのアクセスで権限またはスコープのエラーが発生した場合は、スプレッドシートへのアクセス権を付与して、ユーザーに ga-auth で再ログインするよう案内してください。
3. 接続されている場合は、実データとの比較に進みます（シナリオ D）。

シナリオ B：空の状態＋GA4 がすでにデータを収集している（データから下書きを作成）

1. 接続を確認します（接続がない場合は ga-auth に案内します）。ライブデータを取得します：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-taxonomy/scripts/ga4_events.py list --days 30
   

2. 取得したデータから CSV の下書きを作成します：

   python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_draft.py
   

   .ga4/taxonomy_draft.csv が作成され、各イベントは次の 3 つのカテゴリのいずれかに分類されます： Auto-collected（GA4 が送信するため、記述する必要はありません）、Recommended（Google が名前の意味を定義しているため、説明が入力されています。purchase、add_to_cart、refund などの E コマース関連のイベントが該当します）、および (Uncategorized)（名前のみが入力され、説明は空欄です。これらはそのビジネスでしか分からない名前です）。Recommended の説明は、その名前が本来どのような意味を持つべきかを示すものであり、サイトが正しく送信していることを示すものではありません。サイトが正しく送信しているかどうかは、引き続き作成者が確認する必要があります。
3. マーケターに下書きのカテゴリ、説明、パラメーターを調整してもらい、完成版をシナリオ A の手順で解析して、正式なタクソノミーにします。

シナリオ C：空の状態＋新規（データをまだ収集していない）

1. assets/taxonomy_template.{csv,xlsx} と references/taxonomy-guide.md を使って、記述を作成するよう案内します（運用向けの 9 列テンプレートを推奨します。自動認識や --map で補正できるため、列名や列順は多少異なっていてもかまいません）。 標準的な GA4 イベント（purchase、sign_up、login など）と、ビジネスに適したカスタムイベントの両方を提案します。
2. 完成した記述を、シナリオ A の手順で解析します。

シナリオ D：ライブデータとの照合（タクソノミーと接続の両方がある）

1. ライブデータを取得します（キャッシュが古い場合は再取得します）：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-taxonomy/scripts/ga4_events.py list --days 30
   

2. カスタム定義（カスタムディメンション／指標）のステータスを取得します：

   .ga4/venv/bin/python {SKILLS_DIR}/ga-taxonomy/scripts/custom_dims.py fetch
   

3. 照合レポートを作成します：

   python3 {SKILLS_DIR}/ga-taxonomy/scripts/taxonomy_diff.py
   

4. 結果を分かりやすく説明します。

   invalid_names がある場合は、ほかの情報を読む前に処理を止めて対応してください。 これらのタクソノミー名は GA4 の識別子として使えません（GA4 の名前は英字で始まり、英字、数字、アンダースコアのみで構成されます）。そのため、GA4 がこれらの名前でデータを収集したり、登録したりすることはありません。以下の判定はすべて意味をなしません。単に否定的な判定ということではありません。実際に、正しく登録されていたユーザープロパティ 24 件が未登録と報告され、そのうち 12 件の削除が推奨される事案が発生しました。これは、解析時の警告と同じ状態です。この問題は taxonomy.json に記録されず、この手順から始めるセッションでは解析時の警告を確認できないため、ここでも再確認しています。まず解析を修正し（シナリオ A の GA4 名の無効性に関する案内を参照）、その後、再度照合してください。

   イベント：

   • defined_not_seen_recently：定義済みですが、過去 days 日間はデータが届いていません。 すぐに「実装漏れ」と判断しないでください。確認期間が短いと、問題なく機能している低頻度イベントも対象になります（実際、対象となった 14 件のうち 9 件は問題なく機能しており、そのうち 1 件は 365 日間で 474 件のヒットがありました）。 ユーザーに伝える際は、必ず確認期間を明示してください（「過去 30 日間、データが届いていません」など）。実装上の問題に見える場合も、結論を出す前に、まずより長い期間で確認してください：ga4_events.py list --days 365 を実行してから、再度照合します。 実装漏れと判断する前に、プラットフォームを確認してください。 このプロパティのストリームに存在し得ないイベントは、いくら過去にさかのぼっても現れません。そのようなイベントに対して ga4_events.py list --days 365 を案内しても、ユーザーの時間を無駄にし、ツールが壊れているような印象を与えます。
   • アプリ専用プロパティ（platforms が ["iOS"]、["Android"]、またはその両方で、それ以外は含まない）：page_view、scroll、click、file_download、form_start、form_submit、first_visit、view_search_results はウェブの拡張計測イベントです。これらは届きません。
   • ウェブ専用プロパティ（platforms がちょうど ["web"]）：first_open、screen_view、in_app_purchase、app_update、app_remove、app_exception、os_update、app_store_* の一連のイベント、notification_* の一連のイベントはアプリイベントです。これらは届きません。
   • 混合プロパティ（ウェブとアプリの両方）：どちらのイベント群も該当します。いずれの判断も適用しないでください。
   • リストに unknown が含まれる場合、または []、null の場合：ストリームを分類できなかった（または確認していない）ため、3つの判断のいずれも適用しないでください。プラットフォームが未確認であることを伝え、再確認を提案してください。この場合、web がないのは「判別できなかった」という意味であり、「アプリ専用」ではありません。それを「アプリ専用」と判断してしまうのは、このセクション全体で防ごうとしている、確信に満ちた誤答です。
   • near_misses：存在する場合は、まずこれを確認してください。表記だけが異なる分類名と実際の名前のペアです（確認例：分類名 click_button_cosulting_group と実際の名前 click_button_consulting_group）。 実装漏れではなく、誤記または改名なので、分類側を修正してください。
   • collected_but_undefined：収集済みだが未定義 -> ドキュメントの不足、または標準外イベントです。これが実際に注目すべき兆候です。GA4 の自動収集／拡張計測イベント（page_view、session_start など）はすでに auto_collected_undocumented に振り分けられているため、ここにあるものはすべてドキュメント化する価値があります。
   • auto_collected_undocumented：収集済みだが未定義で、GA4 の自動収集／拡張計測イベントでもあります（taxonomy_schema.py の AUTO_COLLECTED_EVENTS を参照）。件数は簡単に伝えてください。ユーザーに個別に列挙したり、それぞれのドキュメント化を勧めたりしないでください。これは想定内であり、不足ではありません。
   • defined_and_collected：正常です。
   • cache_hint がある場合、実データのキャッシュが古いか、キャッシュの経過時間が不明です。照合結果を報告する前に、ga4_events.py list で再取得してください。 パラメーター／ユーザープロパティ（parameters／user_properties セクション。各セクションには、すべてのパラメーターを分類する items 配列があります）：
   • defined_not_registered：最も重要な出力です。 分類表にはありますが、カスタムディメンション／指標として登録されていないため、分析でクエリできません。 GA4 管理画面 -> カスタム定義で登録するようユーザーに案内してください。登録されるまでは、このパラメーターで内訳を表示したり、フィルタリングしたりできません。
   • 登録を案内する前に scope を確認してください。 scope: "item" のパラメーターは、GA4 管理画面でスコープを Item に設定して登録する必要があり、Event ではありません。アイテムスコープのパラメーターをイベントスコープで登録するようマーケターに伝えると、商品ごとのデータを内訳表示できないカスタムディメンションが作成されます。
   • standard_metric（note 付き）：登録せずにクエリできますが、値は items 配列全体の集計値（itemRevenue、itemsPurchased）であり、アイテムごとの生の値ではありません。その旨を伝え、パラメーターと完全に一致する値として提示しないでください。
   • ambiguous: true：分類表にスコープが記載されておらず、パラメーターも登録されていないため、イベントスコープとして扱われました。付随する hint の内容を伝え、ユーザーに items. プレフィックスまたはスコープ列を追加するよう依頼してください。スコープが確認できるまでは、登録を求めないでください。
   • standard_equivalent：標準ディメンション（standard_dimension フィールド）でクエリできるため、登録は不要です。登録するようユーザーに伝えないでください。対応表には、GA4 が標準ディメンションの値を設定するための入力としてそのパラメーターを使用する場合（自動収集／拡張計測）のみが含まれます。名前が同じだけで別のソースから取得される source／medium／campaign などは、意図的に除外されています。param_naming.py のコメントを参照してください。
   • reserved_not_registerable：GA4 はこの名前をカスタム定義として受け付けません。そのため、これは登録を求めるものではなく、この名前では Data API を通じてクエリすることはできません。上記の defined_not_registered の案内に振り分けないでください。マーケターに登録を促すと、名前が拒否される管理画面に案内することになり、この分類が防ぐための、まさに誤った回答になります。名前が予約済みであることを伝え、note に標準の対応項目が記載されている場合は、そちらを案内してください。実際の分類表では予約済みの名前（user_id、session_id、google_／ga_／firebase_ のいずれかで始まる名前など）がよく使われるため、このケースに遭遇する可能性があります。
   • defined_and_registered：通常の状態です。api_names（指標には複数の集計バリエーションがある場合があるため、配列です）に、実際にクエリできる名前が格納されています。note に標準の対応項目があると記載されている場合は、そちらを優先してください。登録が不要で、カスタム定義が削除されてもクエリ可能なままです。
   • registered_not_defined：そのセクション（parameters／user_properties）直下にある別のリストです。登録済みですが分類表にないため、分類表に追加する候補となります。 api_name 文字列ではなく、items と同じ形式（parameter／scope／kind／api_names／unit）のオブジェクトの配列で、パラメーター名ごとにグループ化されています。指標に3つすべての集計バリエーション（合計／平均／件数）が登録されている場合でも、項目は1つだけ表示され、クエリ可能な名前3つがすべて api_names にまとめられます。分類表に追加する行は1つだけです。

   available: false は、手順2がまだ実行されていないことを意味します。エラーではないため、その旨を伝えたうえで、イベントの照合結果も引き続き提示してください。

   未登録のパラメーターが実際に収集されているかどうかは確認できません。 GA4 が API 経由で公開するのは、登録済みのカスタム定義だけです。そのため、「未登録」とだけ伝え、収集状況を推測しないでください。

ファイルの場所

• ランタイム状態：プロジェクトローカルの .ga4/（Git で無視されます）
  • taxonomy.json：解析済みの分類（計画）— イベント（label/ga4_name/parameters[type]）
    • common_parameters（特定のイベントに属さない共通パラメーター）+ user_properties。各ユーザープロパティには name（GA4 名）と label（人が読める名前）があり、シートで両者が区別されていない場合は null です。
  • taxonomy.md：人が読める分類の概要です。パラメーター表には クエリ名 列（method (standard) / customEvent:author / customEvent:stay_time (metric) / Not registered — cannot query）があり、ga-use が誤った名前でクエリしないようにします。2 つのラベルは名前ではなくアドバイスを示し、それぞれ意味が異なります。 Reserved name — cannot be registered or queried は、GA4 に名前を拒否されるため、マーケターに Admin -> Custom Definitions へ進むよう案内しないでください。 customEvent:x — prefer standard Y は、パラメーターが登録済みですが、標準ディメンションですでに回答できることを示すため、Y を引用します（登録を維持する必要がなく、カスタム定義が削除されても利用できます）。 custom_definitions.json がない場合は (Needs confirmation) と表示されます。custom_dims.py fetch だけを実行しても、生成済みの taxonomy.md は更新されません（内容を再生成するのは parse_taxonomy.py のみで、taxonomy_restore.py は以前のコピーを復元するだけです）。これを取得した後、分類を再解析（シナリオ A のステップ 2）して反映してください。
  • taxonomy_backups/<timestamp>/：解析直前の taxonomy.json+taxonomy.md のコピー（直近 5 世代）。間違ったファイルやシートを解析して分類が消去された場合は、フォルダー全体をロールバックします。
  • collected_events.json：ライブデータのキャッシュ（ga4_events.py によって生成）
  • taxonomy_draft.csv：下書きから作成された草案（マーケターがレビューします）
  • custom_definitions.json：カスタムディメンション／指標の登録状況（custom_dims.py によって生成）
• config.json（property_id）と token.json は、ga-auth スキルによって作成・管理されます。
• GA4_DIR 環境変数で .ga4 の場所を変更できます（デフォルト： <cwd>/.ga4）。