Claude Code と Hooks とは（短く）
Claude Code は Anthropic が出しているターミナル用の AI 開発エージェント。claude コマンドでローカルのリポジトリと対話し、ファイルを編集したりコマンドを走らせたりするツールです。
TUI （Terminal User Interface — ターミナル内で動く GUI 風の画面）で、入力欄やセッション履歴がターミナル画面に表示されます。
Hooks は、Claude Code の ライフサイクルイベント （例: ファイル編集後 = PostToolUse、ツール実行前 = PreToolUse、入力待ち = Notification、セッション開始時 = SessionStart など）に 毎回必ず走るシェルコマンド/スクリプトを、設定ファイルに登録できる仕組みです。
ポイントは 「LLM の判断を経由しない」こと。Claude が「フォーマットした方がいいかな」と思うかどうかに依存せず、ルールとして毎回必ず動くので、チーム運用や安全確認に向いています。
設定ファイルはどこに書くか
Hooks の設定は次のどちらかに書きます。
・ユーザー全体: ~/.claude/settings.json → そのマシンで起動する すべての Claude Code セッションに効く。
・プロジェクト単位: プロジェクトのルートに .claude/settings.json → そのプロジェクトでだけ効く。プロジェクト固有のフォーマッタや保護ルールを書きたい場合はこちら。
ファイルが無ければ新規作成します。Claude Code 上で /hooks を入力すれば、現在登録されている Hooks の一覧を TUI から確認できます。
基本構造
すべての Hooks は次の形を踏襲します。
{
"hooks": {
"イベント名": [
{
"matcher": "条件",
"hooks": [
{
"type": "command",
"command": "実行したいシェルコマンド"
}
]
}
]
}
}
・イベント名は PostToolUse（ツール実行後）や PreToolUse （ツール実行前）、Notification（入力待ち通知）など。
・matcher はイベントのサブタイプ。例えば PostToolUse で "Edit|Write" と書くと、Edit ツールか Write ツールが走った後だけにフックが効く。空文字列なら全マッチ。
・type は command（シェルコマンドを直接書く）か script （スクリプトファイルのパスを指定）。
実行時、Hooks には Claude Code から JSON が標準入力で渡されます （どのファイルを触ったか、何のツールが動いたかなど）。jq などでパースして使うのが定番です。
ユースケース 1: 編集後に自動で Prettier をかける
「Claude が .tsx を編集したら、毎回必ず Prettier を走らせて整形する」例。PostToolUse で Edit|Write をマッチさせます。
.claude/settings.json に追加:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
挙動: Claude が Edit / Write でファイルを書いた直後、そのファイルパスを Prettier に渡して自動整形します。ESLint の --fix や black（Python）に置き換えても同じ要領で書けます。
これまで「Edit のたびに手で npx prettier --write を打つ」「Claude に『書いた後 Prettier かけてね』と毎回お願いする」運用だった部分を、 設定ファイル 1 行で固定できます。
補足: jq はコマンドラインで JSON をパースする定番ツール。 macOS なら brew install jq で入ります。
ユースケース 2: 入力待ちのときにデスクトップ通知
長いジョブを Claude Code に任せて他の作業をしていると、AI が途中で入力待ちになっていることに気づかず数十分放置、ということが起こります。Notification イベントを使えば、入力待ちになった瞬間に OS のデスクトップ通知を出せます。
macOS の例:
{
"hooks": {
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
}
]
}
]
}
}
Linux の場合は notify-send 'Claude Code' 'needs your attention'、 Windows なら PowerShell で MessageBox を出す形に置き換える。
これだけで、「気づいたら AI が 30 分止まっていた」事故をかなり減らせます。長時間ジョブを並列で回す運用に効く。
ユースケース 3: .env / package-lock.json / .git/ の編集をブロック
Claude が 触ってほしくないファイルを勝手に書き換えないように、 PreToolUse で 書き込み前に拒否する例。
まず .claude/hooks/protect-files.sh を作って実行権限を付ける:
#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")
for pattern in "${PROTECTED_PATTERNS[@]}"; do
if [[ "$FILE_PATH" == *"$pattern"* ]]; then
echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
exit 2
fi
done
exit 0
chmod +x .claude/hooks/protect-files.sh
.claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": ".claude/hooks/protect-files.sh"
}
]
}
]
}
}
ポイントは exit 2 を返すと Claude Code 側で「ブロック」として扱われ、AI に理由がフィードバックされること。exit 0 なら通過、 exit 1 は警告扱いです。
「.env を Claude が読んでしまうかも / 上書きするかも」を毎回プロンプトでお願いする運用は、ルールとして書けば毎回守られる ので、チームに導入するときの心理的ハードルがかなり下がります。
誰にどう効くか
・AI に同じ手作業を毎回お願いしているチーム: 「Edit したらフォーマットして」を 設定ファイルに 1 回書いて二度と書かない 運用に変えられる。プロンプトの定型文が短くなる。
・.env / 機密ファイルの取り扱いが心配なチーム: PreToolUse + exit 2 で AI の判断と無関係に必ずブロックできる。 Claude が「気を利かせて読んでしまう」事故を構造的に防げる。
・長時間ジョブを並列で回す人: Notification Hook で 入力待ちに気づける。AI が 30 分止まっていた事故を削れる。
・チームで Claude Code を使い始めたばかりの組織: 個人ごとにプロンプトの作法が違う問題を、プロジェクト単位の .claude/settings.json に集約できる。新しく加わったメンバーも、リポジトリを clone した瞬間から同じルールが適用される。
触ってみるには / 注意点
・始め方: プロジェクトのルートに .claude/settings.json を作り、上記のうち効きそうなユースケースを 1 つだけ書いてから試す。 Claude Code を起動し、/hooks で登録状況を確認 → 実際に Edit を走らせてフックが発火するか見る、の順が安全。
・注意 1（macOS の通知権限）: osascript の display notification は システム設定 > 通知 > Script Editor をオンにしないと出ない。最初の 1 回は手動でも osascript を叩いてみて、許可ダイアログを通しておくのがおすすめ。
・注意 2（exit code の意味）: exit 0 は通過、exit 1 は警告、 exit 2 は ブロック（AI にもフィードバック）。PreToolUse でブロックを意図するなら exit 2 を使う。逆に通常のフォーマッタでファイルが書けない場合などに exit 2 を返してしまうと、毎回 Claude が止まってしまうので、用途を分けて書く。
・注意 3（スクリプトの信頼境界）: Hooks は ローカルで任意のシェルコマンドを実行する仕組みです。第三者から受け取った .claude/settings.json をそのまま流し込むのは、シェルスクリプトをそのまま実行するのと同じ意味なので、中身を読んでから入れる。
・注意 4（Hook の中身は TUI で見えない場合がある）: /hooks で確認できるのは 「どのイベントに何が登録されているか」の一覧で、各 Hook の コマンド本体（実際に何をするか） は設定ファイル側を読む必要が残る。最終的には JSON ファイルが正です。
・注意 5（決定論的な処理向き）: Hooks は 「常に同じ条件で必ず動く」処理に向く仕組みです。「ファイルの内容を読んで判断して、必要なら修正する」のような 判断が必要な処理は、Hooks ではなくプロンプトや Subagents 側でやるほうが向いています。
関連リンク
・公式ガイド (英語): <https://code.claude.com/docs/en/hooks-guide>
・イベントリファレンス (英語): <https://code.claude.com/docs/en/hooks>
_Status: pending — 人間レビュー待ち。_