# AIコーディングエージェントの「委譲率」を実測して、最大の漏れ口を塞ぐ 高価なモデル（監督）に安価なモデル/定額枠（実装者）へ仕事を流させたいのに、 ルールに書いても委譲率が上がらない——という状況を、**推測でなく実測で**直すための手順書。 想定読者: 監督モデル（Opus 級）＋実装用 CLI（定額枠）＋安価API を併用していて、 「ルールは書いたのに監督が自分で全部やってしまう」問題を抱えているチーム。 --- ## 0. 前提として最初に疑うこと 委譲率が上がらないとき、たいてい原因はこの3つのどれかで、**どれも「ルールを追加する」では直らない**。 1. **ゲートが最大の漏れ口を見ていない**（監視対象の選定ミス） 2. **指標の定義が、正しい行動にペナルティを与えている**（逆インセンティブ） 3. **強制層が発動条件を満たさないまま据え置かれている**（昇格ロジックの穴） だから最初にやるのは、ルールの追加ではなく **出力トークンがどこから出ているかの実測** である。 --- ## 1. まず出力の帰属を測る エージェントの会話ログ（JSONL 形式の transcript）を走査し、 `usage.output_tokens` を **content ブロックの種類ごとに按分**する。 ```js // 期間の絞り込みは「行ごとの timestamp」で行う。 // ファイルの mtime で絞ると、長寿命セッションの過去全履歴を誤って合算する（実害あり）。 const ts = Date.parse(row.timestamp || 0); if (!(ts >= cutoff)) continue; const out = row.message?.usage?.output_tokens || 0; const content = Array.isArray(row.message?.content) ? row.message.content : []; ``` 按分の重みは **ブロック種別ごとにトークン密度を変える**。 散文（特に日本語などの非ラテン文字）は概ね 1 文字 ≒ 1 トークンに近く、 コードや JSON は概ね 3.4 文字 ≒ 1 トークン。同じ文字数でも実トークンは3倍以上違う。 ```js const PROSE_CHARS_PER_TOKEN = 1.8; // 散文（多言語混在の実用値） const JSON_CHARS_PER_TOKEN = 3.4; // コード / ツール入力 JSON const chars = type === 'tool_use' ? JSON.stringify(block.input ?? '').length : String(block.text ?? block.thinking ?? '').length; const estimate = chars / (type === 'tool_use' ? JSON_CHARS_PER_TOKEN : PROSE_CHARS_PER_TOKEN); ``` ### ここに致命的な落とし穴がある **推論（thinking）ブロックの本文は transcript に保存されないことがある**（署名だけ残る）。 その場合そのブロックの文字数は 0 になる。素朴に実装すると 「推定合計が 0 のレコードは、出力全量を text に加算する」という分岐を書いてしまい、 **推論に消えたトークンが全部「テキスト出力」として計上される**。 結果、「テキスト出力が最大の漏れ口だ」という**誤った結論**が出る。実際に発生した。 ```js // 誤り: 推論のみのレコードが text に化ける if (!totalEstimate) { blocks.text += out; continue; } // 正: 推論由来と帰属不能を分けて、捏造しない if (!totalEstimate) { const hasThinking = content.some((b) => b?.type === 'thinking'); if (hasThinking) blocks.thinking += out; else blocks.unattributed += out; continue; } ``` 推定できないものを埋めて辻褄を合わせない。`unattributed` バケットを用意して、 測れていないことを測れていないと表示するのが正しい。 --- ## 2. 実測でわかる典型パターン 上記の集計を実データに当てると、たいてい次のような分布になる。 | 指標 | 典型値 | |---|---| | main-loop 出力 / サブエージェント出力 | **99% / 1%** | | 出力の帰属 | ツール呼び出し 43% / 推論 33% / テキスト 24% | | ツール呼び出しの内訳 | **シェル実行 56%** / ファイル書き込み 18% / 編集 6% | ここで効く洞察は **「シェル実行が最大の発生源」** という点。 多くのチームは委譲ゲートを「ファイル書き込み・編集」にだけ掛けている。 ところが監督が実際にトークンを燃やしているのは、 **使い捨ての解析ワンライナー（`node -e "..."` / `python -c "..."` / ヒアドキュメント）を その場で手打ちする行為**であり、それはシェル実行ツールを通るのでゲートに一切引っかからない。 > 教訓: ゲートを掛ける対象は「重要そうなツール」ではなく「**実測で出力が多いツール**」。 --- ## 3. 指標の逆インセンティブを潰す 委譲率をこう定義していないか。 ``` 委譲率 = 安価実行者の出力 / (安価実行者の出力 + 監督モデルの出力) ``` この「監督モデルの出力」に、**サブエージェントとして呼んだ安価モデル（中位・軽量モデル）の出力** まで含めていると、方針が推奨している委譲をするほど委譲率が下がる。 ```js // 中位/軽量モデルへの委譲は「委譲」として分子に入れる const delegated = cheapApiOut + codingCliOut + midTierOut + lightTierOut; const supervisor = topTierOut + otherPremiumOut; const ratio = delegated / (delegated + supervisor); ``` 指標が行動を作る。**測り方を直さずに強制層だけ強くしても、正しい行動が罰され続ける。** --- ## 4. 最大の漏れ口にゲートを掛ける エージェントのフック機構（ツール実行前に介入できる仕組み）で、 シェル実行ツールを対象にした委譲ゲートを追加する。 ### 検出条件 - `node -e` / `node --eval` / `python -c` / `ruby -e` / `perl -e` - ヒアドキュメント（`<<'EOF'` 等） - シェル経由のインラインスクリプト実行フラグ これらに該当し、かつ**インラインプログラム部分が閾値（例: 900文字 または 25行）を超える**ときだけ発火。 ### 発火させてはいけないもの（誤検知は信頼を壊す） - 既に委譲ヘルパーを呼んでいるコマンド（それ自体が正しい行動なので邪魔しない） - 読み取り専用の素のパイプライン（`git` / `ls` / `cat` / `grep` / `find` / `wc` / `head` / `tail` / `jq` など）でインラインプログラムを含まないもの - 一時作業ディレクトリ配下の操作 ### 出力 ```js // 通常時: 警告のみ（作業は通す）。実行可能なコマンド例を必ず含める。 { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: '...' } } // 強制モード時、かつ非常に大きい場合のみ拒否 { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'deny', permissionDecisionReason: '...' } } ``` **鉄則: フック内で例外が出ても、絶対にユーザー操作を止めない。** 全体を try/catch で包み、必ず正常終了させる。フックのバグでエージェントが使えなくなるのが最悪の結果。 --- ## 5. 「委譲する方が楽」にする（ここが本丸） 警告は無視できる。**警告だけで行動は変わらない。** 禁止と同時に、**禁止した行為より低コストな代替経路**を必ず用意する。 このセッションで最も効いた対策は、規制ではなくこれだった: > 監督が毎回手打ちしていた集計スクリプトを、**再利用可能な CLI に畳む**。 ``` <集計CLI> sessions # セッション別の出力トークン（main / サブエージェント別） <集計CLI> blocks # 出力の帰属（ツール別・種別別） <集計CLI> ledger # 安価実行者の利用実績 <集計CLI> deleg # 委譲率とその内訳 ``` これがあると、監督は 1500 文字のワンライナーを書く代わりに 40 文字のコマンドを打つ。 **抜け道より正規ルートを楽にする**のが、規律を実際に定着させる唯一の方法。 --- ## 6. 強制層は「オプトインのパイロット」から始める 閾値を上げた瞬間に、条件を満たす全端末が一斉に拒否モードへ昇格する。 チームに配る仕組みでは、これは事故になる（詳しくない人が拒否理由を読めずに詰まる）。 ```js export function decideEnforcement({ ratio, daysObserved, output, history, target, pilot, previousMode }) { if (!pilot) { // マーカーが無い端末は昇格させない。既に昇格済みなら降格させて解放する。 return { mode: 'warn', reason: '強制モードはパイロット端末のみ有効' }; } // 以降、パイロット端末だけが昇格条件を評価する } ``` - 昇格の可否は**マーカーファイルの存在**で判定する（設定の書き換えより事故りにくい） - マーカーが無い端末では、**既存の強制モードを警告へ降格**させる（一斉解放の経路を必ず持つ） - 判定を**純関数として切り出して単体テストする**。ここを直接 if 文で書くとテストできない ### 昇格ロジックの穴に注意 「改善傾向があれば警告のまま据え置く」という分岐を入れると、 目標に遠く届いていなくても「改善している」だけで永久に昇格しない。 ```js // トレンドに関わらず昇格する下限を必ず設ける if (daysObserved >= 3 && output >= THRESHOLD && ratio < target / 2) return { mode: 'block', ... }; ``` --- ## 7. 実装を委譲したら、必ず自分で検証する この手順書の実装自体もコーディング CLI へ委譲したが、 **検証で2件の実バグが見つかった**。どちらも「静かに誤った数値を出し続ける」種類のもので、 テストが緑でも気づけなかった。 1. 別実行環境（コンテナ/サブシステム）側のセッションログを走査対象に含めておらず、 委譲側の実績を **0 と誤報告**していた（＝委譲率が実際より低く出る） 2. 前述の「推論トークンがテキストに化ける」誤帰属 検証の型: ``` 1. 単体テストを実行する（緑であることは前提条件であって、完了条件ではない） 2. 実データで実行し、独立に手計算した値と突き合わせる 3. フックは実際の入力ペイロードを流し込む: 発火する例 / 発火しない例 / 強制モードでの拒否 / 解除ファイルがある場合 / 壊れた入力 4. 「壊れた入力でも正常終了する」を必ずテストに含める ``` **テストが緑であることと、正しい数値が出ていることは別物。** --- ## 8. 毎回目に入る場所へ結果を出す 計測しただけでは行動は変わらない。監督のコンテキストに毎回注入する。 ``` - 委譲率: 15.2%（目標 50%） - 内訳: コーディングCLI 1998k / 中位モデル 489k / 安価API 38k / 監督 14071k - 出力の出どころ: ツール呼び出し 43%（シェル 56% / 書き込み 18% / 編集 6%）/ テキスト 24% / 推論 33% ``` 「委譲率が低い」だけだと何をすればいいかわからない。 **「どのツールから漏れているか」**まで出すと、次の一手が確定する。 --- ## チェックリスト - [ ] 出力トークンをブロック種別・ツール別に按分して実測した - [ ] 推論ブロックの本文欠落をテキストに混ぜていない（`unattributed` を用意した） - [ ] 期間の絞り込みをファイル mtime でなく行ごとの timestamp で行っている - [ ] 実測で判明した**最大の発生源**にゲートを掛けた（想像で選んでいない） - [ ] 指標の分子に「推奨している委譲先」が全部入っている - [ ] 禁止と同時に、より楽な正規ルート（再利用CLI）を用意した - [ ] 強制モードはマーカーによるオプトインで、降格経路がある - [ ] 昇格ロジックにトレンド無関係の下限がある - [ ] フックは例外時も必ず正常終了する - [ ] 実データで独立検算し、実ペイロードでフックを流した ---