# 「このAIモデルは定額内か従量課金か」を推測せず実測で確定し、ルールを機械で二段構えにする AI コーディングエージェントを組織で使うと、必ず「このモデルは定額プランに含まれるのか、それとも 追加課金なのか」という問いが出る。ここを**推測で決めると高確率で間違える**。実際に「別課金だから 全面禁止」という社内ルールを敷いたが、後で実測したら**課金ゼロだった**という事例がある。 逆に「専用のバーが出ているから定額内だろう」と判断したら従量だった、という逆側の間違いも起こる。 この指示書は、①課金区分を**実測で確定させる手順**と、②確定した結果を**機械が強制する形に落とす型**を扱う。 特定のベンダーに依存しない考え方だが、コンソールの画面名は主要な AI コーディングエージェントの 管理画面を想定して書いている。 ## 1. なぜ推測が外れるのか（2つの罠） **罠1: 専用のレート制限バーがあることは「定額内」の証明にならない。** 高速モードのような「追加課金される機能」でも、専用のレート制限プールを持つことがある。 管理画面に「◯◯ limit」という独立したバーが出ていても、それは 「このモデル専用の上限がある」という意味でしかなく、**その消費が無料かどうかは何も語っていない**。 **罠2: 上限に達していないから課金されていない、とは言えない。** 多くのサービスのドキュメントには「この機能はプランに残枠があっても追加クレジットから引かれる」 と明記されている。つまり**上限とは無関係に課金される機能が存在する**。 逆にこれが判定の鍵になる（後述）。 ## 2. 確定手順（これだけが証拠になる） ### 2-1. 支出レポートを出す 管理コンソールの**分析／Analytics** 画面を開き、「コスト」「支出レポート」に相当する CSV エクスポートを実行する。期間は当月（MTD）。ユーザーごとの「使用量」画面ではなく **分析画面**にあることが多い。ユーザー行の「…」メニューには内訳が無いことが多いので注意。 CSV に必要な列は次の3つ。 | 列 | 用途 | |---|---| | `model`（またはモデル名） | 判定したいモデルの行を特定する | | `total_net_spend_usd`（実課金額） | **これがゼロなら定額内** | | `total_cache_write_1h_tokens` 等のキャッシュ列 | 後述の「本当のコスト要因」を見るのに使う | ### 2-2. 判定する 対象モデルの行の**実課金額を見るだけ**。 - **ゼロ → 定額内**。罠2の裏返しで、従量課金される機能は上限に残枠があっても課金されるため、 「使ったのに金額がゼロ」は定額内以外に説明がつかない - **ゼロでない → 従量**。金額の大きさは使用量次第なので、少額でも従量と判断する **注意: データは1日遅れが普通**。当日に使った分は翌日にしか出ない。 「今日使ったのに金額が増えていない」は定額内の証拠にならない。翌日もう一度出す。 ### 2-3. 総額の内訳も同時に見る（ここで別の発見が出る） 「請求額が想定より高い」という問題を追っているなら、支出レポートは原因の特定にも使える。 実例として、次のような分布が観測されている。 | モデル | リクエスト | 出力トークン | 1時間キャッシュ書き込み | 実課金 | |---|---|---|---|---| | 中位モデル | 4,302 | 1,589,327 | 10,205,837 | $8.64 | | 上位モデル | 3,263 | 2,744,158 | 307,694 | $2.77 | **安いはずの中位モデルが上位モデルの3倍かかっていた**。出力トークンは上位モデルのほうが多い。 差は**1時間キャッシュの書き込み量**（33倍）。長命キャッシュの書き込みは通常入力より単価が高く、 短命なセッションを大量に立てると**読み出しで元が取れる前に書き込み料だけを払う**。 つまり「安いモデルへ逃がす」だけではコストが下がらない。次を守る。 - 委譲は**1セッションで複数件をまとめて**処理させる。1件ずつ新セッションを立てると 同じ前提を毎回キャッシュに書き直す - 短命・単発の呼び出しで長命キャッシュ（1時間 TTL）を狙わない - 「安いモデルでも品質が保てる」という評価結果は**品質の話**であり、総額の結論ではない。 総額は支出レポートで別に測る ## 3. 確定した結果を機械が強制する形に落とす 人間向けドキュメントに「◯◯は監督用途のみ可」と書いても守られない。次の3層に落とす。 ### 3-1. 単一の設定源を作る 判定結果を**1つの JSON**に集約する。判定に関わる全てのツールがこれを読む。 配布の仕組みに乗る場所（他PCへ同期されるディレクトリ）に置くのが要点。 ```json { "planIncluded": true, "scope": "supervisor-only", "verifiedOn": "", "evidence": "支出レポート(<期間>): <モデルID> = req, out tok, 実課金 0.00。従量課金の機能は上限に関係なく課金されるため 0.00 は定額内を意味する。", "recheck": "分析画面の支出レポートを出し、当該モデルの行の実課金額が 0 でなくなったら planIncluded を false に戻す。プラン変更・シート種別変更時も再確認する。" } ``` `evidence` と `recheck` を**必ず書く**。これが無いと半年後に「なぜ許可されているのか」が分からなくなり、 また推測でルールが書き換わる。 ### 3-2. 読み込みヘルパーは「安全側に倒す」 ```js export function loadPolicy(options = {}) { try { const dir = options.dir || path.dirname(fileURLToPath(import.meta.url)); const raw = fs.readFileSync(path.join(dir, 'model-policy.json'), 'utf8'); return JSON.parse(raw.replace(/^/, '')); // BOM を除去する } catch { return { planIncluded: false, scope: 'supervisor-only' }; // 未確認は禁止扱い } } ``` 3点が要。 - **ファイルが無い・壊れている場合は「禁止」に倒す**。未確認のアカウントで勝手に課金させない - **BOM を除去する**。Windows のシェルで書き出すと先頭に BOM が付き、除去しないと `JSON.parse` が落ちて禁止側に倒れ、「定額内なのに警告が出続ける」ことになる - **読み込み元ディレクトリを引数で差し替えられる**ようにする。テストで両方の分岐を固定するため。 既定値は**モジュール自身の位置**から解決する（実行時のカレントディレクトリに依存させない。 配布先ではリポジトリの場所が違う） ### 3-3. 3か所で使い分ける | 層 | 何を見るか | 定額内のときの挙動 | |---|---|---| | セッション監視（プロンプト送信時のフック） | 自分の会話ログの末尾から現在のモデルを判定 | **何も言わない**（正規の使い方になったので） | | 委譲の門（サブエージェント起動前のフック） | 起動パラメータのモデル指定 | **拒否のまま**（単価が高いモデルを量産に使わせない） | | 日次のコストレポート | 期間内の使用量 | 警告ではなく**情報**として報告 | **「定額内だから全面解禁」にしないこと**が肝。単価が上位モデルの2倍あるようなモデルは、 定額内でも「設計・レビュー・検証（監督）に限る」に留めるのが費用対効果に合う。 `scope: "supervisor-only"` がその意思をコードで表現している。 セッション監視のフックは、**会話ログ全体を読まない**。実運用のログは数十MBになるので、 末尾の数百KBだけを読んで最新のモデルを判定する。 ## 4. 検証（ここを飛ばすと必ず壊れる） ### 4-1. 実挙動を3経路とも叩く 単体テストだけでは足りない。フックに実際の入力を流して確認する。 ``` # 定額内 → 無音であるべき echo '{"session_id":"x","transcript_path":"<ログ>","hook_event_name":"UserPromptSubmit"}' | node session-guard.mjs # 未確認 → 警告が出るべき（環境変数で policy を差し替える） ... | POLICY_DIR= node session-guard.mjs # サブエージェント指定 → 定額内でも拒否されるべき echo '{"tool_name":"Agent","tool_input":{"model":"<高単価モデル>"}}' | node agent-guard.mjs ``` ### 4-2. CI が走らせている全部を手元で走らせる **よくある落とし穴**: テストランナーのファイル名パターン（例 `*.test.mjs`）に**乗っていない 検証スクリプト**が CI の別ステップで走っていることがある。手元で `--test` を回して全部通っても、 CI で落ちる。着手前に CI 設定を開き、**実行されているコマンドを全部列挙**してから、 その全部を手元で流す。 既存の検証スクリプトが旧ルール前提の期待値を持っている場合は、 **環境変数で「未確認」を明示して旧期待値を維持**し、新たに「定額内なら無音」を1件足す。 旧期待値を消してはいけない（未確認アカウントの保護が効かなくなる）。 ## 5. 委譲でこの作業をやらせる場合の注意 この作業を別の AI エージェントに委譲するなら、次の2つが実際に起きた失敗なので先に潰しておく。 **失敗1: シェル経由の起動で引数が壊れる。** Windows で子プロセスを `shell: true` で起動すると**引数がクォートされずに連結**される。 `-p "Please execute instructions:"` のような**空白を含む値が分割**され、CLI が 使い方（ヘルプ）を表示して**終了コード0で終わる**。1行も書いていないのに成功に見える。 対処は「シェルを1層も通さない」だが、Windows では npm 製の CLI が `.cmd` なので `shell: false` にすると今度は `EINVAL` で起動できない。**結論は「シェル経由は維持し、 引数の値に空白を入れない」**。値を定数として切り出し、空白が入ったら落ちるテストで固定する。 **失敗2: フォールバック先の空振りを検知していない。** 主たる実行系が枠切れのときの代替経路は、**主たる系と同じ検証を通さないと無言で失敗する**。 「作業ツリーが1行も変わっていない」「出力にヘルプの文字列がある」を検知して**非ゼロ終了**させる。 終了コードだけを信じてはいけない。 **失敗3: 委譲先が仕様の一部を落とす。** 実測では、7項目の仕様を渡して2回連続で「テストの追加」だけが落ちた（宣言はするが実行しない）。 **成果物のファイル一覧を突き合わせて確認**し、落ちた項目は再委譲するか自分で埋める。 「完了報告に含めること」を仕様の末尾に明記しておくと突き合わせが速い。 ## 6. 落とし穴チェックリスト - [ ] 判定を**支出レポートの金額**でやったか（バーの有無・上限の残りで判断していないか） - [ ] データが1日遅れであることを踏まえたか - [ ] 設定ファイルが**読めないとき禁止側に倒れる**か - [ ] BOM を除去しているか - [ ] 設定ファイルの場所が**配布の仕組みに乗る**ディレクトリか - [ ] `evidence` と `recheck` を書いたか - [ ] CI が走らせるコマンドを**全部**手元で流したか - [ ] 旧ルール前提の既存テストを、消さずに「未確認」側で維持したか - [ ] 実挙動を3経路（定額内・未確認・サブエージェント）叩いたか - [ ] キャッシュ書き込み量も見て、**安いモデルが実は高い**を見落としていないか ---