【ハーネス実践】フックで決まりを守らせる|「指示ファイルに書いたのに守ってくれない」を解く

【ハーネス実践】フックで決まりを守らせる|「指示ファイルに書いたのに守ってくれない」を解く AIエージェント

指示ファイルに「本番用の設定ファイルは編集しないこと」とはっきり書いたのに、エージェントがそのファイルを書き換えていた。そんな経験はありませんか? 「編集したら必ず整形ツールをかけて」と書いても、かけたりかけなかったりする。書き方が悪いのかと思って、指示ファイルの文言を何度も直している方もいるかもしれません。

実は、これは書き方だけの問題ではありません。指示ファイルに書いた内容は、エージェントにとっては「お願い」です。モデルが読んで、解釈して、従うかどうかを決めます。たいていは守ってくれますが、「必ず」守られる保証はありません。

本記事では、お願いではなく仕組みで決まりを守らせるフックを、研究と各ツールの公式ドキュメントから整理します。シリーズ第 4 回。H1 で示した部品の地図でいう「拡張(フック)」の話で、第 2 回の指示ファイルと対になる回です。

お願い(指示ファイル)と強制(権限・フック)の違い

エージェントに決まりを守らせる方法は、大きく 2 つに分かれます。

一つは「お願い」です。第 2 回で扱った CLAUDE.md や AGENTS.md などの指示ファイルがこれに当たります。モデルが読んで従う前提の文章なので、柔軟に解釈してくれる反面、確実ではありません。Claude Code の公式ドキュメントも、CLAUDE.md は強制される設定ではなくコンテキストとして扱われると明記し、どんな場合でも止めたい操作には PreToolUse フックを使うよう案内しています(Claude Code「How Claude remembers your project」)。

もう一つは「強制」です。モデルの判断とは関係なく、ハーネス(モデルの外側でループやツールや権限を決める仕組み)が機械的に止めたり実行したりします。第 3 回の権限ルールやサンドボックスと、今回のフックがこちらに入ります。

フックとは、エージェントの動きの決まった時点、たとえば「ツールを実行する直前」や「ファイル編集のツールを実行した直後」に、自分で用意したコマンドやスクリプトを必ず実行させる仕組みです。実行前のフックで中身を検査して止めることも、実行後のフックで整形やログ記録をすることもできます。Claude Code のドキュメントは、フックを「LLM が実行を選ぶかどうかに頼らず、特定の動作が必ず起きる決定的な制御」と説明しています(Claude Code「Automate workflows with hooks」)。ただし、どこまで止められるかはイベントや失敗時の扱いで変わり、実行後のフックはすでに行われた操作を取り消せません。

では、指示ファイルに書かれた決まりのうち、どれくらいが強制の仕組みに置き換えられるのでしょうか。

📄 論文: 指示ファイルの決まりは強制できるか

When “Do Not” Is Not Deny: Security Rules in CLAUDE.md vs Built-In Controls(Ting Yan、2026年8月、arXiv:2608.23550)は、単著の査読前の論文(プレプリント)です。

この研究は、公開されている 481 個の CLAUDE.md からセキュリティに関する決まりを取り出し、それぞれが Claude Code の組み込みの制御(権限ルール・モード・サンドボックス)で強制できるかを調べました。対応づけは LLM で行い、その一部を 2 人のセキュリティ実務者が、互いの判断を見ずに確かめています。

結果、組み込みの制御で対応できた決まりは、記述と制御がどこまで近く一致することを求めるかによって約 4〜16%(厳しい基準ほど低い)にとどまりました。残りの多くは、モデルの解釈に任されたままの「お願い」です。なお、取り出し方法は対象となる決まりの 66.3% を拾えたと著者自身が報告しており、数値はその範囲のものです。本文では、フックは追加のコードが必要なので「組み込みの制御」には数えず、フックや CI の検査を書き足せば強制できる決まりを別に分類しています。

この研究は 1 つのツールの制御を物差しにしていますが、教訓はツールを問いません。著者は、指示ファイルは「書いても強制されるかどうかの反応が返ってこない」一方通行の経路だと指摘しています。現場にとっての意味は、セキュリティの決まりを書いたら、それが強制される仕組みにつながっているかを、人が一つずつ確かめる必要があるということです。

📄 論文: 効くお願い・効かないお願い

Guardrails Beat Guidance: A Large-Scale Study of Rules, Skills, and Persistent Configuration for Coding Agents(Xing Zhang ほか、2026年4月、arXiv:2604.11088)は、査読前の論文(プレプリント)です。題名の「Guardrails(ガードレール)」は「〜するな」型の決まりのことで、実行時に機械的に止める仕組みの意味ではありません。

