Claude Codeのhooksの使い方｜設定の書き方と、社内で毎日動かしている3本

Claude Codeに作業を任せていると、「毎回これだけは確認してほしい」「このファイルだけは触らないでほしい」という場面が出てきます。CLAUDE.mdに書いておいても、長い作業の途中で抜けることがあります。hooksは、そうした確認をClaudeの判断に任せず、決まった場面で必ず動かすための仕組みです。

Claude Codeで社内業務を回している全体像はClaude Codeの活用事例、業務で使うときに決めておくルールはClaude Codeで業務ツールを作るときの注意点に書いています。この記事はhooksの設定に絞ります。

Claude Codeのhooksは、決まった場面で必ず動くコマンドです

hooksは、Claude Codeの動きの中の決まった場面で自動的に実行される、利用者が決めたコマンドです。公式ドキュメントは、LLMが実行するかどうかを選ぶのではなく、特定の処理が必ず起きるようにする仕組みだと説明しています。出典：Claude Code Docs「フックでワークフローを自動化する」

CLAUDE.mdやスキルに書いた手順は、Claudeが読んで、状況に合わせて従います。便利な反面、作業が長くなると読み落としたり、別の判断を優先したりすることがあります。hooksはClaude Code本体が実行するので、Claudeが忘れても動きます。判断が要る方針はCLAUDE.mdに、例外なく毎回やる確認はhooksに、と分けると整理しやすくなります。

最初に覚えるイベントは4つで足ります

hooksは「どの場面で動かすか」をイベントで指定します。2026年9月時点の公式リファレンスには30を超えるイベントが載っていますが、業務で最初に使うのは下の表の範囲で足ります。

見落としやすいのは、止められるかどうかの列です。PostToolUseは、ファイルの編集やコマンドがもう実行された後に動くので、取り消しはできません。止めたい操作があるなら、実行前に動くPreToolUseに書きます。出典：Claude Code Docs「Hooks リファレンス」

設定の書き方：置き場所、matcher、終了コード

置き場所で効く範囲が決まります

hooksは設定ファイルのhooksの欄に書きます。どのファイルに書くかで、効く範囲と共有のされ方が変わります。

このほか、組織の管理者が配る設定や、プラグイン、スキルの中にも書けます。書いた後はClaude Codeで /hooks と入力すると、登録されたフックと、どのファイルから来たものかを一覧で確認できます。

例：.envを編集させないフック

公式ガイドの例を短くしたものです。ファイルの編集や作成の直前に動き、対象が .env か .git/ の中なら止めます。まず、プロジェクトの .claude/settings.json に次のように書きます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

matcher は、どのツールのときに動かすかの指定です。ここでは編集（Edit）と作成（Write）に絞っています。大文字と小文字は区別されます。次に、呼び出すスクリプトを .claude/hooks/protect-files.sh に置き、chmod +x で実行できるようにします。

#!/bin/bash
# protect-files.sh：.env と .git/ への書き込みを止める
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

for pattern in ".env" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "保護対象のため編集できません: $FILE_PATH" >&2
    exit 2
  fi
done
exit 0

フックには、何をしようとしているかがJSONで渡されます。スクリプトはそこから対象のファイルを取り出し、止めるときは終了コード2で終わります。標準エラーに書いた理由はClaudeに伝わり、Claudeは別の方法を考えます。

入れる前に、手でJSONを流して確かめます

Claude Codeで試す前に、ターミナルで同じ形のJSONを流すと、止まるかどうかを数秒で確かめられます。

echo '{"tool_name":"Edit","tool_input":{"file_path":"/tmp/app/.env"}}' \
  | ./.claude/hooks/protect-files.sh
echo $?   # 2 なら止まる、0 なら通る

止めたいパスで2、止めたくないパスで0が返ることを両方確かめてから、Claude Codeで実際に編集を頼んでみます。

SalesDockで毎日動いている3本のhooks

2026年9月24日時点で、社内で常に動かしているhooksは次の3本です。

作業前の同期チェック：古い手順書のまま始めない

SalesDockの手順書やスキルは、GitHub上の1か所を正として、各パソコンはその写しを持っています。写しを更新し忘れると、古い手順書のまま作業が始まります。2026年9月16日には、手元の手順書が本家より157件ぶん古い状態で作業を始め、すでに移行済みの改修をもう一度設計しかけました。

