中小DXラボ のツール

Claude Code の hooks(フック)とは:設定の書き方と使いどころ

公開: ・ 中小DXラボ ・ 内容は執筆時点(2026年10月)の公式ドキュメントなどの出典にもとづきます(各節の末尾に出典を記載)

結論

  • hooks は、Claude Code(Anthropic 社が提供する、ターミナルで動く AI コーディングエージェント)の動作の決まった場面で、利用者が定義したシェルコマンドを自動実行する仕組みです。LLM が実行を選ぶかどうかに頼らず、決まった処理を必ず走らせられます。
  • 設定は設定ファイルの hooks に、イベント名・matcher・実行するコマンドを書きます。/hooks で登録を確認できます。
  • コード整形や保護ファイルの編集ブロックに向きますが、PostToolUse では取り消せないなどの制約があります。社内に配る前に、公式ドキュメントで該当イベントの仕様を確認してください。

hooks で何ができるか

公式ドキュメントによると、hooks は利用者が定義するシェルコマンドです。Claude Code がライフサイクル上の決まったタイミングで実行するため、特定の処理が必ず起きる、という決定的な制御ができます。プロジェクトのルールの強制、繰り返し作業の自動化、既存ツールとの連携が主な用途です。

公式ドキュメントが挙げる例は、編集後のファイル整形、実行前のコマンドのブロック、入力待ちの通知、セッション開始時のコンテキスト注入などです。

多くの hook は "type": "command" でシェルコマンドを実行します。ほかに http、mcp_tool、prompt(単発の LLM 判断)、agent(ツールを使える複数ターンの検証)があります。agent は実験的で、将来変更される可能性があるため、本番のワークフローでは command hook が推奨されています。

この記事は執筆時点(2026年10月)で参照した公式ドキュメントに基づきます。イベントや設定項目は更新されうるため、導入前に最新の内容を確認してください。

出典: Automate actions with hooks

設定の書き方:最初の hook

hook を作るには、設定ファイルに hooks ブロックを追加します。イベント名は、1つの hooks オブジェクトの中のキーとして並べます。すでに hooks キーがある場合は、全体を置き換えず、既存のイベントキーと同じ階層に追加します。

次は、ファイル編集ツールの実行後に Prettier(コード整形ツール)を走らせる例です。公式ドキュメントでは、プロジェクト直下の .claude/settings.json に追加するとされています。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

PostToolUse はツール呼び出しが成功した後のイベントです。matcher の Edit|Write は、Edit か Write ツールを使ったときだけ動かす指定で、Bash や Read では動きません。matcher を付けないと、そのイベントが起きるたびに動きます。コマンドは jq(JSON を処理するコマンド)で編集されたファイルのパスを取り出し、Prettier に渡しています。

設定したら、プロンプトで /hooks と入力すると hooks の一覧が開き、登録を確認できます。成功した hook は会話上に何も表示しないため、効果(ここではファイルが整形されたか)で確認します。

出典: Automate actions with hooks

設定ファイルの置き場所と適用範囲

公式ドキュメントでは、hook を置く場所で適用範囲が決まります。

  • ~/.claude/settings.json:自分の全プロジェクト。手元のマシン限定で共有されません
  • .claude/settings.json:そのプロジェクトのみ。リポジトリにコミットして共有できます
  • .claude/settings.local.json:そのプロジェクトのみ。共有しません
  • 管理ポリシー設定:組織全体。管理者が制御します
  • プラグインの hooks/hooks.json、スキルやサブエージェントの frontmatter:それぞれプラグインが有効な間、スキル呼び出し後のセッション、サブエージェントの実行中に適用されます

社内で揃えたい hook は、.claude/settings.json に入れてリポジトリで共有する形になります。hooks を止めるには、設定ファイルに "disableAllHooks": true を書きます。ただしプロジェクトの設定ファイルが自分の設定を上書きすることがあり、管理設定の hooks は、管理設定側でも disableAllHooks を設定しない限り動き続けます。

出典: Automate actions with hooks

入力・出力と終了コードの考え方