研究チームは GitHub から 679 個のルールファイル(決まりの数で 25,532 件)を集め、1 つのエージェントと 1 つのモデルの組み合わせで、ソフトウェア開発の課題を 5,000 回以上解かせて、決まりの効き方を比べました。

結果、単体で役に立った決まりはすべて「関係ないコードをリファクタリングするな」のような否定の形で、害になった決まりはすべて「コードスタイルに従え」のような肯定の形でした。また、SWE-bench Verified のうち差が出やすい課題に絞った評価では、ランダムに選んだ決まりでも、専門家が選んだ決まりと同じだけ(どちらも 13.8 ポイント)成績が上がっており、中身よりも「何か決まりがある」こと自体が効いている可能性も示されました。

著者らは、すべきことを指示するより、してはいけないことで縛るのを原則として挙げています。現場にとっての意味は、お願いを書くなら「〜するな」の形を試す価値がある、ということです。ただし 1 つのエージェントとモデルの組み合わせでの結果で、否定形なら効くと一般化できるものではないので、自分の環境で確かめましょう。

📄 論文: 実行時に決まりを強制する

AgentSpec: Customizable Runtime Enforcement for Safe and Reliable LLM Agents(Haoyu Wang ほか、2025年3月、arXiv:2503.18666)は、ICSE 2026 採録の論文です。

この研究は、エージェントが守るべき決まりを「きっかけ(どの操作のときに)」「条件(何を満たしたら)」「対処(どう止めるか)」の組で書ける小さな専用言語を提案し、実行時に機械的に当てはめる仕組みを作りました。コードを実行するエージェントのほか、ロボットや自動運転の分野でも評価しています。

論文のコードを実行するエージェントの評価では、危険な実行のケースの 90% 超を防ぎ、かかる負荷はミリ秒単位でした。

現在の主要ツールのフックは、「ツールを実行する直前に、自前の検査を差し込んで止める」という点で、この考え方と共通しています(論文の方式そのものではありません)。現場にとっての意味は、実行時の強制は重い仕組みではなく、軽い検査を決まった場所に差し込むだけでも効果が期待できる、ということです。

実践:フックで決まりを守らせる

研究と公式ドキュメントを合わせると、フックは次の手順で入れていくのがよさそうです。

  1. 指示ファイルの決まりを仕分ける: 書いてある決まりを「権限ルールで止められるもの」「フックで検査できるもの」「お願いのままにするもの」に分けます。論文が示したとおり、組み込みの制御だけでは届かない決まりが多くあります
  2. 保護したいファイルを実行前のフックで守る: 本番用の設定ファイルや既存のマイグレーションなど、編集されると困るファイルへの変更を、ツール実行前のフックで検査して止めます
  3. 整形やテストは実行後のフックで必ず走らせる: 「編集したら整形して」というお願いは、ファイル編集後のフックで整形ツールを自動実行する形に置き換えます
  4. ログを残す: どのツールがいつ何をしたかをフックで記録しておくと、後から見直せます
  5. 失敗したときの動きを確かめる: フックのスクリプト自体がエラーになったとき、操作が止まるのか素通りするのかはツールや設定で違います。止めたい検査は、わざと失敗させて試しておきましょう

たとえば、ファイルの編集が終わるたびに、編集されたファイルのパスを受け取って整形ツールにかける、というフックは次のような設定になります。

Claude Code の .claude/settings.json に書くフックの例(jq と Prettier が入っている前提):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

(設定の書き方は 2026-10-01 時点の公式ドキュメント Claude Code「Automate workflows with hooks」 で確認。仕様は変わるため、使う前に最新の公式ドキュメントを確認してください)

各ツールのフックの在りかは次のとおりです。2026 年 10 月時点の各社公式ドキュメントに基づく。仕様は変わるため最新の公式ドキュメントを確認してください。

