# 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行だけ報告**する。 揃っていれば何も出力しない（無音が正常）。 ```js // 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）**する。 ```js const base = scriptName.replace(/\.(mjs|ps1|sh)$/, ''); if (registered.some(cmd => cmd.includes(base))) return false; // 既にある ``` また、既に登録済みのエントリは「追加」処理でスキップされるので、**timeout などの属性変更は届かない**。 属性を変えたいなら「既存エントリを書き換える」処理を別に用意する。 --- ## 2. 禁止は「集計」でなく「拒否」でやる よくある失敗: 使用禁止のはずのモデルが、**日次レポートの事後集計にしか登場しない**。 これは「気をつけよう」以上の効果を持たない。ツール実行前フックで**拒否**する。 - エージェントが**サブエージェントを生成するツール**も拒否対象に含める。 ここを見落とすと「本体は守るがサブエージェント経由で全部素通り」になる。 - 探索・読み取り専用の用途は除外する（過剰なブロックは信頼を失う）。 ### 例外は「人の明示指定」で自動的に通す 「どうしても使いたい時は hook を外してください」は運用が壊れる（外したまま戻らない）。 **発話を見られる層（依頼受領時）で明示指定を検知し、短命の許可トークンを書く**。 ```js // 依頼受領時: 明示指定を検知して 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 が読む。 ```json { "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を名指しする表**があるか - [ ] テストは一時ホームで走り、プラットフォーム依存の固定値を期待していないか ---