AI運用ルールを「機械的に守らせる」hook設計 — ルール文が守られない本当の理由

チームで AI コーディングエージェント（Claude Code / Codex CLI 等）を使うと、必ずこうなる。

「高いモデルを使うな」「実装は定額枠のCLIに投げろ」「大量処理は夜間バッチに回せ」と ルールに書いたのに、別のPCでは一度も実行されていなかった。

原因はほぼ「ルールを読んでいない」ではない。ルールを強制する仕組みがそのマシンで動いていないか、 経路が沈黙して壊れているかのどちらかである。この指示書は、その2つを機械的に潰す設計を渡す。

---

1. 何を hook にするか（3層で考える）

層	発火点	役割	例
禁止	ツール実行前 (PreToolUse)	拒否する	使用禁止モデルの指定を deny
誘導	依頼受領時 (UserPromptSubmit)	依頼を分類し具体コマンドを注入	実装→定額CLI / 分類→激安API / 長文脈→大容量文脈API
担保	セッション開始時 (SessionStart)	hookが登録されているか自己点検し欠落を自動修復	必須hook棚卸し＋再登録

3層目が抜けると全部無意味になる。 これが冒頭の「別PCで一度も実行されていない」の正体である。

落とし穴: 配布とインストールは別物

• 日次同期スクリプトが「hookのファイル」を更新しても、設定ファイルへの登録はインストール時のままになりがち。 → インストール後に追加した hook は、既存マシンに永久に届かない。
• 対策: 同期処理の最後に登録処理を必ず呼ぶ（冪等に）。さらに SessionStart で 「必須hookの一覧」と実際の設定を突き合わせ、欠けていたら自動で登録し1行だけ報告する。 揃っていれば何も出力しない（無音が正常）。

// hook-selfcheck: SessionStart で必須hookの欠落を検出→自動修復
const REQUIRED = [
  ['PreToolUse', 'model-guard.mjs'],
  ['UserPromptSubmit', 'routing-gate.mjs'],
  ['SessionStart', 'hook-selfcheck.mjs'],
];
const missing = REQUIRED.filter(([ev, s]) =>
  !(settings.hooks?.[ev] || []).some(g => (g.hooks || []).some(h => String(h.command||'').includes(s))));
if (missing.length) {
  spawnSync(process.execPath, [registrar, '--hooks-only'], { env: { ...process.env, HOME_OVERRIDE: home } });
  console.log(`🚨 必須hookが ${missing.length} 本欠落していたため自動登録しました（次回セッションから有効）`);
}
process.exit(0); // 失敗しても必ず 0（エージェント本体を壊さない）

登録処理の冪等判定は「拡張子を無視」する

同じhookに OS 別の実装（.ps1 と .mjs など）があると、拡張子込みで重複判定すると二重登録になり 同じ内容が2回注入される。判定は拡張子を落として行い、**旧実装は置換（migrate）**する。

const base = scriptName.replace(/\.(mjs|ps1|sh)$/, '');
if (registered.some(cmd => cmd.includes(base))) return false; // 既にある

また、既に登録済みのエントリは「追加」処理でスキップされるので、timeout などの属性変更は届かない。 属性を変えたいなら「既存エントリを書き換える」処理を別に用意する。

---

2. 禁止は「集計」でなく「拒否」でやる

よくある失敗: 使用禁止のはずのモデルが、日次レポートの事後集計にしか登場しない。 これは「気をつけよう」以上の効果を持たない。ツール実行前フックで拒否する。

• エージェントがサブエージェントを生成するツールも拒否対象に含める。 ここを見落とすと「本体は守るがサブエージェント経由で全部素通り」になる。
• 探索・読み取り専用の用途は除外する（過剰なブロックは信頼を失う）。

例外は「人の明示指定」で自動的に通す

「どうしても使いたい時は hook を外してください」は運用が壊れる（外したまま戻らない）。 発話を見られる層（依頼受領時）で明示指定を検知し、短命の許可トークンを書く。

// 依頼受領時: 明示指定を検知して 60分・同一セッション限りの許可を発行
if (/明示指定の正規表現/.test(prompt) && !/使うな|禁止|避けて/.test(prompt)) {
  writeJson(allowFile, { until: Date.now() + 60*60*1000, sessionId, prompt: prompt.slice(0,120) });
}
// ツール実行前: deny の前に許可を検証（期限内かつ同一セッション）
if (violating && !validAllow(allowFile, sessionId)) return deny(reason);

時間とセッションで自動失効するので、許可が残留しない。否定文脈（「〜は使うな」）で発行しないこと。

---

3. 段階的エスカレーション（warn → block）

最初から全部ブロックすると作業が止まり、回避策が横行する。 観測 → 警告 → 改善しなければ拒否の順に上げる。判定は状態ファイルに書き、hook が読む。

{ "mode": "warn", "reason": "観察中", "metric": 0.06, "target": 0.30 }

• 目標を大きく下回る（例: 目標の1/3未満）ときは観察期間を短縮して即 block に上げる。
• 必ず脱出ハッチを用意する（オーバーライド用ファイルの作成 / 指標が改善したら自動で warn に戻る）。
• 拒否メッセージには代わりに実行すべき具体コマンドを必ず書く。禁止だけ告げると人は詰まる。

