Claude Codeのフック機能を使いこなす：自動フォーマット・自動テスト

フック機能とは

Claude Codeのフック機能は、特定のアクションの前後にカスタムコマンドを自動実行する仕組みです。ファイル保存後の自動フォーマットや、コード変更後の自動テスト実行などを設定できます。

フックは .claude/settings.json に記述し、Claude Codeが特定の操作を行うタイミングでシェルコマンドを実行します。設定ファイルの書き方の基本はCLAUDE.mdの書き方完全ガイドでも解説しています。

フックの種類

Claude Codeでは以下のタイミングでフックを設定できます。

フックイベント	発火タイミング
PreToolUse	ツール実行前
PostToolUse	ツール実行後
Notification	通知送信時
Stop	Claude Codeの応答完了時

基本設定

フックは .claude/settings.json の hooks フィールドに定義します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

設定の構造

• matcher: フックを発火させるツール名のパターン（正規表現）
• command: 実行するシェルコマンド

ユースケース1：自動フォーマット

ファイル編集後に自動的にPrettierを実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

これにより、Claude Codeがファイルを作成・編集するたびに、自動的にPrettierでフォーマットされます。チームのコーディングスタイルが常に維持されます。

ユースケース2：自動リント

ESLintの自動修正を組み込む例です。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

|| true を付けることで、リントエラーがあってもフックが失敗扱いにならず、Claude Codeの処理が継続します。

ユースケース3：変更時の自動テスト

ファイル編集後に関連するテストを自動実行し、結果をフィードバックします。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx vitest related \"$CLAUDE_FILE_PATH\" --run 2>&1 | tail -20"
      }
    ]
  }
}

Vitestの related オプションで、変更されたファイルに関連するテストだけを実行します。全テスト実行と比べて高速にフィードバックが得られます。

ユースケース4：型チェックの自動実行

TypeScriptプロジェクトでファイル変更後に型チェックを走らせます。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }
    ]
  }
}

ユースケース5：危険なコマンドのブロック

特定のコマンド実行を防止するPreToolUseフックです。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|drop table|git push.*force'; then echo 'BLOCKED: Dangerous command detected' >&2; exit 1; fi"
      }
    ]
  }
}

exit 1 で終了すると、Claude Codeはそのツール実行をスキップします。

ユースケース6：完了通知

Claude Codeがタスクを完了したときに通知を送ります。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "notify-send 'Claude Code' 'タスクが完了しました' 2>/dev/null; echo 'Done'"
      }
    ]
  }
}

macOSの場合は以下のように書けます。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "command": "osascript -e 'display notification \"タスクが完了しました\" with title \"Claude Code\"'"
      }
    ]
  }
}

複数フックの組み合わせ

実際のプロジェクトでは、複数のフックを組み合わせるのが効果的です。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf /'; then exit 1; fi"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      },
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "command": "echo '✓ Task completed'"
      }
    ]
  }
}

フック作成のコツ

1. 実行時間を短くする

フックは同期的に実行されるため、重い処理はClaude Codeの応答を遅延させます。テスト実行は related オプションで対象を絞る、出力は head や tail でトリミングするなどの工夫をしましょう。

2. エラーハンドリング

フックがエラーで終了するとClaude Codeの動作に影響します。|| true や 2>/dev/null で安全にしておくのがおすすめです。

3. 環境変数の活用

フック内で利用できる環境変数を活用しましょう。$CLAUDE_FILE_PATH で操作対象のファイルパスが取得できます。

まとめ

フック機能を活用すれば、Claude Codeのワークフローを大幅にカスタマイズできます。特に自動フォーマットと自動テストの組み合わせは、コード品質の維持に非常に効果的です。まずはPrettierの自動実行から始めてみましょう。外部ツールとの連携をさらに広げたい方はMCPサーバーの設定と活用法を、日々の開発効率を高めたい方は生産性を3倍にする10のTipsもあわせてご覧ください。

フック機能の詳細はAnthropic公式ドキュメントやClaude Code GitHub リポジトリで確認できます。