Hooks

Hooks は、Claude Code がツールを実行する 前後に自動的に処理を挟む仕組み です。コードのフォーマットや検証を自動化できます。

Hooks とは

Claude Code は、ファイルの読み書きやコマンドの実行など、さまざまな「ツール」を使います。Hooks を使うと、これらのツールが実行される 前 や 後 に、カスタムスクリプトを自動実行できます。

通常のフロー:
  Claude がファイルを編集 → 完了

Hooks を使ったフロー:
  Claude がファイルを編集 → PostToolUse Hook 発動 → 自動フォーマット実行

Hooks の用途

Hooks は主に以下の目的で使います。

• ファイル保存後の自動フォーマット（Prettier、ESLint --fix）
• コマンド実行前の安全チェック
• 特定のイベント発生時の通知

Hooks の種類

Claude Code には 3 種類の Hook があります。

Hook 名	タイミング	主な用途
PreToolUse	ツール実行 前	実行を許可/拒否する判断
PostToolUse	ツール実行 後	フォーマットや検証の実行
Notification	Claude が通知を送信する時	カスタム通知の送信

PreToolUse Hook

ツールが実行される 前 に呼び出されます。スクリプトの終了コードによって動作が変わります。

終了コード 0: ツール実行を許可（自動承認）
終了コード 2: ツール実行をブロック（拒否してフィードバック）
その他: 通常のフロー（ユーザーに確認を求める）

PostToolUse Hook

ツールが実行された 後 に呼び出されます。主にフォーマットや検証に使います。

Notification Hook

Claude が長時間の処理を完了した時や、ユーザーの入力を待っている時に呼び出されます。

Hooks の設定方法

Hooks は .claude/settings.json または ~/.claude/settings.json に設定します。

基本的な設定構造

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

matcher の書き方

matcher には正規表現を使ってツール名を指定します。

• "Write" - Write ツールのみ
• "Write|Edit" - Write または Edit ツール
• ".*" - すべてのツール

実践例

例 1: ファイル保存時の自動フォーマット

最もよく使われる Hook です。Claude がファイルを編集した後に、自動的に Prettier を実行します。

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

環境変数

Hook スクリプトでは以下の環境変数が利用できます。

• $CLAUDE_FILE_PATH - 操作対象のファイルパス
• $CLAUDE_TOOL_NAME - 実行されたツール名
• その他のコンテキスト情報

例 2: ESLint の自動修正

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

エラーハンドリング

Hook のコマンドがエラーで終了すると、Claude Code のワークフローに影響する場合があります。|| true を付けるなど、エラーをグレースフルに処理しましょう。

例 3: 特定のファイルの編集を防止

PreToolUse を使って、特定のファイルへの編集をブロックできます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "node .claude/hooks/check-protected-files.js"
      }
    ]
  }
}

.claude/hooks/check-protected-files.js:

// 保護されたファイルへの編集をブロック
const protectedFiles = [
  'src/generated/',
  '.env',
  'package-lock.json'
];

const filePath = process.env.CLAUDE_FILE_PATH;

if (protectedFiles.some(p => filePath.includes(p))) {
  console.error(`このファイルは保護されています: ${filePath}`);
  process.exit(2); // 終了コード 2 でブロック
}

例 4: Notification Hook でカスタム通知

{
  "hooks": {
    "Notification": [
      {
        "matcher": ".*",
        "command": "osascript -e 'display notification \"Claude Code からの通知\" with title \"Claude\"'"
      }
    ]
  }
}

Hook の実行フロー

1. Claude がツールを呼び出そうとする

2. PreToolUse Hook が実行される
   ├── 終了コード 0 → ユーザー確認なしで実行（自動承認）
   ├── 終了コード 2 → ツール実行をブロック
   └── その他 → 通常のフロー（ユーザー確認）

3. ツールが実行される

4. PostToolUse Hook が実行される
   └── フォーマット、検証などの後処理

Hook の入出力の詳細

Hook スクリプトには、JSON 形式で入力データが標準入力（stdin）から渡されます。Hook の結果は標準出力（stdout）から JSON で返すことができます。

入力の例:

{
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "content": "..."
  }
}

PreToolUse の出力例（ブロック時）:

{
  "decision": "block",
  "reason": "このファイルは編集禁止です"
}

Hook 設定のベストプラクティス

1. シンプルに保つ

// 良い例: シンプルで分かりやすい
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "prettier --write \"$CLAUDE_FILE_PATH\""
      }
    ]
  }
}

2. エラーを適切に処理する

Hook のスクリプトが失敗しても、Claude Code の動作を止めないようにしましょう。

3. パフォーマンスを考慮する

Hook は頻繁に実行されるため、重い処理は避けましょう。

注意事項

• Hook のスクリプトは同期的に実行されます
• 長時間かかるスクリプトは避けてください
• PreToolUse で終了コード 0 を返すと、ユーザー確認をスキップします（セキュリティに注意）

まとめ

Hook	タイミング	主な用途
PreToolUse	ツール実行前	実行の許可/拒否
PostToolUse	ツール実行後	自動フォーマット、検証
Notification	通知送信時	カスタム通知

次は、外部ツールと連携する MCP を学びましょう。