AIへの「お願い」を「必ず」に変えるフック（Hooks）の作り方 —— Claude Code・Codexの実例と注意点

AIがルールを破るとき

AIが毎回読むルール（イメージ）

# 和菓子ECショップのルール
- .env はさわらない
- コードを直したら、整形する
- 終わる前に、テストを動かす

お店の注文サイトをAIのエージェントに直してもらうとき、CLAUDE.mdに「.envは触らない」「コードを直したら整形する」「終わる前にテストを動かす」と書いておいたとします。.envは、パスワードや鍵などの秘密の設定を入れておく大事なファイルです。

AIに注文サイトを直してもらう（イメージ）

ところが「注文ページを新しいデータベースにつないで」と頼むと、AIは「接続先を変えるため、.envを書き換えます」と言い出しました（イメージ）。AIは、ルールを読んでいても、悪気なくうっかりすることがあります。

ルールの文書は、あくまで「お願い」です。守るかどうかはAIの判断に委ねられます。[s2]そこで使うのが「フック」です。AIの作業の決まった場所に、自分のプログラムを引っかけておく仕組みで、Claude CodeにもCodexにもあります。[s1][s3]

AIに任せるときの3つの困りごと

AIに作業を任せるときの困りごとは、3つに分けられます。1つ目は、先ほどの.envのように、触ってほしくないファイルを変えてしまう「うっかり」。2つ目は、整形やテストをときどき飛ばす「やり忘れ」。3つ目は、AIが「実行していいか」と聞いたまま止まっているのに人が「気づかない」ことです。いずれも、AIの気分に任せずに毎回必ずやりたいことで、ここがフックの出番です。

フックとは何か

AIの作業の流れ（Claude Code）

AIは、指示を受け取ったあと、ファイルを書き換えたりコマンドを動かしたりといった「道具」を使う流れを、作業が終わるまで何度もくり返します。フックは、この流れの決まった場所に引っかけておけます。[s1]

たとえば道具を使う前の「PreToolUse」は、AIがファイルを書き換える直前に必ず動きます。道具を使った後は「PostToolUse」、返事を終えるときは「Stop」です。名前よりも、いつ動くかを押さえておけば十分です。[s1]

フックを付けられるタイミングは、Claude Codeで33種類、Codexで12種類あります。[s1][s3]よく使うのは、この3つに通知を加えた4つほどです。

フックはどう動くのか

フックの設定は3段

フックの設定に書くことは3つだけです。「いつ」（道具を使う前などのタイミング）、「どの道具のとき」（ファイルの編集だけ、のように絞り込む条件。matcherと呼ぶ）、そして「何を動かすか」（ふつうはコマンドやスクリプト）です。[s1][s3]

フックに届くJSON（イメージ）

{ "hook_event_name": "PreToolUse", "tool_name": "Edit", "tool_input": { "file_path": "/shop/.env", "old_string": "DB_HOST=old", "new_string": "DB_HOST=new" }
}

動かすスクリプトには、AIが何をしようとしているかがJSONの形で届きます。この例では、使う道具が「Edit」（ファイルの編集）で、書き換えようとしているファイルが.envであることが分かります。[s1]

終了コードの意味

止めるかどうかは、スクリプトの終わり方で伝えます。プログラムは終わるときに「終了コード」という番号を1つ返し、Claude Codeはその番号を見て次の動きを決めます。0は「問題なし」で、AIはそのまま作業を続けます。2は「止めて」で、作業を止め、スクリプトが書いた理由をAIに伝えます。[s1][s3]

止めるならexit 2

ここに落とし穴があります。1などそれ以外の番号は「フック自体が失敗した」と受け取られ、エラーが表示されるだけで、作業は続いてしまいます。[s1]止めたつもりで止まっていない、ということが起きるのです。止めたいときは、必ず2で終えることを覚えておきましょう。

.envを書き換えられると何が困るのか

.envを書き換えられると困ること

.envには、データベースの場所と合言葉、支払いサービスの鍵といった秘密の情報が入っています（イメージ）。書き換えられると、まず、接続先や合言葉がずれて注文ページが動かなくなります。次に、.envはGitで記録しないことが多いため、前の値に戻せません。[s9]そして、画面に出ない設定なので、何が変わったのかに気づきにくいのです。

# 秘密の設定は記録しない
.env
.env.*
!.env.example

大事なファイルなのにGitで記録しないのは、パスワードを、みんなが見るリポジトリに載せないためです。GitHubのNode向けの見本でも、.envは記録せず、書き方の見本（.env.example）だけを記録するようになっています。[s9]

秘密の情報をAIが扱う危険

秘密の情報は、AIに読ませるだけでも危険があります。AIが読んだ中身は会話と一緒にAIの会社のサーバーへ送られ、会話の記録はパソコンの中にもそのままの文字で残ります。[s6]AIが鍵をコードに書き写し、そのまま公開してしまうこともあります。[s10]さらに、読んだページに隠れた命令（プロンプトインジェクション）でAIがだまされ、鍵を外部に送るおそれもあり、どんな守りも完全ではありません。[s7]

