CLAUDE.mdに、git add -Aは使わない、と書いてあります。それでもある日、エージェントはgit add -Aを打ちます。指示書に書いた規則は、モデルが読んで、覚えていて、その場で思い出したときにだけ守られます。長い作業の終わりや、文脈が圧縮された後は、思い出さないことがあります。
当社は2026年9月に、こういう規則のうち判断の要らないものを、指示書からhookに降ろしました。hookは、Claude Codeがツールを実行する前後に自動で動くスクリプトです。モデルが忘れても、スクリプトは忘れません。この記事は、当社が動かしている8本の検査と、その書き方を扱います。読者は、Claude CodeかCodex CLIで日常の作業を回していて、指示書に書いた規則が守られない場面に当たった人です。確認日は2026年10月13日です。
結論を先に書きます。
- 判断の要らない規則は、hookに降ろします。 禁止コマンド、秘密値、禁止語、URLの有無のような、正規表現で判定できるものです。判断が要る規則は指示書に残します
- hookには、止める型と差し戻す型があります。 実行前のhookは終了コード2で操作を止められます。実行後のhookは止められず、理由をモデルに返して直させます
- hookは動いていないことに気づきにくい仕組みです。 失敗した hook はデフォルトで操作を通し、Codex側では信頼するまで動きません。初回と変更のたびに、わざと違反して確かめます
hookの仕組み
Claude Codeのドキュメントによると、hookはツールの実行前（PreToolUse）、実行後（PostToolUse）、セッションの開始、プロンプトの送信など、30を超える出来事に結びつけられます。設定は.claude/settings.jsonに、出来事、対象のツール名、実行するコマンドの3段で書きます。コマンドは標準入力でJSONを受け取ります。JSONには、ツール名、ツールへの入力（Bashならcommand、Writeならfile_path）、作業フォルダー、セッションIDが入っています。
終了コードの意味は、実行前と実行後で違います。実行前のhookが終了コード2で終わると、ツールの呼び出しは止まり、標準エラーに書いた文がモデルに理由として渡ります。実行後のhookが終了コード2で終わっても、ツールは既に動いているので止まりません。標準エラーの文がモデルに見える、という点だけが同じです。終了コード0で標準出力にJSONを返して許可や拒否を伝える方法もありますが、当社は使っていません。違反なら2、それ以外は0で終わる、という単純な形です。ドキュメントは、方針を守らせたいなら終了コード1ではなく2を使え、と書いています。JSONを返さない場合、1は止めない扱いだからです。
Codex CLIにも同じ型のhookがあります。設定は.codex/hooks.jsonに書き、出来事の名前と入力のJSONの形はほぼ同じです。当社は、検査の本体をPythonのスクリプトにして、両方の設定から同じファイルを呼んでいます。入力の形の違いは、スクリプト側の小さな読み取り関数で吸収しました。Codex側の設定はリポジトリからの相対パスでスクリプトを指しているので、リポジトリの直下で起動する前提です。この両対応の考え方は、4層に分けて持つ記事に書いています。
当社の8本
当社のhookは2本のスクリプトです。実行前に動くのが1本、書き込みの後に動くのが1本で、その中に8つの検査が入っています。
| 番号 | いつ | 何を見る | 見つけたら |
|---|---|---|---|
| H1 | Bashの実行前 | コマンドの文字列にgit add -A、git add .、git add --allの形 | 止める。パスを指定してaddするよう返す |
| H8 | Bashの実行前 | git commitのコマンドの文字列にCo-Authored-By:が無い（amendは対象外） | 止める。どのモデルのセッションで作ったかを本文に残させる |
| H2 | WriteとEditの後 | 対象の拡張子のファイルに、APIキー、アクセストークン、秘密鍵の形をした文字列 | 差し戻す。値は書かず、1Passwordの参照名にさせる |
| H3 | WriteとEditの後 | 文書の保存先のファイルに、禁止リストに登録した顧客の実名や識別子 | 差し戻す。伏せ字にさせる |
| H4 | WriteとEditの後 | 原稿の保存先の.mdと.htmlに、文章規約の違反（ダッシュ、禁止語、自己言及） | 差し戻す。規約の検査スクリプトの結果を返す |
| H5 | WriteとEditの後 | SNS本文の保存先の.txtのうち、ファイル名でInstagramとThreads向けと分かるものに、httpかhttpsのURL | 差し戻す。本文からURLを外させる |
| H6 | WriteとEditの後 | .mdの中の公開日の項目が、実行した日より未来 | 警告だけ返す。公開時期は人が決める |
| H7 | WriteとEditの後 | 原稿と営業資料の保存先の.mdに、円や月額のような価格の語があり、提案か確定かを示す語が無い | 警告だけ返す。どちらかを明記させる |
8本に共通するのは、どれも人がすでに決めた規則で、正規表現と保存先で判定できることです。git addの形、文字列の形、ファイルの保存先とファイル名、日付の大小。モデルの判断は要りません。逆に言えば、どれも形で判定する補助の検査で、網羅はしません。H2は、参照名の行と例示の行を除外しますし、対象の拡張子に無いファイルは見ません。H3は、ローカルの禁止リストに登録した文字列を探すだけなので、リストの更新が要ります。H7は、価格の語と状態の語の有無を見るだけで、金額と承認の状態が対応しているかは人が判断します。
H1とH8は実行前です。git add -Aは、他のセッションが作りかけていたファイルを巻き込んでコミットする原因になります。ステージングは戻せますが、気づかずにコミットして共有した後は、取り消しに時間がかかります。だから、実行の前に止めます。署名行も同じで、コミットした後に足すには履歴の書き換えが要るので、前に止めます。
H2からH7はWriteとEditの後です。Writeの操作を事前に止めることもできますが、書く内容を事前に検査するにはツールへの入力の全文を読む必要があり、Editの差分では文脈が足りません。書き込まれた後のファイルを丸ごと読んで検査し、見つかったら理由を返して直させる、という形にしました。この型では、違反した内容が一度はディスクに書かれます。また、対象はWriteとEdit（Codexではapply_patchも）の後だけで、Bashのリダイレクトやスクリプト経由の書き込みは通りません。
H6とH7は、終了コードは2で返しますが文面は警告です。未来の公開日は、予約公開の原稿では正しいからです。H6は、本人の指示があるなら無視してよい、と添えて返します。H7は、どちらかを明記するよう求めます。機械で白黒をつけられない規則は、hookの中でも警告にとどめます。
1回の操作がhookを通る流れ
スクリプトの動きを、2つの場面で追います。
エージェントがgit add -Aを打とうとします。Bashの実行前にpre-bash.pyが起動し、コマンドの文字列を受け取ります。H1に当たるので、終了コード2で終わり、標準エラーに理由を書きます。コマンドは実行されず、モデルには、git add -Aは禁止、git status --shortで確認してパスを指定してaddする、という文が渡ります。
エージェントが原稿を書きます。Writeが実行されてファイルができた後にpost-write.pyが起動し、ファイルのパスを受け取ります。原稿の保存先なので、文章規約の検査スクリプトを呼びます。ダッシュが1つ見つかれば、終了コード2で終わります。ファイルは書かれたままですが、モデルには違反の箇所が渡ります。
hookが保証するのは、ここまでです。止めることと、理由を渡すこと。次のターンでモデルがパスを指定したaddに変えるか、ダッシュを言い換えるかは、モデルの側の動きです。直ったかは、次の書き込みで同じ検査がもう一度走ることで確かめます。hookの文面は、モデルに向けて書きます。何が悪いかだけでなく、代わりに何をするかを1文で添えます。理由だけ返すと、モデルが別の回避策を試すことがあるからです。
指示書に残すか、hookに降ろすか
当社は、規則の置き方を4つに分けています。横軸は、正規表現やスクリプトで判定できるか。縦軸は、違反したときに取り返しがつくか。
- 機械で判定でき、取り返しがつかない。 実行前のhookで止めます。git add -Aの形、履歴の書き換えの形。本番環境への配置や外部への送信のように損害が大きい操作は、hookではなく権限設定で人の承認を挟み、hookは重ねる検査にします。ドキュメントも、確実に許可や拒否をしたいならhookではなく権限の仕組みを使え、と書いています
- 機械で判定でき、取り返しがつく。 実行後のhookで差し戻します。禁止語、URLの有無、日付。当社の秘密値の検査もここにありますが、書かれること自体が問題なら実行前に移します
- 機械で判定できず、取り返しがつかない。 権限設定で人の承認を挟みます。外部への送信、削除、課金
- 機械で判定できず、取り返しがつく。 指示書に残します。文体、構成、どの資料を優先するか
hookに降ろすと、指示書に書く量を減らせます。消すのは、判定の手順です。規則の目的と、hookが見ていない経路は指示書に残します。当社のAGENTS.mdにも、git addはパスを指定する、署名行を入れる、という一行は残っていて、hookはそれを機械で裏打ちしています。指示書を痩せさせる記事で書いた、追記は簡単で削除は難しい問題に対して、追記以外の手段を持つ、ということです。
誤検知を避ける書き方
8本を動かして、直した点が2つあります。
散文の中の禁止パターンを拾わない。 最初の版では、コミットメッセージに、git add -Aを禁止した、と書くだけでH1が反応しました。今のpre-bash.pyは検査の前に、ヒアドキュメントの本文と引用符の中身を落としてから正規表現を当てます。散文の誤検知は減りましたが、引用符の中に実行コマンドを書く形や、git add -Aを別の書き方にした形は見逃します。H1は典型的な書き方を止める補助の検査で、シェルの構文を解析するものではありません。
社内文書と公開文書で強さを変える。 文章規約の検査は、公開向けの原稿の保存先でだけ動かします。社内の記録にまで同じ規約を当てると、作業の記録が書けなくなります。リポジトリからの相対パスの先頭で判定しています。
注意点
hookは失敗すると操作を通します。 ドキュメントによると、hookが落ちた、見つからない、時間切れになった場合、デフォルトでは操作はそのまま進みます。実行前のhookなら、v2.1.295以降で使えるonFailureの設定でblockを指定すると、失敗時に止められます。当社はまだ設定していません。実行前のhookが時間切れになった場合も止まらないので、検査は軽く保ちます。デフォルトの上限は両方の道具とも600秒ですが、当社の設定では、実行前は20秒、書き込み後は90秒にしています。
Codex側は信頼するまで動きません。 Codexのドキュメントによると、管理されていないhookは、/hooksで確認して信頼するまで実行されません。新しく足したhookと、定義を変えたhookは、もう一度信頼するまで飛ばされます。定義が指しているPythonのファイルの中身を変えた場合に再確認の対象になるかは、ドキュメントからは読み取れませんでした。hookを変えたら、わざと禁止語を書いて、差し戻しが返ることを確かめてください。
実行後のhookは書き込みを防げません。 秘密値のように、一度書かれること自体が問題になる内容は、実行前のhookか、権限設定で止めます。当社のH2は差し戻しの型なので、書かれた値はモデルが消すまでディスクに残ります。コミットの前に止めたいなら、実行前のhookでgit addとgit commitの対象ファイルを検査する形に移します。
hookは任意のシェルコマンドです。 ドキュメントも、自動で動く任意のコマンドだと明記しています。他人のリポジトリのhookは、中身を読んでから有効にします。Claude Codeのプロジェクトのhookは、対話のセッションではフォルダーを信頼した後に動きます。-pの非対話の実行やSDKでは信頼の確認が出ないので、起動の前にリポジトリの設定を見ておきます。
KOIYALの見解
指示書に規則を書き足していくと、指示書は長くなり、1つの規則が思い出される機会は減ります。当社は、守られなかった規則が出るたびに、それが機械で判定できるかを先に問います。できるなら、指示書に太字で書き直すのではなく、hookに1つ検査を足します。H1のgit addの形も、H5のURLの有無も、H7の提案か確定かの別も、指示書に書いてあったのに守られなかった規則から生まれました。
インハウス経営（AIを活用し、自社で業務を改善し、自社で仕組みをつくる経営）で言えば、hookは、会社の規則を道具の中ではなく、自社のリポジトリの中に置く手段です。モデルを替えても、検査のスクリプトは同じものが動きます。読者の会社で最初に自社でできるようになるのは、守られなかった規則を1つ選び、正規表現で判定できる形に書き直して、実行前か実行後のどちらに置くかを決めることです。これは、自社の規則を自社の言葉で定義し直す作業でもあります。
次の行動
- 自社のCLAUDE.mdかAGENTS.mdを開き、禁止や必須の形で書いてある規則に印を付ける
- 印を付けた規則のうち、正規表現で判定できるものを1つ選ぶ。最初はgit addの形か、秘密値の形が、判定が単純で効果が分かりやすい
- 実行前に止めるか、実行後に差し戻すかを決めて、終了コード2で理由を返すスクリプトを1本書き、わざと違反して動くことを確かめる
自社の規則をどこまでhookに降ろすかを決めるところから、一緒に作ることもできます。FDE型支援では、社外の推進チームが週1で入り、指示書と検査を自社のリポジトリに残して離れます。お問い合わせの本文に、守られなくて困っている規則を1つ書いていただければ、どこに置くかの判断から始められます。