Claude Code Hooksの設定方法 — 初めて書く人の完全手順

要点

Hooksは .claude/settings.json に10行ほど書くだけで設定できます。最初の難所は "どのイベントに紐付けるか" の把握。ここでは PostToolUse でWrite後に自動でフォーマッタを走らせる実用例を、最小構成から順に手を動かして作ります。

このチュートリアルで得られること

• .claude/settings.json にHookを書く最小構成がわかる
• PostToolUse イベントの使い方がわかる
• WriteしたファイルにPrettierを自動適用する実動作まで到達する

前提条件

• Claude Codeがインストール済み(claude --version が通る)
• Node.jsプロジェクトでPrettierが導入済み(npx prettier --version が通る)
• macOS / Linux / WSL(Windows PowerShellのパスは最後に補足)

手順1: 設定ファイルを作る

プロジェクトルートに .claude/ ディレクトリと settings.json を作ります:

mkdir -p .claude
touch .claude/settings.json

確認:

ls -la .claude/
# -> settings.json が存在する

手順2: 最小のHookを書く

.claude/settings.json に以下を書きます。まずはただログを出すだけのhookで、設定が効いていることを確認します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[hook] Write が実行されました\" >> /tmp/claude-hooks.log"
          }
        ]
      }
    ]
  }
}

ポイント:

• PostToolUse は「ツール実行後」に走るイベント
• matcher: "Write" でWriteツールだけに限定(* にすると全ツール)
• command はただのシェルコマンド。標準出力・標準エラーは通常は捨てられるので、ファイルに書き出す

手順3: Claude Codeを再起動して確認

settings.jsonの変更は起動中のセッションには反映されないので、一度Claude Codeを終了して再起動します。

# セッション終了後
claude

新しいセッションで、簡単なWriteを含むタスクを頼みます:

README.md に "Hello Hooks" と書いて保存してください

別のターミナルで確認:

cat /tmp/claude-hooks.log
# -> [hook] Write が実行されました

ログが書かれていれば成功です。

手順4: Prettierを走らせる実用版に拡張

ログだけのhookを、Prettierを走らせる実用hookに置き換えます:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path // empty' <<< \"$CLAUDE_HOOK_INPUT\") && [ -n \"$FILE\" ] && npx prettier --write \"$FILE\" 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

解説:

• matcher: "Write|Edit" でWriteとEdit両方を対象に(正規表現)
• $CLAUDE_HOOK_INPUT にhookのコンテキストJSONが渡ってくる(Claude Codeから提供される環境変数)
• jq でツール入力からfile_pathを抜き出す
• Prettierが走るのは拡張子が対応するファイルだけ(非対応なら静かに失敗、|| true でhook全体は成功扱い)

手順5: 動作確認

Claude Codeを再起動し、以下を頼みます:

src/utils.ts を作って、foo 関数を書いてください

作成されたファイルを確認:

cat src/utils.ts

Prettierのフォーマット(セミコロン・クォート規約・インデント等)が適用された状態になっていれば成功です。

うまくいかないとき

症状1: hookが発火しない

• 原因: settings.jsonの変更が反映されていない
• 対処: Claude Codeを一度終了して再起動

症状2: jq: command not found

• 原因: jq が未インストール
• 対処: brew install jq(macOS) / apt install jq(Debian系)。もしくは node スクリプトに置き換える

症状3: Prettierが走らない

• 原因: npx prettier のパスが通っていない、package.json にprettierが無い
• 対処: npm install --save-dev prettier でインストール。既にあるなら cd でプロジェクトルートに居るかを確認

症状4: Windows PowerShellで動かない

• 原因: 上記例はPOSIXシェル前提
• 対処: command部分をPowerShell構文に書き換え、CLAUDE_CODE_USE_POWERSHELL_TOOL=1 を設定

症状5: hookが遅すぎてClaudeの応答が詰まる

• 原因: Prettierが重い / 大量ファイルに一斉適用
• 対処: hookを .ts/.tsx/.js に限定するglobマッチを追加するか、hook自体をasync化する(内部でバックグラウンド & する)

まとめ

Hookは最小10行のJSONで設定できますが、起動中セッションには反映されないのが最初の躓きポイントです。最小ログ版で設定の存在を確認してから実用版に拡張するのが、最も短時間で動作に到達する手順でした。

次のステップは、PreToolUse で危険コマンドを事前ブロックするhook、Stop でセッション終了時にコミット支援を走らせるhookなど。Hooksは「実行時の自動化レイヤ」ですが、プロジェクトの暗黙ルールはCLAUDE.md側、繰り返し呼び出したい知識はSkills側 に置くと役割分担が綺麗に整います。