CLAUDE.mdに書いたルールが、また飛ばされた。
そんなときに使うのがhooksです。
🎥 この記事の内容は動画でも解説しています。
先に結論です。
- hooksは、Claude Codeの決まったタイミングで、自分のスクリプトを自動で動かす機能
- 設定は
settings.jsonに書く。コマンドの実行前に止めるならPreToolUseを使う PreToolUseのスクリプトが終了コード2で終わると、そのツールは実行されない(終了コード1では止まらない)- 自分の公開チェック用hookは確認済みの印の有無を見るだけ。チェックの中身の良し悪しまでは見ていない
自分は、記事と動画の公開コマンドを、確認済みの印がなければ止めるのに使っています。
hooksを入れたきっかけ
このブログの記事は、Claude Codeと一緒に作っています。
公開前に、文章のチェックを何段階か通す決まりです。
あるとき、そのチェックが抜けていたことが分かりました。
照合するはずのガイドのファイルパスが間違っていて、Claude Codeはそれに気づかないまま、記憶をもとにした簡単な検索で代用していたんです。
動画の台本のチェックも、実行されていませんでした。
ルールは書いてあったんです。
でも、飛ばされました!
「絶対に遵守できるルール設定方法はないの?」とClaude Codeに聞いたら、hooksを教えてくれました。
文章のルールはAIの判断を通るけど、hooksはClaude Codeの仕組みの側で動きます。
AIの判断とは別に、決めたタイミングでスクリプトが動く。
ここが違います!
hooksの設定方法
設定ファイルの場所
書く場所は3つあります。
| ファイル | 効く範囲 |
|---|---|
~/.claude/settings.json |
自分の全プロジェクト |
.claude/settings.json |
そのプロジェクト(コミットして共有できる) |
.claude/settings.local.json |
そのプロジェクトの自分だけ |
複数の場所に書いたhooksは、上書きではなく全部合わせて効きます。
自分の公開チェックはこのブログ専用なので、.claude/settings.local.jsonに入れています。
settings.jsonの書き方
Bashコマンドの実行前にスクリプトを動かす設定は、こんな感じです!
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "bash .claude/hooks/block-push.sh"
}
]
}
]
}
}
PreToolUse: ツールを使う前のタイミング。使った後ならPostToolUsematcher: どのツールのときに動かすか。Edit|Writeのように複数も書けるcommand: 動かすコマンド
止めるスクリプトの最小例
git pushを止める例です。
次の内容を.claude/hooks/block-push.shに保存します。
#!/bin/bash
COMMAND="$(jq -r '.tool_input.command // empty')"
if printf '%s' "$COMMAND" | grep -q 'git push'; then
echo "git pushは止めています。本人に確認してください。" >&2
exit 2
fi
exit 0
大事なのは3つです。
- 実行しようとしているコマンドは、標準入力にJSONで渡ってくる。例では
jqで取り出している(jqがないとコマンドを取り出せず、この例では止められない) exit 2で止まる。エラーの文章はClaudeに渡るので、次に何をすればいいかを書いておくexit 1では止まらない。処理は続行される
最後のは間違えやすいんです。
普通のスクリプトの感覚でexit 1と書くと、止めたつもりで素通りします・・・。
動くか確かめる
スクリプト単体なら、JSONを渡して試せます。
echo '{"tool_input":{"command":"git push origin main"}}' | bash .claude/hooks/block-push.sh; echo "終了コード: $?"
終了コード2が出て、git statusに変えると0になれば、スクリプト単体の動作は確認できます。
Claude Codeから動くかは、実際に使って確かめます。
設定した一覧は、/hooksで見られます。
読み取り専用なので、変更は設定ファイルのほうでします。
hooksは自分のマシンでコマンドをそのまま動かします。
人からもらった設定は、中身を読んでから入れてください。
実例1: チェックが終わるまで公開を止める
記事を作るコマンド(wp post create)と、動画をアップするスクリプトが対象です。
「チェックが終わった」という印のファイルがないと実行できません。
- 印がなければ止める。エラーには、どのチェックをするかも書いてある
- 15分たった印は無効
- 1回使うと消える。ローカルと本番に入れるなら、印も2回必要
入れたときに11パターンの入力で試して、実際のセッションでも、止まる→印を作る→通る→印が消える→また止まる、を確かめました。
止め方は、さっきのexit 2ではなく、JSONを返す形です。
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "QA済みの印がありません"
}
}
これを出力してexit 0で終わると、止めて理由を伝えられます。
最初に試すなら、exit 2のほうが簡単です。
実例2: 測っていない画像の反映を止める
アイキャッチの余白や文字サイズを測るスクリプトをClaude Codeに作ってもらったんですが、最初は一部の案にしか使っていなかったので、全部の案で測ることにしました。
ただ、手順に書くだけだとまた抜けそうです。
なので、測ったファイルの名前を印に残して、記事に画像を設定するコマンドに同じ名前がなければ止める形にしました。
こっちの印は60分有効です。
ローカルと本番で同じ画像を使うからです。
止めないhooksもある
hooksは止めるだけじゃないです!
自分はPostToolUseで、ファイルを編集したあとにCodex用のルールファイルを作り直しています。
Claude Code用のルールとのズレを防ぐためです。
やらかしたこと
自分のhooksはBashコマンドの文字列で判断するので、関係ないときにも反応します。
何回かやらかしました・・・。
- スクリプトを書くコマンドの中に「post create」があって止まった。同じコマンドの中で印を作る処理まで止まるので、スクリプトを書く工程と、印を作る工程と、実行を分けた
- アップ用スクリプトの中身を調べたかっただけなのに、名前が入っていて止まった
- アイキャッチ用のhookが説明文の文字列に反応して、作業記録の更新が止まった
判定をゆるくすると、今度は本当に止めたいものが通るかもしれません。
今のところ、判定はこのままにしています。
hooksで止められないもの
ここ、入れる前に知っておいてほしいです!
- 印を作るのはAI自身。自分のhookが見ているのは、印があるかどうかだけ。チェックの中身までは確かめていない
- Claude Codeの機能なので、Codexやブラウザから上げるものは止まらない
- スクリプトがタイムアウトした場合、
PreToolUseでも基本は止まらない(onFailure: blockを指定した場合を除く。公式ドキュメントより)
つまり、このhookが止めているのは「確認済みの印がないまま公開コマンドを実行すること」までです。
チェックの中身は、手順と自分の目で見ています。
何からhooksにするか
全部のルールをhooksにする必要はないと思います。多分。
自分が見ているのはこの3つです。
- 同じ注意を2回以上した
- 破られると、公開や削除みたいに外に出たり戻せなかったりする
- ファイルがあるか、コマンドに特定の文字があるか、のように機械で判定できる
3つそろっているものがあれば、さっきのgit pushの例を書き換えて、試してみてください!
hooksのまわりの考え方は、ハーネスの記事に、ルールの置き場所の話はルールを手順に入れた記事に書いています。