項目Claude CodeCodex CLIGemini CLIGitHub Copilot
設定の置き場所(プロジェクト).claude/settings.json の hooks[.codex/hooks.json・config.toml の [hooks]](https://learn.chatgpt.com/docs/hooks).gemini/settings.json の hooks.github/hooks/*.json
ツール実行前のイベントPreToolUsePreToolUseBeforeToolpreToolUse
ツール実行後のイベントPostToolUsePostToolUseAfterToolpostToolUse
止め方終了コード 2・permissionDecision の deny終了コード 2・permissionDecision の deny終了コード 2・decision の denypermissionDecision の deny
設定済みフックの確認/hooks/hooks/hooks panel/env(Copilot CLI)

GitHub Copilot のフックは、Copilot cloud agent(旧 coding agent)と Copilot CLI で使えます。

手順 5 の「失敗したときの動き」は、ツールによってはっきり違います。2026 年 10 月時点の公式ドキュメントでは、Claude Code は終了コード 2 だけが止める合図で、一般的な失敗の終了コード 1 では止まらず操作が続きます。Gemini CLI も、2 以外の終了コードは警告を出して先に進みます。Codex CLI は、未対応の項目を返した実行前フックや、MCP ツールを呼ぶ形のフックのエラーでは、ツールの実行が続くと書いています。一方、GitHub Copilot のコマンド型の実行前フックは、0 以外の終了コードやクラッシュでは操作を止める側に倒れますが、タイムアウトしたときは素通りします。「検査が壊れていたら素通りする」状態は気づきにくいので、必ず試しておきましょう。

もう一つ大切なのが、フック自体の安全です。フックは手元のコマンドを利用者の権限で実行する強い仕組みです。各社のドキュメントもこの点を注意しており、Codex CLI は新しいフックや変更されたフックを人が確認して信頼するまで実行しない仕組みを、Gemini CLI はプロジェクトのフックが変わると実行前に警告する仕組みを備えています。他人が書いたリポジトリのフック設定は、中身を読んでから取り込みましょう。また Codex のドキュメントは、ツールのフックを「完全な強制の境界ではなく、役に立つガードレール」として扱うよう書いています。フックだけに頼らず、第 3 回のサンドボックスや権限ルールと重ねて使うのが基本です。

筆者の現場では:決まりは 4 回破られ、道具に移した

筆者のチームには、「PR を出す前に、変更に関係する CI の検査を手元で全部回す」という決まりがあります。回す検査を記憶で選ぶと漏れるので、見落としが起きたときに「CI の設定ファイルから機械的に全部抜き出す」と指示ファイルに書き足しました。それでも、この決まりは書き足した後も破られ、合わせて 4 回になりました。原因は決まりの書き方ではなく、抜き出す手段が無かったことでした。たとえば CI の設定には複数行のコマンドのまとまりがあり、文字列で検索しても中身が見えないため、その中の検査が漏れたことがあります。

そこで、CI の設定を読んで「この変更に効く検査」と「その中身のコマンド」を全部出すスクリプトを作りました。ところが、今度は道具の使い方で外す事故が続きました。スクリプトは「どのフォルダで実行するか」を人が読むための注記として出していたのに、その出力を読んで実行する側がこの注記を落とし、別のフォルダで実行して偽の失敗を出したのです。最後は、そのまま実行できる形でコマンドを書き出すモードを足しました。決まりを「お願い」から「道具」へ、さらに「出力をそのまま使える道具」へと、2 段階で仕組みに寄せたことになります。

フックも同じ考え方で使っています。エージェントは、GitHub への書き込みや push、検証用コンテナの起動のあとに「完了しました」と報告しがちですが、実際の状態を確かめていないことがありました。そこで、ツール実行後のフック(PostToolUse)で gh・git push・検証用コンテナを起動・停止するスクリプトの実行を見張り、実行の直後に Issue の状態やラベル、手元とリモートのコミットが一致しているか、コンテナが動いているかを取り直して、エージェントの文脈に差し込んでいます。エージェントは自分の思い込みではなく、取り直した観測値を見て次の判断をします。

ここから言えるのは、指示ファイルで何度も破られる決まりは、守る気が足りないのではなく、守るための手段が欠けていることが多い、ということです。「何回破られたら仕組みに移すか」を決めておくと、判断に迷いません。

フックで決まりを守らせる鍵は次の3点です

  1. お願いと強制を分けて考える
    公開された指示ファイルのセキュリティの決まりのうち、対応する組み込みの制御があったのは約 4〜16% でした。絶対に守らせたい決まりは、指示ファイルではなく権限やフックに移しましょう。
  2. フックは「実行前に止める」「実行後に必ず走らせる」の 2 つから始める
    保護したいファイルの検査と、整形やテストの自動実行が入り口です。研究の評価でも、実行時の軽い検査で危険な実行の多くを防げていました。
  3. フックが失敗したときの動きを確かめ、重ねて守る
    エラーで素通りするかどうかはツールで違います。わざと失敗させて試し、サンドボックスや権限ルールと組み合わせましょう。

まとめ:「お願い」で足りないところは「仕組み」で守ろう!

指示ファイルは手軽で柔軟ですが、あくまでお願いです。研究からは、指示ファイルに書かれたセキュリティの決まりの多くが組み込みの制御では強制できないこと、そして実行時に軽い検査を差し込む仕組みが、評価で危険な実行の多くを防いだことが見えてきました。

まずは、いまの指示ファイルを開いて「これは絶対に守ってほしい」という行に印を付けてみましょう。その行が、権限ルールかフックで本当に強制されているか。一つずつ確かめるところから始めてみてください!

次回は、長い作業の途中でエージェントの調子が落ちる問題を、コンテキスト管理とサブエージェントから考えます。シリーズの一覧は /?p=209 へ。

参考文献

タイトルとURLをコピーしました