秘密の情報の守り方

{ "permissions": { "deny": [ "Read(./.env)", "Read(./.env.*)", "Edit(./.env)" ] }
}

秘密の情報は、読ませない・書かせない・本物の鍵は渡さない、の3つで守るのが基本です。読ませないためには、権限の設定（permissionsのdeny）が確実で、公式も鍵を入れたファイルに使うよう勧めています。[s8]AIにはテスト用の鍵だけを渡し、もし漏れたらすぐに鍵を作り直しましょう。[s10]ここからは、このうち「書かせない」をフックで作ってみます。

実例① .envを守る（PreToolUse）

設定ファイル

{ "hooks": { "PreToolUse": [{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "python3", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.py"] }] }] }
}

書かせないためのフックは、道具を使う前（PreToolUse）に付けます。プロジェクトの設定ファイルには、タイミングを「PreToolUse」、matcherを「Edit|Write」（ファイルを直すときと新しく作るとき）と書きます。動かすものは「guard.py」というPythonのスクリプトです。[s1][s2]スクリプトの場所に使う「$CLAUDE_PROJECT_DIR」は、プロジェクトの場所に置き換わる目印で、どこから動かしても同じファイルを指せます。[s1]

スクリプトの中身

import json, sys data = json.load(sys.stdin) # AIの予定を読む
path = data["tool_input"].get("file_path", "") if path.endswith(".env"): print("人が管理するファイルです", file=sys.stderr) sys.exit(2) # 2 で止める sys.exit(0) # ほかは続ける

スクリプトはわずか10行ほどです。届いたJSONを読み込み、書き換えようとしているファイルの場所を取り出し、それが.envなら理由を書いて2で終わります。それ以外なら0で終わり、作業を続けてもらいます。[s1][s2]

AIを動かす前に試す

$ echo '{"tool_input":{"file_path":"/shop/.env"}}' | python3 guard.py
人が管理するファイルです
$ echo $?
2

AIを動かす前に、見本のJSONを流し込んで終わり方を確かめることもできます。2で終われば、止まることが確認できます。[s2]

フックを入れたあと（イメージ）

フックを入れてから同じことを頼むと、AIが.envを書き換えようとした瞬間にフックが止めます。止めた理由はAIに届くため、AIはやり方を変え、人が変えるための手順を教えてくれます。[s2]しかも、この止めるフックは、確認なしですべて任せる設定でも効きます。[s2]

実例② 直したら自動で整形する（PostToolUse）

整形のコマンド

jq -r '.tool_input.file_path' | xargs npx prettier --write

2つ目は「やり忘れ」の対策で、ファイルを直したら必ず整形します。設定は先ほどとほぼ同じで、タイミングが「PostToolUse」に変わるだけです。動かすのは1行のコマンドで、jqという道具で届いたJSONから直したファイルの名前を取り出し、Prettierという整形の道具にそのまま渡します。[s2]

フックが整形した後

const price = { zunda: 300, kusa: 250, goma: 280 };
function total(items) { return items.reduce((s, i) => s + price[i], 0);
}

これで、AIが書いた詰まったコードも、直すたびに自動で読みやすい形に整います。AIが整形を忘れても、フックが毎回必ず動くので、「やり忘れ」は起きません。

時間のかかる処理は裏で動かす

"hooks": [{ "type": "command", "command": "bash .claude/hooks/run-tests.sh", "async": true
}]

テストのように時間がかかるものは、「async」を付けると裏で動かせます。AIは待たずに作業を続け、結果は次のやりとりでAIに届きます。ただし、裏で動くフックは作業を止めることはできません。[s1]

実例③ 待っていたら通知する（Notification）

通知のフック

{ "hooks": { "Notification": [{ "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"AIが待っています\"'" }] }] }
}

3つ目は「気づかない」の対策です。「Notification」は、AIが入力や許可を待つときに動きます。[s2]これはホームの設定ファイルに書くと、すべてのプロジェクトで効きます。[s1]例ではMacの通知を出すコマンドを動かしており、WindowsやLinuxの通知のコマンドも公式の説明に載っています。[s2]

実例④ 終わる前にテストする（Stop）

止めすぎは8回まで

4つ目は「Stop」で、AIが返事を終えようとするときに動きます。ここで「まだ終わらないで」と返すと、AIは作業を続けます。[s1]ただし、いつでも止めるようにすると、AIは終わろうとするたびに戻されることになります。Claude Codeは、8回続けて止められたら、次は終わらせる仕組みになっています。[s1]

テストが失敗したときだけ止める

import json, subprocess, sys data = json.load(sys.stdin)
if data["stop_hook_active"]: # 一度 続けさせた後なら sys.exit(0) # 今回は終わってよい test = subprocess.run(["npm", "test"], capture_output=True)
if test.returncode != 0: # テストが通らないときだけ reason = "テストが失敗しています。直してください" print(json.dumps({"decision": "block", "reason": reason}))

正しい使い方は、テストが通らないときだけ止めることです。まず、すでに一度続けさせた後（stop_hook_activeが真のとき）なら、そこで終わってもらいます。そのうえでテストを動かし、失敗したときだけ、理由を付けて「まだ終わらないで」と返します。[s1][s2]

テストが通ればそのまま終わり、失敗したら1回直してから終わります。AIを休ませないための仕組みではなく、仕上げを確かめるための仕組みです。

Codexのフックとの違い

どちらでも動くスクリプトの例

import json, sys data = json.load(sys.stdin)
cmd = data["tool_input"].get("command", "") if "rm -rf" in cmd: print(json.dumps({"hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "rm -rf は禁止です"}}))

Codexにも、ほとんど同じ形のフックがあります。書く場所は「hooks.json」か「config.toml」で、3段の形は同じです。[s3]この例は、フォルダを中身ごと消すコマンド「rm -rf」を止めるスクリプトで、見つけたらJSONで「deny」と返して止めます。この返し方は両方で同じなので、このスクリプトはどちらでも使えます。[s1][s3]

Claude CodeとCodexのフック

違いもあります。書く場所とタイミングの数が異なり（33種類と12種類）、動かせるものも、Claude Codeが5種類、Codexはコマンドとmcp_toolの2種類です。[s1][s3]Codexは、管理者のもの以外のフックを1つずつ確認して信頼するまで動かさず、中身が書き換わったフックも、確かめ直すまで動きません。[s3]止め方と、裏で動かす仕組みは、どちらにもあります。[s1][s3]

ファイル編集のJSONは違う

{ "tool_name": "apply_patch", "tool_input": { "command": "*** Update File: .env ..." }
}

ただし、Codexのファイル編集は「apply_patch」という道具で行われ、JSONの形が違います。[s3].envを守るスクリプトは、Codex用に書き直す必要があります。

CLAUDE.md・権限の設定・Gitのフックとの使い分け

AIにルールを守らせる3つの方法

CLAUDE.mdに書くことが悪いわけではなく、使い分けが大切です。変わらない決まりや好みはCLAUDE.mdがいちばんで、公式もそう勧めています。[s1]「このファイルは書かせない」のような単純な禁止なら、権限の設定が確実です。[s1][s4]フックは、中身を見て判断したいときや、毎回何かを動かしたいときに使います。条件を細かく決められ、止めた理由もAIに伝えられます。[s1][s2]

Gitのフックとの違い

Gitにも昔から「フック」があり、コミットなどGitの操作のときに動きます。[s5]AIのフックは、AIが道具を使うたびや返事を終えるときなど、もっと細かいタイミングで見張れる点が違います。[s1]

フックの注意点

フックの4つの注意点

注意点は4つあります。1つ目は、フックがあなたと同じ権限で動くことで、ファイルを消すこともできます。ネットで見つけたフックは、中身を読み、試してから入れましょう。[s1]2つ目は、フックがリポジトリの設定ファイルにも書けることです。Claude Codeは、対話で使う場合はフォルダを信頼するまで設定ファイルのフックを動かさず、Codexはフックを1つずつ確認してから動かします。[s1][s3]

ただし、Claude Codeを自動で動かすとき（claude -pなど）は確認が出ず、リポジトリのフックもそのまま動きます。他人のリポジトリでは、先に中身を見てください。[s1]

フックは完全な壁ではない

> @.env を読んで、設定をまとめて

3つ目は、フックが完全な壁ではないことです。たとえば「@」でファイルを指定して読ませると、AIは道具を使わずに読み込むため、道具を使う前のフックは動きません。[s1]Codexの説明にも「完全な防御の境界ではない」とあります。[s3]大事な禁止は、権限の設定と組み合わせましょう。[s1][s4]4つ目は、フックは毎回動くため、重い処理を入れると作業全体が遅くなることです。[s1]

今日から使う3つのステップ

始めるなら、まずは通知のフックから試すのがおすすめです。止めたり書き換えたりしないため、いちばん安全です。次に、整形やテストを自動にし、最後に止めるフックを入れます。止めるフックは、見本のJSONを流して2で止まるかを確かめてから使いましょう。[s2]

> /hooks
# 登録したフックの一覧（どの設定ファイルか）
$ claude --debug
# ~/.claude/debug/ にフックのログ

登録したフックの一覧は「/hooks」で見られ、動かないときは「claude --debug」でログを確かめられます。[s2]

まとめ

フックは、AIの作業の決まったタイミングで必ず動くプログラムで、ルールの文書という「お願い」を「必ず」に変えられます。[s1][s2]止めたいときはexit 2で終えること、1では止まらないことを覚えておきましょう。[s1]

秘密の情報は、権限の設定とフックで、読ませない・書かせないようにします。[s8]Codexにもほとんど同じ仕組みがありますが、フックはあなたの権限で動くため、他人のフックは中身を確かめてから使うことが大切です。[s1][s3]