← AIバイブコーディングTips 一覧へ Pre-commit Hook / Agent Guardrail

AGENTS.mdに書いたルールは守られない。
コミットを落として"指示を返す"フックにした

AIエージェントが自作のライブラリを使ってくれない。AGENTS.mdに一行足しても、しばらくするとまた素通りされる。Geoffrey Huntley氏の解き方は、ルールを文書に足すのをやめて、コミットの関所に移すことでした。違反した差分が来たらコミットを止め、エラーメッセージとして「次に何をすべきか」をエージェントへ返す。その最小構成を、このブログ自身のルールで実際に動かしてみました。

この記事で手に入るもの

AGENTS.mdに書いたルールがなぜ少しずつ守られなくなるのかという仕組みと、差分だけを見て落とし、直し方を返すpre-commitフックの最小例(約15行・実行ログ付き)が手に入ります。あわせて、どのルールをフックに移し、どのルールを文書に残すかの仕分け基準と、--no-verifyによる抜け道の塞ぎ方も整理しました。

01 — 何が話されたか

「AGENTS.mdを直しても、差分は残って漂流する」

発端は、Simon Willison氏が2026年10月13日にブログで紹介したGeoffrey Huntley氏の発言です。

Huntley氏は、エージェントがチームの診断ライブラリを使わずに、ログやメトリクスのモジュールを直接呼んでしまう問題に悩んでいました。AGENTS.mdを見直して書き足すこともできます。ただ、それでは指示と実際の振る舞いのずれが残り、時間がたつほど広がっていく。氏はそれを「but there's still a delta, and it'll drift.」と言い表しています。

代わりに氏が書いたのがpre-commitフックです。git diffを調べ、診断ライブラリを通さずに観測系モジュールを直接呼んでいる行があれば、コミットを失敗させる。そのうえで「診断ライブラリを使え」というプロンプトをエージェントに返す。氏によれば、それ以降エージェントは毎回ルールどおりに直すようになったそうです。