いまはセッションを始めるたびに、本家との差を数えて「何件遅れているか」「どの手順書が古いか」を表示しています。警告を出すだけで、自動で更新はしません。作業中の変更を勝手に動かさないためです。SessionStartのフックが標準出力に書いた内容はClaudeにも渡るので、Claude自身も古い版を読んでいることに気づけます。

認証の健康診断：作業の途中で止まらないように

ブログの改善では、検索順位とアクセス解析の数字を毎日読みます。認証が切れていると、作業の途中で止まり、原因の切り分けから始めることになります。そこで、セッションの開始時に両方の認証を確かめ、「ともに正常」か、切れているものを1行で表示しています。これは全プロジェクトに効かせたいので、プロジェクトではなく自分の ~/.claude/settings.json に書いています。

編集後の劣化チェック：直す指示をClaudeに返す

社内で開発している業務アプリのコードは、AIに編集を重ねさせると、1つのファイルが長くなったり、型の指定を省いたりしがちです。そこで、そのアプリのファイルを編集した直後（PostToolUse）に、500行を超えていないか、型の省略が3か所を超えていないか、デバッグ用の出力が残っていないかなどを数えます。

見つかったときは、JSONの additionalContext という欄で「次の応答で直してください」とClaudeに返します。PostToolUseでは編集を取り消せないので、止めるのではなく、次の一手で直させる形にしています。関係ないフォルダのファイルなら何もせずに終わるよう、最初に対象のパスを確かめています。

hooksで踏みやすい罠

timeoutの単位は秒です

この記事を書くために自社の設定を見直したところ、プロジェクト側の2本に "timeout": 15000 と 10000 が書かれていました。ミリ秒のつもりで書いた値ですが、hooksのtimeoutの単位は秒です。フックが固まったら、その間ずっと待つ設定になっていました。待ってよい秒数を、秒で書きます。

• 15000 と書いた場合：15000秒、約4時間10分待ちます。
• 何も書かない場合：コマンド型のフックは600秒（10分）で打ち切られます。
• セッション開始時の確認のように数秒で終わるもの：15 程度で十分です。

終了コード1では止まりません

一般的なシェルスクリプトでは、失敗を1で返すことが多いはずです。hooksでは、終了コード1は「フックのエラー」として扱われ、操作はそのまま進みます。止めたいときは2を使います。

JSONを返すなら、標準出力に余計な文字を出しません

JSONで結果を返すときは、標準出力がJSONだけになっている必要があります。シェルの設定ファイルが起動時に文字を出す環境では、JSONの読み取りに失敗します。値に引用符が含まれると壊れやすいので、文字列をつなげるより jq などでJSONを組み立てるほうが安全です。

hooksはRPAの代わりにはなりません

hooksを業務の自動化の仕組みとしてRPAと並べて考えることもできますが、hooksが反応するのは、ファイル編集やコマンド実行など、Claude Codeの中で起きた出来事だけです。業務システムの画面を順番に操作する自動化とは役割が違います。どちらに投資するかの判断はAIエージェントとRPAの違いで整理しています。

1本目は、効いたかどうかが見えるものから入れます

hooksは一度入れると意識しなくなるので、効いているのか、邪魔をしているのかが分かりにくくなります。最初の1本は、動いたことがすぐ目に見えるものを選びます。

1. 入力待ちのたびにデスクトップ通知を出すNotificationのフックを、自分の ~/.claude/settings.json に入れます。公式ガイドの最初の例がこれです。
2. 次に、プロジェクトで絶対に触らせたくないファイルを1〜3個決め、上の例のようにPreToolUseで守ります。入れる前に、手でJSONを流して2と0が返ることを確かめます。
3. 4週間、フックが止めた回数と、止めたけれど実は通してよかった回数を記録します。スクリプトの中で、止めたときに日時とファイル名を1行ずつログへ書き足しておけば、数えるのは1分で済みます。
4. 通してよかった回数が止めた回数の半分を超えるなら、条件が広すぎます。対象のパスを絞るか、止めずに警告だけ返す形に変えます。

止める操作を決めるときは、どこまでをAIに任せ、どこで人が確認するかも同時に決めることになります。その線の引き方は人の承認を挟むAIワークフローの記事に書いています。社内の手順を増やしていった順番は自社で50のAIスキルを作った話にまとめました。