AIエージェントが自作のライブラリを使ってくれない。AGENTS.mdに一行足しても、しばらくするとまた素通りされる。Geoffrey Huntley氏の解き方は、ルールを文書に足すのをやめて、コミットの関所に移すことでした。違反した差分が来たらコミットを止め、エラーメッセージとして「次に何をすべきか」をエージェントへ返す。その最小構成を、このブログ自身のルールで実際に動かしてみました。
AGENTS.mdに書いたルールがなぜ少しずつ守られなくなるのかという仕組みと、差分だけを見て落とし、直し方を返すpre-commitフックの最小例(約15行・実行ログ付き)が手に入ります。あわせて、どのルールをフックに移し、どのルールを文書に残すかの仕分け基準と、--no-verifyによる抜け道の塞ぎ方も整理しました。
発端は、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氏の引用部分だけを根拠にしています。「毎回守られた」という効果は氏の報告で、筆者が測ったものではありません。
AGENTS.mdやCLAUDE.mdは、セッションの最初にコンテキストへ入る長い説明書です。ルールを書いても、守られるかどうかは確率の問題になります。
説明書が長くなるほど、一つひとつのルールは埋もれます。このブログでもArchUnitの記事で書いたとおり、ルールは増えるほど守られなくなります。直す側がルールを1行足すたびに、他のルールが少しずつ薄まっていきます。
そもそも、書いたファイルが読まれているとは限りません。CLAUDE.mdとAGENTS.mdのどちらが実際に読まれていたかを確かめた記事では、置いたはずのルールが読み込まれていない構成がありえることを確認しました。文書ベースのルールは、届く経路そのものが壊れることがあります。
pre-commitフックは、コミットしようとしている変更を毎回必ず調べます。記憶にも注意力にも頼りません。しかも反応するのは違反が起きた瞬間だけなので、指示が必要なときに、必要な分だけコンテキストに入ります。ルールを常に説明書に載せておく必要がなくなります。
ここが核心。このフックの本体は検出よりもエラーメッセージのほうです。エージェントは失敗した git commit の出力を読み、そこに書かれたとおりに直します。エラーメッセージは、違反した瞬間にだけ届く、その場に合った指示として働きます。
題材には、このブログで実際に運用しているルールを使いました。記事の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
(フックは何も出力せず、コミットが作成された)
git diff --cached -U0 で、ステージ済みの追加行(先頭が +)だけを検査します。過去のファイルに残っている違反では止めないので、導入した初日から全コミットが止まるということがありません。※この確認は検証用の使い捨てリポジトリで行ったもので、まだ本番の執筆フローには組み込んでいません。エージェントが失敗出力を読んで自分で直す部分は、Huntley氏の報告と、Claude Codeが失敗したコマンドの出力をそのまま受け取る仕組みに基づく見立てです。
フックが向くのは、機械で検出できて、直し方が一つに決まるルールだけです。それ以外を無理にフックにすると、誤検知でコミットが止まり続けるだけになります。
--no-verifypre-commitフックは git commit --no-verify で飛ばせます。Claude Codeは既定で「明示的に頼まれない限りフックを飛ばさない」よう指示されていますが、それも文書によるルールです。念を入れるなら、Claude Code側の PreToolUse フックで、--no-verify を含むBashコマンドを実行前に拒否しておきます。CLAUDE.md・スキル・フックの使い分けの記事で整理した「必ず起きてほしいことはフックで」という原則を、関所の抜け道にもう一段かける形です。
サーバー側でも止めたい場合は、CIで同じスクリプトを走らせます。ローカルのフックは手元での即時のフィードバック、CIは最後の砦、と役割を分けると、同じ検査を二度書かずに済みます。
最初から仕組みを作り込む必要はありません。AGENTS.mdやCLAUDE.mdを開き、直近で破られたルールを1つ選ぶところから始めます。
git diff --cached -U0 の ^\+ 行に絞り、既存の違反で止めない。--no-verify を PreToolUse で拒否するか、CIで同じ検査を回す。AGENTS.mdに書く1行は「お願い」で、フックが返す1行は「関所での案内」です。お願いが何度も無視されたルールは、お願いを書き直すのではなく、関所に移すほうが早く片づきます。