マーベリックスのテックブログPublicationへの投稿
🎣

CursorとClaude CodeのHookまとめ&比較

msd
に公開
AI
Cursor
Claude Code
tech

経緯

  • 業務でCursorを使用するため、ドキュメントを読んでいたところHooksというのがあるのを知る
  • Claude Codeでもフックがあると聞き、CursorのHooksとの違いが気になった
  • Cursor/Claude Code共に初心者である自分が理解した内容をざっくりまとめたいという趣旨です

前提

概要比較

項目 Claude Code Cursor
ステータス 正式版 ベータ版
フックイベント数 9種類 6種類
設定ファイル settings.json hooks.json
設定場所 ~/.claude/settings.json
.claude/settings.json
.claude/settings.local.json 		~/.cursor/hooks.json
.cursor/hooks.json
実行形式 bashコマンド コマンド
入力方法 環境変数 + stdin stdin (JSON)
出力方法 stdout/stderr (+ JSON) stdout (JSON)

フック一覧の比較

Claude Code のフック（9種類）

フック名 タイミング 制御可能
PreToolUse ツール実行前 ✅ 許可/拒否/確認 (permissionDecision)
PostToolUse ツール実行後 ✅ ブロック可能 (decision: "block")
UserPromptSubmit プロンプト送信時 ✅ ブロック可能 (decision: "block")
Stop 停止時 ✅ 継続を強制可能 (decision: "block")
SubagentStop サブエージェント停止時 ✅ 継続を強制可能 (decision: "block")
SessionStart セッション開始時 ✅ コンテキスト注入 (additionalContext)
PreCompact コンテキスト圧縮前 ❌ 制御不可（監視のみ）
SessionEnd セッション終了時 ❌ 制御不可（ブロック不可、クリーンアップのみ）
Notification 通知時 ❌ 制御不可（監視のみ）

Cursor のフック（6種類）

フック名 タイミング 制御可能
beforeShellExecution シェル実行前 ✅ 許可/拒否/確認 (permission)
beforeMCPExecution MCP実行前 ✅ 許可/拒否/確認 (permission)
beforeReadFile ファイル読み取り前 ✅ 許可/拒否 (permission)
beforeSubmitPrompt プロンプト送信前 ✅ 送信の取り消し可能 (continue)
afterFileEdit ファイル編集後 ❌ 制御不可（監視のみ）
stop エージェントループ終了時 ❌ 制御不可（監視のみ）

主な違い

設計思想

Claude Code

  • PreToolUse/PostToolUseでツールを制御: 複数のツール（Task, Bash, Read, Write, Edit, Grep, Glob, WebFetch, WebSearchなど）に対して、ツール実行の前後でフックを実行
  • マッチャー機能: ツール名にマッチするパターンで特定のツールだけをフィルタリング可能（正規表現、ワイルドカード対応）
  • セッションライフサイクル管理: SessionStart（セッション開始/再開時）とSessionEnd（セッション終了時）でセッション全体を管理

Cursor

  • アクション別のフックイベント: beforeShellExecution、beforeMCPExecution、beforeReadFileなど、具体的なアクションごとに個別のフックイベントを提供
  • エージェントループの制御: エージェントループの定義済みステージの前後で実行され、動作の観察・ブロック・変更が可能

マッチャー機能

Claude Code

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "..."
          }
        ]
      }
    ]
  }
}
  • ツール名でフィルタリング可能
  • 正規表現、ワイルドカード使用可能
  • PreToolUse/PostToolUseでのみ使用可能

Cursor

{
  "hooks": {
    "beforeShellExecution": [
      { "command": "..." }
    ]
  }
}
  • マッチャー機能なし
  • フック自体が特定のアクションに対応
  • 条件分岐が必要な場合はコマンド/スクリプト内で実装

フックイベントの機能比較

機能 Claude Code Cursor
ツール実行前の制御 PreToolUse（すべてのツール） beforeShellExecution + beforeMCPExecution + beforeReadFile
ファイル編集後のフック PostToolUse（matcherで指定） afterFileEdit
プロンプト送信制御 UserPromptSubmit（ブロック可能） beforeSubmitPrompt（送信の取り消し可能）
停止制御 Stop/SubagentStop（継続を強制） stop（監視のみ）
コンテキスト注入 SessionStart（additionalContext）
UserPromptSubmit（stdout）		 agentMessage経由（間接的）
セッション終了処理 SessionEnd なし

ユースケース別の適性

Claude Code が優れている場面

  • セッション全体の管理が必要（SessionStart/End/PreCompact）
  • ツールの種類でフィルタリングしたい（マッチャー機能）
  • コンテキスト圧縮のタイミングで処理したい（PreCompact）
  • プロンプト送信をブロックしたい（UserPromptSubmit）
  • 停止を防いで継続させたい（Stop/SubagentStop）

Cursor が優れている場面

  • ファイル読み取り前のシークレット編集（beforeReadFile）
  • MCPサーバーの実行制御（beforeMCPExecution）
  • 会話単位・生成単位のトラッキング（conversation_id/generation_id）
  • エージェントとユーザーへの個別メッセージ（agentMessage/userMessage）
  • シンプルな設定で基本的な制御

まとめ

両者について調べる前は、なんとなく似た機能なんだろうほどの理解でしたが、
Claude Codeにはマッチャーがあるため、同じフックイベント内で複数のツールを細かく制御できる柔軟性があると感じました。
一方でCursorはフックイベント自体が特定のアクションに対応しているため、設定がシンプルで理解しやすい設計になっています。
それぞれの特性を理解した上で活用していきたいと思いました！

おまけ

CursorのカスタムコマンドとHooksの違い

Cursot内でのチャットでカスタムコマンドとHooksに似た雰囲気を感じたので
違いや使い分けのポイントを比較してまとめてみました。

基本概要

項目 カスタムコマンド（Chat Commands） Hooks
定義 チャットで使う再利用可能なワークフロー エージェントループを監視・制御・拡張する仕組み
実行方法 /を入力して手動で実行 特定のイベントで自動発火
定義形式 Markdownファイル（.md） JSONファイル（hooks.json）
実行内容 Markdownで記述されたプロンプト コマンド（シェル文字列、スクリプトパス等）
実行タイミング 能動的（ユーザーが指示） 受動的（イベント駆動）
レベル チャットベース システムレベル
主な目的 ワークフローテンプレート 動作の制御・監視

使い分けのポイント

場面 カスタムコマンド Hooks
決まった手順の作業 ✅ 最適 ❌ 不向き
チーム内標準化 ✅ 最適 △ 補助的
能動的な作業開始 ✅ 最適 ❌ 不向き
自動ルール適用 ❌ 不向き ✅ 最適
セキュリティ強制 ❌ 不向き ✅ 最適
品質チェック自動化 △ 補助的 ✅ 最適
操作の記録・監視 ❌ 不向き ✅ 最適
マーベリックスのテックブログ
マーベリックスのテックブログPublication

北海道札幌発・株式会社マーベリックスのテックブログです。 フロントエンド、バックエンド、AWS、AI駆動開発まで、エンジニアの日常と実験を気ままに発信していきます。

Discussion