🧭 本記事は Claude Code実務運用シリーズ の STEP 6「サブエージェント化する」です。
エージェントチームに"監査"を任せる回です。外部データを一切見ず、ローカルのコードだけを根拠にGA計測を棚卸しし、その結果を独立検証で裏づけます。
シリーズ全体の地図と読む順は 親記事 にまとめています。
この記事のゴール
「このイベント、まだ使ってる?」 ― GA の計測についてこう聞かれて、その場で即答できるチームは、どのくらいあるでしょうか。
同じ種類の質問は、いくらでも出てきます。
- 「この数字、何を数えてるの?」がコードを読まないと分からない(そしてコードを読むと思っていたのと違う)
- 新しい施策の分析設計をしたいのに、既存の計測で何が測れるのかが分からない
- 定義だけあってどこからも送信されていないイベントが、台帳に混ざったまま気づかれない
原因ははっきりしています。GA の計測は2つの層に分かれていて、答えは片方にしか書かれていないからです。
- 実装層 … アプリに組み込む Firebase Analytics(Google Analytics for Firebase とも呼ばれます)の SDK。「どのイベントを・どこで・どういう条件で送るか」はここ、つまりコードの中にしかありません
- 分析層 … 送られたデータが溜まる GA4(Google Analytics 4) のプロパティ。企画・マーケティング担当が普段見ているのはこちらです
分析層の管理画面に出るのは「送られてきたイベント」だけです。「どこで・どういう条件で送っているか」は出てきません。冒頭の質問に誰も即答できないのは、答えが実装層にしかないからです。この非対称が、運用年数が伸びるほど効いてきます。
(この記事で「GA計測」と呼ぶのは両方を合わせたものですが、棚卸しの対象は実装層です。)
かといって手で棚卸しすると、イベント定義が3桁・呼び出し箇所が数百に散らばっている規模では、数日仕事になります。しかも一度やっても、半年後にはまたズレます。
この記事は、その棚卸しを Claude Code のサブエージェントチーム(7体) に任せた実装例です。GA4 の管理画面も Firebase コンソールも一切見に行かず、ローカルのソースコードだけを根拠に、イベント台帳・品質監査・ビジネス活用提案までを1つのHTMLレポートにまとめます。
そして、この手の自動化でいちばん問題になるのが「その台帳、信じていいの?」です。AIが作った台帳は、たいていそれらしく完成します。表も埋まっているし、ファイル名も書いてある。しかし中身が正しいかは誰も確かめていません。この記事の後半は、そこを検証工程として組み込んだ設計に割いています。
固有名詞と実データは伏せますが、設計とテンプレートはそのまま転用できる形で書きます。iOS(Swift/Objective-C)を題材にしていますが、計測ラッパーを持つコードベースなら Android でも Web でも同じ構造で組めます。
なお Skill / サブエージェントの frontmatter 仕様は 2026年8月時点の Claude Code で検証したものです。この領域は変化が速いため、実装時は公式ドキュメント(Agent Skills・Subagents)も併せて確認してください。
GA計測の棚卸しは、なぜ人にもAIにも難しいのか
手作業でやったことがある人なら分かると思いますが、この作業は「grep して一覧にする」では終わりません。
1. 経路が多段になる。 計測ラッパーを噛ませていると、こうなります。
イベント定数の定義 → ラッパーの補助メソッド → 実際の呼び出し元(画面・サービス)
イベント名で grep しても、出てくるのは定数定義とラッパーだけです。「どの画面のどの操作で送られるのか」に辿り着くには、さらに1〜2段たぐる必要があります。ObjC と Swift が混在していれば、呼び出し形式も2種類になります。
2. 送信条件がコードの奥にある。 「カート追加イベント」が、本当にカート追加が成功したときに送られているとは限りません。ボタンをタップした時点で送られていることもあります。この違いは、コンバージョン率を計算するときに致命的です。管理画面からは絶対に分かりません。
3.「無い」を証明する必要がある。 未使用イベントの判定は、「全パターンを網羅したうえで、無いと言い切る」作業です。網羅性の嘘は、成果物の見た目からは絶対に分かりません。ここがAIに任せたときの最大のリスクです。
4. 読者がエンジニアではない。 棚卸しの結果を本当に使うのは企画・マーケティング担当です。Foo.swift:123 が根拠として書いてあっても、彼らには使えません。
つまりこの作業は、量が多く・経路が多段で・「無い」の証明を含み・成果物の読者が別職種という、AIに任せると壊れる条件が全部そろっています。だから設計で潰します。
設計:7体で「収集・解釈・検証・翻訳」を分ける
作ったのは ga-audit という Claude Code スキル(= サブエージェントのチーム)です。フローはこうです。
役割分担は次のとおりです。「なぜ分けるか」に理由がない分割はしないのが原則です。
| # | エージェント | 責務 | 分けた理由 |
|---|---|---|---|
| 1 | sdk-scout |
分析SDK(Firebase Analytics 等)・ラッパー層・初期化・ユーザープロパティ・同意まわり | 「何で計測しているか」を決めつけずに探索させる役。イベント列挙とは探索範囲が別物 |
| 2 | event-cataloger |
イベント定義と全呼び出し箇所の機械的列挙(JSON出力) | 解釈を禁止した列挙専任。後述の「型1」 |
| 3 |
flow-analyst ×4 |
各イベントの意味・トリガー・送信条件・呼び出し経路・活用方法 | 量が多いので担当を明示分割して並列化 |
| 4 | quality-auditor |
未使用・重複・命名揺れ・計測漏れ・パラメータ不整合・PII懸念 | 「個別の意味」ではなく「全体の歪み」を見る役。視点が違う |
| 5 | verifier |
独立検証(別解での再導出・根拠の裏取り・秘密情報スキャン) | 他の成果物を信用しない役。後述の「型4」 |
| 6 | business-strategist |
ファネル・KPI・セグメント軸への翻訳 | 読者がエンジニアではない。求められる正しさの基準が違う |
| 7 | reporter |
単一ファイルHTMLレポートの生成 | 統合と整形だけ。判断させない |
重要な制約として、全エージェントにネットワーク・MCP・外部サービスを一切使わせません。 GA4の管理画面もFirebaseコンソールも見に行かない。「実データを見ないと分析にならないのでは」と思うかもしれませんが、逆です。根拠を「ローカルのコードと設定だけ」に固定すると、すべての記述が第三者に検証可能になります。実データが要る話は、後述のタグで「要確認」として切り出します。
何が出てくるのか(成果物)
出力は単一ファイルのHTMLレポート1本です(CSS・JS・データを全部インライン化しているので、ファイルをそのまま Slack や Redmine に添付できます)。中身はタブ構成で、こうなっています。
1. イベント台帳(メイン) — 検出したイベント全件の表です。1行 = 1イベントで、クリックすると詳細が開きます。
| 列 | 内容 |
|---|---|
| イベント名 | コード上の実際の送信文字列 |
| カテゴリ | 本棚・ビューア・購入・検索・認証…といった機能分類 |
| 説明 | 何を計測しているか(分類タグ付き) |
| トリガー | 発火契機(ユーザー操作・画面遷移・ライフサイクル) |
| 送信条件 | ガード条件(会員のみ / 初回のみ / 無条件…) |
| 呼び出し箇所数 | 何箇所から送られているか |
| 状態 | 使用 / 未使用 |
詳細を開くと、呼び出し経路(「画面X のボタンtap → ハンドラ → ラッパー」)、パラメータの意味、根拠(パス:行番号 のリスト)、活用方法、要確認事項、呼び出し箇所の全リストが出ます。
フリーテキスト検索・カテゴリ絞り込み・使用/未使用の切り替えが付いているので、「このイベントまだ使ってる?」にその場で答えられるのが実用上いちばん効きます。
2. 計測基盤 — 使っている分析SDK、ラッパー層の構造、初期化箇所、screen_view が自動収集か手動送信か、ユーザープロパティ一覧、同意まわり(ATT等)の実装有無。
3. 品質監査 — 未使用イベント、重複・類似イベント、命名揺れ、計測漏れの疑い、パラメータ不整合、PII混入の懸念、ラッパーを迂回した直接呼び出し。棚卸しで本当に欲しいのはここだったりします。
4. ビジネス活用提案 — 後述します。
5. 独立検証結果 / 要確認事項一覧 / 調査方法 — 「この台帳をどこまで信じてよいか」を明示するセクションです。
台帳を「信用できるもの」にする4つの型
ここからが本題です。棚卸しの自動化そのものは、正直そんなに難しくありません。難しいのはその結果を信じてよい状態にすることです。
AIに調査を任せたときの壊れ方は、だいたい4つです。
- 存在しないものを書く … 定義されていないイベント名が、もっともらしく表に並ぶ
-
根拠がズレる … 「
Foo.swift:123」と書いてあるが、開くと別の処理がある - 一部を全部に一般化する … 「全呼び出し箇所でこのパラメータが付きます」と書くが、実際は5箇所中3箇所だけ
- 調べ漏れを「無い」と報告する … 前述のとおり、これは見た目から分かりません
どれも「もっともらしさ」で通ってしまいます。かといって人間が根拠の行を全部開いて確かめるなら、そもそもAIに任せた意味がありません。以下の4つは、それを設計で潰した部分です。ここはGA以外のドメインにもそのまま移植できます。
型1:「事実の列挙」と「意味の解釈」を別のエージェントに分ける
event-cataloger のプロンプトには、こう書いています。
解釈や提案はしない(それは flow-analyst / quality-auditor の仕事)。
正確な列挙だけに集中する。
分ける理由は、同じエージェントに列挙と解釈を両方させると、解釈の都合で列挙が歪むからです。面白いイベントは厚く書かれ、地味なイベントは「その他」に丸められ、最終的に何件あったのかが曖昧になります。
列挙専任にして、出力を厳密なJSONスキーマに固定します。
{
"event": "add_to_cart",
"constant": "AnalyticsEvent.addToCart",
"definedAt": "path/to/AnalyticsConstants.swift:22",
"wrapperMethod": "path/to/Tracker+Events.swift:120 logAddToCart(...)",
"callSites": [
{"file": "path/to/Foo.swift", "line": 123, "context": "Tracker.log(.addToCart)"}
],
"paramKeys": ["item_id", "screen"],
"used": true,
"dynamic": false,
"notes": ""
}
ポイントは used と callSites を持たせたことです。これで未使用イベントの判定が、人の主観ではなく配列長で決まります。検証側も機械的に突き合わせられます。
そして最後に必ずこれを書かせます。
書き終えたら `python3 -m json.tool` で JSON として妥当か必ず検証する。
自分の出力を自分で構文チェックさせるだけで、下流の「パースできませんでした」がほぼ消えます。
型2:根拠に「パス:行番号」を強制する
全エージェント共通の厳守事項に、次を入れています。
- すべての【確認済み】記述に根拠(リポジトリ相対パス:行番号)を付ける。
- 行番号は必ず grep -n / Read で実測する(推測の行番号を書かない)。
地味ですが、この記事でいちばん重要な一行です。理由は単純で、検証可能性は後付けできないからです。
根拠のない台帳を後から検証しようとすると、検証役は結局ゼロから全部調べ直すことになり、コストが二重にかかります。最初から「パス:行番号」を出力仕様に埋めておけば、検証は抜き取って開いて照合するだけの作業になります。読む側にとっても、疑わしい行だけ自分で確かめられるのは大きい。
「実測する(推測を書かない)」を明記するのも効きます。これがないと、それっぽい行番号が生成されます。
型3:4分類タグで「断定」を封じる
すべての記述に、次のどれかを必ず付けさせます。
| タグ | 意味 |
|---|---|
| 確認済み | コードの該当行で直接確認できる事実(根拠必須) |
| 推定 | コードからの合理的推測、または一般知識(その旨を明記) |
| 改善提案 | 監査担当のアイデア。実装事実ではない |
| 要確認 | コードだけでは判断できず、実データや関係者確認が必要 |
そのうえで、効果と数値の断定を名指しで禁止します。
- 「このイベントで◯◯が分かる/改善できる」という活用方法は必ず【改善提案】とし、
実データがなければ効果や数値を断定しない(「〜の把握に使える」まで)。
GA計測の棚卸しでは、この区別が特に効きます。コードから確実に言えること(「このイベントはボタンタップ時点で、成否を問わず送信される」)と、実データがないと言えないこと(「実際に何件発生しているか」「この画面の離脱率」)は、はっきり別物だからです。
タグを付けさせる本当の狙いは、書き手に「これは自分がどの立場で言っているのか」を毎回自己申告させることです。「確認済みタグを付けるなら根拠を出す必要がある」という制約が効いて、根拠を出せない主張は自然に「推定」か「要確認」へ落ちていきます。
読者(特にビジネス側)にとっても、どこを鵜呑みにしてよくて、どこが仮説なのかが一目で分かります。
型4:検証は「別解で再導出」+ 機械適用可能な修正指示
verifier のプロンプトはこう始まります。
あなたは「独立検証」担当。他エージェントの成果物を信用せず、
自分で導出した結果と突き合わせて、調査漏れ・根拠のない説明・誤引用を見つける。
あなたの姿勢は敵対的レビュアーである:
「正しいことの確認」ではなく「誤りの発見」を目的とする。
そして検証手順の第1項が、この設計の肝です。
1. **網羅性の独立再導出**: 台帳を見る前に、自分のパターンでイベント一覧を再導出する
(grep パターンは cataloger と変えて複数試す)。その結果と台帳を突き合わせ、
台帳にないイベント・存在しないイベントを列挙する。
「台帳を見る前に」「パターンを変えて」 の2つが要点です。成果物を先に読むと、人間と同じで「書いてあることの確認」に引きずられます。同じ手順を再実行するだけなら、同じ誤りを同じように再現するだけで検証になりません。
残りの検証項目はこうです。
- 構造検証 … JSONスキーマ・必須キー・件数の一致(意味分析の合計件数 = 台帳の件数)
-
根拠のサンプル検証 … 全体の15%以上を無作為抽出し、
パス:行番号を実際に開いて引用位置に本当にその処理があるかを確認 - 秘密情報・個人情報スキャン … APIキーらしき文字列・メールアドレス等の混入を全成果物に対して機械検査
- タグ規律 … 効果の断定が【改善提案】以外に紛れていないかを抜き取り確認
そして出力は、感想文ではなく 機械適用可能な修正指示JSON です。
[
{
"severity": "major",
"target": "03_semantics_A.json",
"event": "<イベント名>",
"field": "params",
"action": "revise_text",
"from": "<現在の記述>",
"to": "<修正後の記述>",
"reason": "5箇所中2箇所はパラメータなしで呼ばれており、現状の記述は全箇所で付くと読める"
}
]
なぜJSONなのか。 「ここが間違っています」という自然言語のレビューコメントで返すと、それを人間か別のエージェントが解釈して適用することになり、その解釈でまた新しい誤差が入ります。「どのファイルの・どの項目の・どのフィールドを・何から何に」まで機械可読にすれば、適用は python3 の数行で決定的に終わります。オーケストレーター側は判断せず、適用するだけになります。
critical(調査漏れ)が出た場合だけ、その漏れたイベントだけを担当にしたエージェントを1体追加起動して補完し、もう1ラウンドだけ検証をかけます。上限は先に決めて、超えたら「残課題」と明記して進みます。
ビジネス担当が読める形にする
棚卸しの成果物を本当に使うのは、多くの場合エンジニアではありません。そこで7体目の business-strategist が、調査結果を企画・マーケティング・プロダクトオーナー向けに翻訳します。
出すのはこの構成です。
- 推奨ファネル … 「ビジネス上の問い」→ イベント列 → 計測上の注意点(この計測はどこまで信用してよいか)
- 定点観測すべき指標(KPI候補) … 対応イベント・GA4での作り方(どの探索レポートで何を掛け合わせるか)
- セグメント分析の軸 … 実在するユーザープロパティに限定
- 計測改善の優先提案 … ビジネスインパクト順
ファネルの「注意点」列が実務では効きます。たとえば「カート追加イベントは、処理の成否を問わずタップ時点で送信されるので試行数として扱う」といった但し書きです。これを書いておかないと、分母を間違えたコンバージョン率が独り歩きします。
ここでも規律を同じだけ課します。
- **実在するイベント・パラメータ・ユーザープロパティしか参照しない**:
提案に使うイベント名は、書く前に必ず台帳と突き合わせる(python3 等で機械的に照合)。
未使用イベントを組み込む場合は「現在未使用」と明記する。
ビジネス向けの文書はいちばん「盛れて」しまうところなので、架空のイベント名で理想のファネルを描く事故を機械照合で潰します。オーケストレーター側でも同じ照合を独立にもう一度かけています。
読者を変えると、正しさの基準も変わる
これは実際にやってみて気づいたことです。最初の版では、パラメータ名をコード上の定数名(例: selectFrom)で書いていました。エンジニアには通じます。しかしビジネス担当がGA4の管理画面でこの名前を探しても、絶対に見つかりません。実際に送信されているキーは select_from だからです。
定数定義の実体を確認して送信キー名に直しましたが、これは「事実として間違っている」わけではなく、読者にとって使えない情報だったという失敗です。同様に次の3つも、あとから規則としてエージェント定義に追記しました。
- ソースコードの参照(
パス:行番号)は本文に直書きせず、(※1)形式の脚注にして末尾へ退避する(開発チームとの確認用として残す) - 実装用語をビジネス語に言い換える(「差分同期で検知」→「購入済み一覧を次回同期した際の事後検知」)
- KPI表には「GA4での作り方」列を持たせる(どの機能で、何を掛け合わせるか)
読者を宣言すると、必要な正しさの基準が変わる。 成果物を人に渡すエージェントを作るなら、ここは設計項目として最初から持っておくべきでした。
実際に動かして起きたこと
1. 検証役は、本当に誤りを見つけた
いちばん知りたいのは「検証層はアリバイではないのか」だと思います。実行結果は major 1件・minor 2件(critical 0件)でした。
major は、あるイベントのパラメータ説明が「呼び出し箇所ごとに値が設定される」と読める書き方になっていたが、実際には複数ある呼び出し箇所のうち2箇所はパラメータなしで送信していた、というものです。事実として完全な嘘ではないが、その説明を信じてGA4側で分析設計をすると破綻する種類の誤りです。
これは前述の「一部を全部に一般化する」パターンそのもので、台帳を眺めているだけでは絶対に気づけません。検証役が呼び出し箇所を1件ずつ開いたから出てきました。minor 2件は件数の記載ミス(定数の数え間違い)で、これも機械照合で出ています。
2. 静的チェックが全部PASSでも、触ったら壊れていた
生成されたHTMLレポートに対して、私は最初こう検証しました ― JSON構文チェック、埋め込みイベント件数の一致、外部参照ゼロの確認、JavaScript構文チェック。全部PASSでした。
そのあと実ブラウザで開いて操作したら、タグ絞り込みが壊れていました。「改善提案」「要確認」のチェックを入れると常に0件になる。原因は、フィルタが「説明タグ」だけを見ていて、パラメータや活用方法に付いたタグを判定対象にしていなかったことでした。
教訓は単純です。成果物が「動くもの」なら、動かす検証を工程に入れる。 静的チェックは「壊れていないこと」を保証しません。ついでに、狭い画面幅で横スクロールが出るCSSの不備も、実機幅で見て初めて分かりました。
3. 「一致した」ことにも価値がある
verifier の独立再導出は、台帳と完全に一致しました。差分ゼロです。
これは「無駄だった」ではありません。網羅性を主張してよい根拠が手に入った、ということです。「イベントを全部洗い出しました」という主張は、普通なら誰も検証できないので信じるしかありません。別手法での再導出が一致していれば、その主張の裏付けを成果物に書けます。棚卸しの成果物としては、ここが信頼性の土台になります。
4. 出てくる指摘は、だいたい「言われてみれば」系
品質監査から出てくるのは、派手なバグではありません。定義だけあって使われていないイベント、同じ操作を別名で二重に計測している箇所、イベント名の綴りミス(送信されると意図した名前で集計できない)、同じ導線なのにパラメータが付いている呼び出しと付いていない呼び出しの混在、自由入力値をそのままパラメータに載せている箇所(PII混入の懸念)といった類です。
どれも「言われてみればそうだ」というもので、だからこそ何年も放置されます。棚卸しの価値は、こういうものを定期的に機械で拾い直せる状態にすることにあります。
ハマりどころ / 実装Tips
- 担当は明示的に列挙して渡す … 並列化するとき「残りを担当してください」は必ず漏れます。オーケストレーター側で台帳から名前を抽出し、担当リストを全件書き出してプロンプトに埋めます。返ってきたら件数が割当と一致するか機械確認します
-
オーケストレーターは成果物を読み込まない … 台帳JSONを自分のコンテキストに展開すると、それだけでコンテキストが埋まります。
python3で「件数」と「名前リスト」だけ抽出します。統合役こそコンテキストを空けておく必要があります - サブエージェントの返信に行数上限を課す … 「詳細はファイルへ書き、返信は要約のみ・25行以内」と明記します。これがないと、成果物の全文が返信で戻ってきてオーケストレーターが溺れます
-
「未使用」の判定は必ず裏取りさせる … 台帳の
used: falseを鵜呑みにせず、検証役が独自のgrepで1件ずつ確認します。存在しないことの証明が、いちばん嘘の出やすい場所です - レポート生成役に判断させない … データはPythonスクリプトでマージしてJSONに固め、手書き転記を禁止します。「整形しているうちに数件落ちる」を構造的に潰します
- リポジトリは読み取り専用にする … 棚卸しは調査であって実装ではありません。「コード・テスト・設定・指示ファイルを一切変更しない。書き込みは状態ディレクトリ配下だけ」をスキルの安全ルールに明記します
-
スキルは明示呼び出し専用にする … frontmatter に
disable-model-invocation: trueを入れ、自然言語や他スキルから勝手に起動しないようにします。監査系は「頼んでいないのに走る」と事故になります
テンプレート
スキル本体(SKILL.md)の骨格 ― クリックで展開
---
name: ga-audit
description: "[明示呼び出し専用] 計測実装をローカルソースコードのみで網羅調査し、
イベント台帳・品質監査・独立検証付きのHTMLレポートを生成する。
管理画面・MCP・Web検索は使用しない。リポジトリは読み取り専用。"
argument-hint: "[出力先ディレクトリ(省略可)]"
disable-model-invocation: true
---
あなた(このスキルを実行するメインエージェント)は Orchestrator / Integrator である。
自分では調査・分析をせず、専用サブエージェントに委譲する。あなたの仕事は、
フェーズ制御、成果物の整合確認、検証結果の反映、ユーザーへの短い進捗報告だけである。
## 固定設定
| 項目 | 値 |
|---|---|
| 対象リポジトリ | カレントの git リポジトリ(worktree でも可) |
| STATE_DIR | `$HOME/Documents/<成果物置き場>/<RUN_ID>/`(リポジトリ外) |
### 予算(ハード上限)
| 名前 | 値 | 意味 |
|---|---|---|
| SUBAGENT_CALLS_MAX | 14 | サブエージェント起動回数の合計上限 |
| CHUNK_SIZE | 40 | 解釈担当1体あたりの担当イベント数の目安 |
| VERIFY_ROUNDS_MAX | 2 | 検証→修正の最大ラウンド数 |
上限到達時はその時点の結論と限界を明記してレポート作成へ進む。上限は引き上げない。
## 安全ルール(絶対・例外なし)
- **リポジトリは読み取り専用**: コード・テスト・設定・指示ファイルを一切変更しない。
git の書き込み操作をしない。書き込みは STATE_DIR 配下だけに許される。
- **外部サービス禁止**: GA4管理画面・Firebaseコンソール(MCP含む)・Web検索・WebFetch を使わない。
根拠はローカルのソースコード・設定・docs のみ。
- **秘密情報**: 設定ファイルの値(APIキー等)を読まない・出力しない。
- **タグ規律**: 記述は【確認済み】【推定】【改善提案】【要確認】のいずれかに分類し、
実データがなければ効果・数値を断定しない。
## 調査フェーズ
### Phase 1: 基盤調査と台帳作成(並列2体)
### Phase 2: 意味分析(N体並列)と品質監査
### Phase 3: 独立検証 → 修正指示JSONを機械適用
### Phase 3.5: ビジネス翻訳 + イベント名の機械照合
### Phase 4: レポート生成
### Phase 5: オーケストレーターによる最終検証
イベント台帳役(cataloger)の出力仕様 ― クリックで展開
# 調査手順
探索対象: リポジトリ内のアプリコード全体。テストコードは対象外だが、テストだけから
参照されるイベントがあれば notes に記録する。依存ライブラリ配下のSDK本体は
呼び出し箇所として数えない。
1. **イベント定数の全列挙**: 定数定義を grep -n で全件取得し、
定数名・イベント名文字列・定義位置を記録する。
2. **送信呼び出しの全列挙**: 次のパターンをすべて洗う:
- ラッパー経由の送信メソッド呼び出し(Swift / ObjC 両方)
- ラッパー内の補助メソッドと、その呼び出し元
- SDK 直接呼び出し(ラッパーを迂回しているもの)
- 生文字列でのイベント名指定(定数を使っていないもの)
3. **対応付け**: 各イベントについて (a)定義位置 (b)補助メソッド (c)アプリコードからの
呼び出し箇所すべて(ファイル:行番号 + その行のコード1行) (d)渡しているパラメータキー
(e)使用/未使用 を対応付ける。
- 動的にイベント名を組み立てている箇所は dynamic: true として生成パターンを記録する。
# 出力
1. `02_catalog.json` — 厳密なJSON配列(コメント禁止)。書き終えたら python3 -m json.tool で検証。
2. `02_catalog.md` — 統計のみ: 定義済み総数 / 使用 / 未使用 / 呼び出し箇所総数 /
生文字列イベント数 / SDK直接呼び出し数 / 動的イベント名の箇所。
3. 最終返信は20行以内: 上記統計と出力パスのみ。イベント一覧を返信に貼らない。
検証役(verifier)のエージェント定義 ― クリックで展開
---
name: <prefix>-verifier
description: <スキル名>専用。他エージェントの調査結果を独立に検証し、調査漏れ・
根拠のない説明・誤った行番号・秘密情報混入をチェックする読み取り専用エージェント。
オーケストレーターから明示的に起動されたときだけ使用する。
Do not use proactively.
tools: Read, Grep, Glob, Bash, Write
model: sonnet
---
あなたは「独立検証」担当。他エージェントの成果物を信用せず、
自分で導出した結果と突き合わせて、調査漏れ・根拠のない説明・誤引用を見つける。
あなたの姿勢は敵対的レビュアーである:
「正しいことの確認」ではなく「誤りの発見」を目的とする。
# 厳守事項
- 読み取り専用: リポジトリ内のファイルを一切変更しない。Write は担当ファイルのみ。
- 外部サービス禁止: ネットワークアクセス・MCP ツールを一切使わない。
- 秘密情報・個人情報の実値を出力しない。
# 検証手順
1. **網羅性の独立再導出**: 成果物を見る前に、自分のパターンで一覧を再導出する
(grep パターンは収集役と変えて複数試す)。その結果と成果物を突き合わせ、
欠落・過剰を列挙する。
2. **構造検証**: 全JSONがパースでき、必須キーを持ち、件数が一致すること。
3. **根拠のサンプル検証**: 全体の15%以上を無作為抽出し、各根拠の パス:行番号 を
実際に Read して、(a)引用位置に本当にその処理があるか (b)説明がコードと整合するか
(c)【確認済み】タグの記述が本当に直接確認できるか を判定する。
できなければ【推定】への降格を指示する。
4. **秘密情報・個人情報スキャン**: APIキーらしき文字列・メールアドレス等を
全成果物に対して grep し、混入があれば重大問題として報告する(値は伏せて位置だけ)。
5. **タグ規律**: 効果・数値の断定がタグなしで書かれていないかを抜き取り確認する。
# 出力
1. `05_verification.md`: 検証方法、PASS/FAIL サマリー、問題一覧(critical/major/minor)。
2. `05_fixes.json`: オーケストレーターが機械適用できる修正指示。
問題がなければ空配列。書き終えたら python3 -m json.tool で検証する。
3. 最終返信は20行以内: PASS/FAIL、件数、代表的な問題3件以内、出力ファイルパス。
詳細を返信に貼らない。
ビジネス翻訳役に課した「可読性の規則」 ― クリックで展開
# ビジネス可読性の規則(読者はエンジニアではない)
- **パラメータ名は管理画面で見える送信キー名で表記する**: 定数名ではなく実際の送信値を
定義ファイルで実測して使う。実測できないものは【推定】と明記する。
- **ソースコードの参照(パス:行番号)を本文に直書きしない**: 本文には (※1) 形式の
脚注番号だけを置き、末尾の「根拠(実装箇所)」節に一覧をまとめる(開発チーム確認用)。
- **実装用語をビジネス語に言い換える**: クラス名・フラグ名・API名をそのまま使わず、
動作の意味で説明する。
- **KPI表には「GA4での作り方(例)」列を含める**。
- 書き終えたら、ビジネス読者(管理画面は触れるがコードは読まない人)になりきって通読し、
(a)本文にコード参照が残っていないか (b)未翻訳の実装用語がないか を確認してから完了する。
まとめ
GA計測の棚卸しをAIエージェントに任せて分かったのは、棚卸しそのものより「その台帳を信じてよい状態にする」ほうが設計の本体だったということです。効いた原則は4つでした。
-
検証可能性は後付けできない。 「根拠は
パス:行番号で、行番号は実測する」を最初から出力仕様に埋める。後から検証しようとすると、検証役が全部調べ直すことになって二度手間になります - 検証は「別解での再導出」でしか成立しない。 同じ手順を再実行しても、同じ誤りを同じように再現するだけです。成果物を見る前に、違うパターンで、独立に導出させる
- 修正指示は機械可読にする。 自然言語のレビューコメントは、適用する側の解釈でまた誤差が入ります。「どのファイルの・どの項目を・何から何に」まで構造化すれば、適用は決定的になります
- 成果物が動くものなら、動かして検証する。 静的チェックが全部PASSでも、実際に触ると壊れていることがあります(実際に壊れていました)
そして、棚卸しの成果物を人に渡すなら 読者を宣言する。読者が変われば、必要な正しさの基準そのものが変わります ― 定数名で書かれた正しい情報は、GA4の管理画面しか見ない人には使えない情報でした。
「GAのイベントが増えすぎて、実装側の全体像が誰にも見えていない」というのは、長く運用しているプロダクトならどこにでもある話だと思います。根拠フォーマットの強制・タグ規律・別解での再導出・機械適用可能な修正指示の4点セットがあれば、その棚卸しは「AIにやらせたが信じてよいか分からないもの」ではなく、定期的に回せる検証済みの作業にできます。
このシリーズの歩き方
Claude Code実務運用シリーズ ― 暴走させない、から仕組みにするまで。
- ◀ 前の記事: 【Claude Code】チケットURLを渡すだけ。iOS不具合を調べて報告まで行うAIチームの設計
- ▶ 次の記事: スキルが増えたら「入口」を作る:Slack起点の受付AIチームで一次トリアージ【テンプレ全公開】
- 🔍 あわせて読む: Claude Codeで作る敵対的レビュー3体:高リスク差分だけに注入【全文公開】 ― 同じ「反証役」の発想をコード差分のレビューに適用した回
- 🗺 シリーズ全記事の地図(親記事)
