Hooks（フック）

Hooks は、Claude Code の動作の決まったタイミングで自動的に実行される処理です。ツール実行前にチェックを入れたり、実行後にログを取ったり、危険な操作を自動でブロックしたりできます。

Hooks とは

身近な例えで理解する

なぜ Hooks が必要なのか

1. 危険な操作を自動でブロックできる

CLAUDE.md に「rm -rf を実行しないで」と書いても、AI は指示を100%守るとは限りません。Hooks なら、rm -rf コマンドが実行される前にシェルスクリプトがチェックし、確実にブロックできます。ルールに頼るのではなく、仕組みで防ぐのが Hooks です。

2. 品質チェックを自動化できる

ファイルを編集した後に自動でフォーマッターを実行したり、コミット前にリントを走らせたりできます。「フォーマットし忘れた」「リント通してなかった」というミスがゼロになります。

3. 監査ログを残せる

誰が（どのセッションで）、いつ、何のツールを実行したかを自動記録できます。チーム開発でのトレーサビリティに役立ちます。

4. 環境の自動セットアップ

セッション開始時に環境変数を設定したり、必要なサービスを起動したりできます。毎回手動で環境を整える手間がなくなります。

CLAUDE.md のルールとの違い

フックタイプ

Hooks には4つのタイプがあり、それぞれ異なる方法で処理を実行します。

主要なフックイベント

よく使うイベント

チーム開発向けイベント

設定方法

設定場所

Hooks は以下のいずれかの設定ファイルに定義します。

基本的な設定構造

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "ツール名の正規表現",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/スクリプト名.sh"
          }
        ]
      }
    ]
  }
}

マッチャー（matcher）

特定のツールにだけフックを適用したい場合に正規表現で指定します。省略すると全ツールに適用されます。

終了コードの意味

フックスクリプトの終了コードで動作を制御します。

実践例

例1: 保護ファイルへの編集をブロック

.env や package-lock.json など、AI が編集すべきでないファイルへのアクセスを自動でブロックします。

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

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

PROTECTED_PATTERNS=(".env" ".git/" "package-lock.json" "yarn.lock")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "保護対象ファイルへの変更はブロックされました: $FILE_PATH" >&2
    exit 2
  fi
done

exit 0

例2: ファイル編集後の自動フォーマット

ファイルが編集された後に、自動的に Prettier などのフォーマッターを実行して整形します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/auto-format.sh"
          }
        ]
      }
    ]
  }
}

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

if [[ -z "$FILE_PATH" ]]; then
  exit 0
fi

# ファイル拡張子に応じてフォーマッターを実行
case "$FILE_PATH" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
    npx prettier --write "$FILE_PATH" 2>/dev/null
    ;;
  *.py)
    black "$FILE_PATH" 2>/dev/null
    ;;
esac

exit 0

例3: セッション開始時の環境セットアップ

セッション開始時に必要な環境変数を設定したり、前提条件をチェックしたりします。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./.claude/hooks/setup-env.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# 必要なツールの存在チェック
for cmd in jq node npm git; do
  if ! command -v "$cmd" &>/dev/null; then
    echo "警告: $cmd がインストールされていません" >&2
  fi
done

# Node.js の依存関係チェック
if [[ -f "package.json" ]] && [[ ! -d "node_modules" ]]; then
  echo "node_modules が見つかりません。npm install を実行してください。" >&2
fi

exit 0

例4: 危険なコマンドの実行をブロック

Bash ツールで rm -rf や sudo など危険なコマンドが実行されそうなときにブロックします。

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

DANGEROUS_PATTERNS=(
  "rm -rf /"
  "rm -rf ~"
  "sudo rm"
  "mkfs"
  "dd if="
  ":(){:|:&};:"
  "chmod -R 777 /"
)

for pattern in "${DANGEROUS_PATTERNS[@]}"; do
  if [[ "$COMMAND" == *"$pattern"* ]]; then
    echo "危険なコマンドがブロックされました: $COMMAND" >&2
    exit 2
  fi
done

exit 0

ユースケース

フックスクリプト作成のコツ

確認方法

# セッション内でフック一覧を確認
/hooks

# Verbose モード（Ctrl+O）でフック実行を確認