# AIエージェントの「委譲率」が上がらない時の診断と是正 — 委譲の準備と使い捨てスクリプトを分離する ## これは何か Claude Code のような自律コーディングエージェントを監督役（高価なモデル）＋実装役（定額・安価なモデル）で運用すると、 「監督が実装を抱え込まないこと」を数値で管理したくなる。典型的な指標が **委譲率 = 委譲先の出力トークン / 全体の出力トークン**。 この指示書は、**委譲率が目標に届かず、ゲート（PreToolUse hook による警告・拒否）を強くしても改善しない**という状況の 診断手順と是正パターンを示す。実際に委譲率 8.5% で停滞していた環境で、原因が「規律の不徹底」ではなく **計測と強制層の設計ミス**だったと判明したケースを一般化したもの。 ## 前提 - エージェントの実行ログ（transcript）が JSONL で保存され、`tool_use` ブロックと `usage.output_tokens` が読めること - ツール実行前に割り込める hook（PreToolUse 相当）が使えること ## 手順 ### 1. ゲートを足す前に、出力の発生源を実測する 「ルールが守られない → ルールを追加する」を繰り返すと層だけ増えて漏れ口は開いたまま残る。まず測る。 transcript の assistant メッセージを走査し、出力トークンを次の3バケツに分ける。 - `tool_use`（さらにツール名別に内訳を取る） - `text` - `thinking` 注意: **thinking の本文は transcript に保存されない実装がある**。その場合、thinking のみのレコードの出力を そのまま text に加算すると「text が最大の漏れ口」という誤った結論になる。thinking は独立バケツに分離すること。 多くの環境で最大になるのは**シェル実行ツール**（Bash 等）である。実装コード編集（Write/Edit）にだけゲートを 掛けていると、最大の発生源が完全にノーガードのまま残る。 ### 2. シェル実行の「中身」をさらに分類する ツール名別の内訳で止めないこと。シェルコマンドの本文を次のカテゴリに分類し、文字数を集計する。 | カテゴリ | 判定 | 意味 | |---|---|---| | `delegated` | 委譲ヘルパーの呼び出しを含む | 委譲そのもの。常に最優先で判定する | | `spec-authoring` | ヒアドキュメントやリダイレクトで**ファイルへ書き込んでいる** | 委譲先へ渡す仕様書の執筆＝**委譲の準備コスト**。無駄ではない | | `inline-program` | インタプリタが即席プログラムを実行している | **削減対象の無駄** | | `read-only` | 読み取り専用コマンド | 不可避 | | `other` | 上記以外 | — | `inline-program` の判定は `-e` / `-c` オプションだけでは足りない。 **インタプリタがヒアドキュメントを標準入力から読む形**（`python - < **`other` が最大カテゴリなら、それは結論ではなく次の調査対象。** 未分類バケツが大きいまま放置されている＝まだ測れていない、のサイン。 ### 4. 落とし穴: 指標が正しい行動を罰していないか確認する 上記の未分類 60% の中身を上位から目視すると、ほぼ全部が `cat > task-spec.md <<'SPEC_EOF' ...` ＝ **委譲先へ渡す仕様書を書く行為**だった。 ここに構造的な矛盾がある。 - 仕様書の執筆は、監督役の正規の担当（設計・分解・指示）である - しかしその出力は委譲率の**分母**（監督の出力）に積まれ、**分子には一切入らない** - つまり **委譲すればするほど委譲率が下がる** - さらにゲートが文字数だけで判定していると、**委譲の準備をするたびに警告される** 強制層を強くする前に、必ず「その指標は推奨したい行動にペナルティを与えていないか」を確認すること。 ### 5. 是正: 分類器を単一の真実にして共有する プロファイラ（計測側）とゲート（強制側）が**それぞれ独自の正規表現**を持っていると、片方だけ直して もう片方が古いまま残る。分類関数を1つ export し、両方が import する形にする。 ```js // 計測側とゲート側が同じ関数を使う export function classifyBashCommand(command) { if (DELEGATION_HELPERS.test(command)) return 'delegated'; // 最優先 if (INTERPRETER_INLINE.test(command)) return 'inline-program'; // 無駄 if (FILE_WRITE_HEREDOC.test(command)) return 'spec-authoring'; // 委譲の準備 if (READ_ONLY.test(command)) return 'read-only'; return 'other'; } ``` ゲート側の判定は次の一行に畳む。 ```js if (classifyBashCommand(command) !== 'inline-program') process.exit(0); ``` **`spec-authoring` は文字数に関わらず素通しさせる。** 委譲の準備を止めてはならない。 止めた瞬間、エージェントは「仕様書を書くのが面倒だから自分で実装する」方向に最適化する。 ### 6. 是正の原則: 禁止と同時に「禁止した行為より楽な正規ルート」を用意する 禁止だけを足すと抜け道を探す動機になる。使い捨ての集計スクリプトを禁止するなら、 **同じ集計をワンコマンドで返す再利用可能なサブコマンド**を先に用意し、拒否メッセージからそれを案内する。 ``` 🔒 委譲ブロック: 約{N}文字の使い捨てインラインプログラムを停止しました。 再利用可能な集計なら `<統計ツール> <サブコマンド>` を使ってください。 一回性の実装なら `<委譲ヘルパー> "<指示>"` へ委譲してください。 ``` ## 検証（ここまでやって初めて「効いた」と言える） 1. **分類器の単体テスト**: 各区切り語のヒアドキュメント、インタプリタ標準入力形、委譲ヘルパー呼び出しが 期待どおりのカテゴリになること 2. **hook の端から端までのテスト**: 実際の hook 入力 JSON を標準入力へ流し、 巨大な `spec-authoring` が**素通しされる**こと・巨大な `inline-program` が**拒否される**ことを確認する 3. **実体パスでの確認**: hook は設定ファイルに登録されたパスで動く。リポジトリの作業コピーを直しても、 登録先が別のコピーなら**何も変わらない**。登録先のファイルを直接叩いて確認すること 4. **再計測**: 是正前後で各カテゴリの割合を比較する 参考として、実測環境での是正前後（7日間・シェル呼び出し 4,512件 / 約210万文字）: | | 是正前 | 是正後 | |---|---:|---:| | inline-program（無駄） | 32.1% | 26.0% | | spec-authoring（委譲の準備） | 未分類に混入 | 11.7% | | delegated（委譲呼び出し） | 6.5% | 35.8% | | other（未分類） | 60.1% | 25.2% | ## 落とし穴まとめ - **複数のエージェントが同じ作業ツリーを共有していると、他方の `git checkout` で自分のブランチごと HEAD が戻される。** 検証は独立した作業ツリー（`git worktree add`）を切ってそこで行う。共有ツリーで検証すると、 自分が直したはずのコードではなく古い版を検証してしまい、誤った結論（「回帰した」等）に至る - hook の中で例外を握り潰していると、import 失敗などで**黙って何もしない hook**になる。 無効化に気付けないので、端から端までのテストを必ず持つ - 委譲率の指標そのものは、是正後も `spec-authoring` を分子に数えない。 数値を上げるために定義を変えるのは指標の私物化なので、**まず内訳を併記して解釈可能にする**のが先 ---