イベントが起きると、Claude Code はイベント固有のデータを JSON で hook の標準入力に渡します。たとえば PreToolUse の hook は tool_name や tool_input を受け取ります。スクリプトはそれを読み、終了コードで次の動作を伝えます。

  • 終了コード 0:異議なし。PreToolUse では承認にはならず、通常の権限確認が続きます。UserPromptSubmit や SessionStart などでは、標準出力がテキストとして Claude のコンテキストに追加されます
  • 終了コード 2:動作をブロックします。理由は標準エラー出力に書きます。理由の届け先はイベントによって異なり、SessionStart のようにブロックできないイベントもあります
  • それ以外:標準出力の内容で結果が変わり、多くの場合は非ブロッキングエラーとして処理が進みます

次は PreToolUse でコマンドをブロックするスクリプトの例です。

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2                                               # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

より細かく制御したいときは、終了コード 0 で JSON を標準出力に返します。ブロックは終了コード 2、構造化制御は終了コード 0 と JSON のどちらかに決め、1つの hook で混ぜないよう公式ドキュメントは案内しています。また、同じイベントに複数の hook が一致すると並列で実行され、PreToolUse の権限判断では最も厳しい結果が採用されます(deny、defer、ask、allow の順)。ある hook が deny を返しても、ほかの hook の実行は止まりません。

出典: Automate actions with hooks

使いどころと注意点

向いている使いどころ

  • 編集後のコード整形(PostToolUse)
  • .env、package-lock.json、.git/ など保護したいファイルの編集ブロック(PreToolUse とスクリプトの終了コード 2)。スクリプトは実行可能にしておく必要があります
  • 入力待ちの通知(Notification)。macOS、Linux、Windows 向けの例が公式ドキュメントにあります
  • コンテキストの再注入(SessionStart と compact)。会話の要約で失われる情報を補う用途です
  • 設定ファイル変更の監査ログ(ConfigChange)

注意点

  • PostToolUse は、ツールがすでに実行された後なので、処理を取り消せません
  • Edit|Write の matcher だけでは、Claude がシェルコマンドでファイルを変えるケースを拾えません。全変更を監査したい場合は、1ターンごとに作業ツリーを調べる Stop hook が案内されています
  • if フィールドによる絞り込みはベストエフォートです。厳格な許可・拒否には、hook ではなく権限システムを使うよう案内されています
  • PermissionRequest で自動承認する場合は matcher を狭くします。.* を指定したり空にしたりすると、ファイル書き込みやシェルコマンドを含むすべての権限確認が自動承認されます
  • PreToolUse の deny は bypassPermissions モードでも効きます。一方、hook の allow は設定の deny ルールを回避できません

出典: Automate actions with hooks

よくある質問

セッションのたびに同じ前提を Claude に伝えたいだけなら、hooks を使うべきですか。

公式ドキュメントでは、セッション開始のたびにコンテキストを入れたい場合は、SessionStart hook より CLAUDE.md を検討するよう案内しています。SessionStart の compact matcher は、コンパクション後に重要な情報を入れ直す用途の例として紹介されています。

出典: Automate actions with hooks

hook が動かないときは、何から確認すればよいですか。

公式ドキュメントでは、まず /hooks で正しいイベントの下に表示されているかを確認します。matcher はツール名と正確に一致させる必要があり、大文字小文字も区別されます。設定ファイルの JSON は末尾のカンマやコメントが使えません。スクリプトが動かない場合は実行権限を確認します。詳細なログは claude --debug で見られます。

出典: Automate actions with hooks

ルールで決められない、判断が必要な処理にも hooks は使えますか。

公式ドキュメントでは、prompt hook が Claude モデルに1回判断させ、agent hook はファイルの読み取りなどのツールを使って検証します。agent hook は実験的で、将来変更される可能性があり、本番では command hook が推奨されています。

出典: Automate actions with hooks

関連する無料ツール

Claude Code 権限設定(settings.json)ジェネレーター: deny / ask / allow のルールを選ぶと、置き場所つきで settings.json を出力します。配る前の設定の下書きに使えます。

参考(執筆時点)

この記事は、上の出典の内容を中小DXラボが要約・再構成したものです。仕様は変わることがあります。社内で使う・配る前に、公式ドキュメントで最新の情報を確認してください。