出典: Quoting Geoffrey Huntley(Simon Willison's Weblog, 2026-10-13)。元になった記事は Huntley氏のブログ「nobody should type code by hand anymore」 で、Josh Wulf氏との対談をまとめたものです。本文の後半は購読者限定のため、フックの詳細はWillison氏の引用部分だけを根拠にしています。「毎回守られた」という効果は氏の報告で、筆者が測ったものではありません。


02 — なぜ漂流するのか

文書のルールは「読まれる確率」で効き、フックは「毎回」効く

AGENTS.mdやCLAUDE.mdは、セッションの最初にコンテキストへ入る長い説明書です。ルールを書いても、守られるかどうかは確率の問題になります。

01

ルールは他の指示と注意を奪い合う

説明書が長くなるほど、一つひとつのルールは埋もれます。このブログでもArchUnitの記事で書いたとおり、ルールは増えるほど守られなくなります。直す側がルールを1行足すたびに、他のルールが少しずつ薄まっていきます。

02

「書いた」と「読まれた」は別物

そもそも、書いたファイルが読まれているとは限りません。CLAUDE.mdとAGENTS.mdのどちらが実際に読まれていたかを確かめた記事では、置いたはずのルールが読み込まれていない構成がありえることを確認しました。文書ベースのルールは、届く経路そのものが壊れることがあります。

03

関所は「その場の差分」にしか反応しない

pre-commitフックは、コミットしようとしている変更を毎回必ず調べます。記憶にも注意力にも頼りません。しかも反応するのは違反が起きた瞬間だけなので、指示が必要なときに、必要な分だけコンテキストに入ります。ルールを常に説明書に載せておく必要がなくなります。

ここが核心。このフックの本体は検出よりもエラーメッセージのほうです。エージェントは失敗した git commit の出力を読み、そこに書かれたとおりに直します。エラーメッセージは、違反した瞬間にだけ届く、その場に合った指示として働きます。


03 — 実際に動かした

このブログのルール「OGPタグを手書きしない」をフックにする

題材には、このブログで実際に運用しているルールを使いました。記事のHTMLに og: や twitter: のメタタグを手書きしない、というものです。

このブログでは投稿スクリプトが、公開のたびにOGPタグを消して作り直しています。記事側に手書きしても上書きされるだけで、書けば書くほど混乱のもとになります。執筆用のスキルには「手書きしない」と明記してありますが、守らせる手段は文書しかありませんでした。検出しやすい(決まった文字列が出る)、直し方が一つに決まる(その行を消す)、という点でフック化に向いた題材です。

使い捨てのgitリポジトリを作り、次のフックを .git/hooks/pre-commit に置きました。

#!/bin/sh
# 記事HTMLに og:/twitter: タグを手書きしていないか、追加された行だけを見る
hits=$(git diff --cached -U0 -- '*.html' \
  | grep -E '^\+[^+].*(property="og:|name="twitter:)')
if [ -n "$hits" ]; then
  echo "$hits" >&2
  cat >&2 <<'MSG'
[pre-commit] コミットを止めました。
OGP/Twitterタグは記事に手書きしません。投稿時に blog_post.py が自動で作り直します。
上の行を削除して、もう一度コミットしてください。
MSG
  exit 1
fi

違反する行を足してコミットすると、次のように止まりました(Windows上のGit 2.54で確認)。

$ git commit -m og
+<meta property="og:image" content="x.png">
[pre-commit] コミットを止めました。
OGP/Twitterタグは記事に手書きしません。投稿時に blog_post.py が自動で作り直します。
上の行を削除して、もう一度コミットしてください。
exit=1

# 行を消して再コミット → 通過
$ git commit -m fix
(フックは何も出力せず、コミットが作成された)

書くときに効いた3つの工夫

※この確認は検証用の使い捨てリポジトリで行ったもので、まだ本番の執筆フローには組み込んでいません。エージェントが失敗出力を読んで自分で直す部分は、Huntley氏の報告と、Claude Codeが失敗したコマンドの出力をそのまま受け取る仕組みに基づく見立てです。


04 — 仕分けと抜け道

全部をフックにはしない。文書に残すのは「なぜ」と「判断」

フックが向くのは、機械で検出できて、直し方が一つに決まるルールだけです。それ以外を無理にフックにすると、誤検知でコミットが止まり続けるだけになります。

→
フックに移す文字列や構文で判定できるもの。例: 禁止APIの直接呼び出し、手書き禁止のタグ、秘密情報らしき文字列、決められたラッパーを通さない呼び出し。
→
文書に残す判断が要るもの、背景の説明。例: 設計の方針、命名の考え方、「なぜこのライブラリを使うのか」。フックのメッセージから文書の該当箇所を指すと、両方がつながります。
→
テストに回す差分の1行では判定できない構造上のルール。例: レイヤー間の依存の向き。これはArchUnitのような静的検証の役目です。

抜け道: --no-verify

pre-commitフックは git commit --no-verify で飛ばせます。Claude Codeは既定で「明示的に頼まれない限りフックを飛ばさない」よう指示されていますが、それも文書によるルールです。念を入れるなら、Claude Code側の PreToolUse フックで、--no-verify を含むBashコマンドを実行前に拒否しておきます。CLAUDE.md・スキル・フックの使い分けの記事で整理した「必ず起きてほしいことはフックで」という原則を、関所の抜け道にもう一段かける形です。

サーバー側でも止めたい場合は、CIで同じスクリプトを走らせます。ローカルのフックは手元での即時のフィードバック、CIは最後の砦、と役割を分けると、同じ検査を二度書かずに済みます。


05 — 今日やること

守られなかったルールを1つだけ選んで、関所にする

最初から仕組みを作り込む必要はありません。AGENTS.mdやCLAUDE.mdを開き、直近で破られたルールを1つ選ぶところから始めます。

✓
検出できるか確かめる違反がgrepで1行で拾えるか。拾えないなら文書かテストに残す。
✓
追加行だけを見るgit diff --cached -U0 の ^\+ 行に絞り、既存の違反で止めない。
✓
メッセージを指示として書く該当行・理由・次の一手の3点を必ず入れる。
✓
わざと違反してみる使い捨てブランチで違反コミットを試し、止まることと、メッセージが読めることを確認する。
✓
抜け道を塞ぐ--no-verify を PreToolUse で拒否するか、CIで同じ検査を回す。

AGENTS.mdに書く1行は「お願い」で、フックが返す1行は「関所での案内」です。お願いが何度も無視されたルールは、お願いを書き直すのではなく、関所に移すほうが早く片づきます。