---

4. 「失敗が沈黙する経路」を疑う（ここが本命）

ルールを強制できても、委譲先が静かに死んでいると全部エージェント本体に戻ってくる。実際に踏んだもの:

症状	真因	対策
全APIキーが「未設定」判定	設定ファイルが UTF-8 BOM 付きで、1行目が KEY= になり startsWith('KEY=') が外れる	共有パーサに集約（BOM除去 / export KEY= / KEY = "v" / コメント / 重複は最後 / CRLF）。既存ファイルはバックアップ付きで自動修復
CLIは入っているのに書き込めない	サンドボックスが読み取り専用に固定されるプラットフォームがある	「導入済みか」ではなく**「その用途に使えるか」で判定**。使えないなら具体的な代替経路を出す
外部CLIの起動が必ず失敗	shell 経由で引数を引用符付きで渡すと壊れる環境がある	shell を介さない配列渡しで起動する
自動導入が永久に完了しない	導入コマンドが数十秒〜数分かかるのに、hookには timeout があるため毎回途中で殺される	重い処理は切り離して起動し即座に戻る。報告は「開始しました（次回有効）」と正直に書く。二重起動は状態ファイルで防ぐ
委譲率が実際より低く出る	委譲先のログが別のファイルシステム配下（仮想環境の中など）にあり集計対象外	集計対象パスに仮想環境側も含める

共通する教訓: これらは全部エラーを出さない。だから「導入した」「配った」で完了と判断してはいけない。 実際に実行して、期待する副作用（ファイルが書かれた・キーが読めた・差分が出た）を確認するまでが1タスク。

---

5. 「決めた施策が実際に使われたか」を可視化する

使われていない施策は存在しないのと同じ。定期レポートに使用回数0を⚠️で名指しする表を出す。

| 実行者/施策 | 使用回数 | 判定 |
|---|---:|---|
| 激安API      |  87 | ✅ |
| 長文脈API    |   0 | ⚠️ 使用0 |
| 夜間バッチ   |   3 | ✅ |
| 禁止モデル   | 558k tok | 🚨 検出 |

集計のモデル分類に禁止対象を明示的に入れること。分類漏れで「その他」に丸められると、 最も見たい違反が永久にレポートに現れない（実際にそうなっていた）。

---

6. テストの作り方（ここで必ずハマる）

hook は「壊れると全作業が止まる」ので、テストは必須。ただし次を守る。

1. 本物のホームディレクトリを絶対に触らない。 環境変数でホームを一時ディレクトリに差し替えて実行する。 差し替えを忘れたテストは、本番の状態ファイルが変わった瞬間に落ちる（例: モードが warn→block に昇格した途端に失敗）。
2. プラットフォーム依存の値を固定値で期待しない。 「導入先 = native」と書くと別OSで必ず落ちる。 実行環境から期待値を導出する。
3. テスト用の差し替え口を実装側に用意する（導入コマンドの置換、検出結果の強制）。 未設定時は挙動に一切影響しないこと。これが無いと「未導入の経路」を再現できない。
4. 重い処理が同期的にブロックしないことを時間で検証する（例: 20秒かかる導入コマンドを与えても本体は数秒で戻る）。
5. 秘匿値は状態だけを検証し、値をログに出さない。

---

7. 委譲を「抜け道より楽」にする

規律は禁止だけでは定着しない。正規ルートが最短になるようにする。

• 長い起動コマンドを毎回組み立てさせない。1コマンドのラッパーを用意する。
• ラッパーが蓄積コンテキストを自動で同梱する（別のCLIはこちらの記憶を継承しないので、 素で投げると気が利かない）。関連する知見ファイルだけをキーワードで選んで渡す。
• 実行後に差分の要約を出し、使用実績を台帳に記録する（＝委譲率の指標が自動で上がる）。
• 「実装を依頼したのに差分が空」なら警告して非ゼロ終了する。黙って成功扱いにしない。

---

8. 並行作業の事故（共有作業ツリー）

同じリポジトリを複数のエージェントセッションが同時に触ると、作業ツリー・ステージ領域・HEAD が共有される。

• git commit -a / git add -A は他セッションの進行中作業を巻き込む。 対象ファイルを列挙して stage する。
• 自分が触っていないファイルが変更されていたら、消す前に持ち主を確認する（原則そのまま放置）。
• 長い作業は作業ツリーごと分離する（git worktree add）。共有ツリーの HEAD を切り替えない。

---

導入チェックリスト

• 禁止事項はツール実行前フックで拒否しているか（サブエージェント生成ツールも対象に含めたか）
• 明示例外が手作業ゼロで通り、時間とセッションで自動失効するか
• 依頼受領時に「用途別の具体コマンド」を注入しているか（禁止だけになっていないか）
• セッション開始時に必須hookの欠落を自己修復するか（無音が正常）
• 日次同期が登録処理を呼ぶか（ファイル更新だけになっていないか）
• 設定ファイル読込は BOM・表記ゆれに強い共有パーサ経由か
• 「導入済み」ではなく**「その用途に使えるか」**で判定しているか
• 重い自動修復は切り離し起動で hook の timeout を超えないか
• レポートに使用回数0を名指しする表があるか
• テストは一時ホームで走り、プラットフォーム依存の固定値を期待していないか