Cursor Hooksとは？仕組みと設定・活用例を徹底解説

Cursor Hooksとは？Agentループをカスタマイズする仕組み

Hooksの3つの役割：観察・制御・拡張

室谷代表取締役

Hooks って、ドキュメントを読むと observe / control / extend の3つの役割に分かれるんですよね。シリコンバレーのチームだと「観察」目的で導入するケースが多くて、agent の行動を全部ログに残すのに使ってます。

テキトー教師.AI認定講師

たしかに。現場でよく聞くのは「何をやらかしたか把握したい」というニーズです。

セキュリティ面だと、PII（個人情報）がコードに含まれていないかスキャンするのに使ったりもします。

室谷代表取締役

制御の面だとたとえば「本番DBへのSQL書き込みをブロックする」とか。agent が暴走しないようにガードレールを設置できる。

うちのチームでも、beforeShellExecution で危険なコマンドを弾く hook を書いてますね。

テキトー教師.AI認定講師

拡張はもう一歩進んで、agent の出力を自動整形したり、コミットメッセージを生成したり。編集後に必ずフォーマッタを走らせる、みたいな使い方です。

どんなタイミングで発火するのか（Agent / Tab / アプリ）

室谷代表取締役

Hooks には発火トリガーが3系統あるんですよね。Agent の操作中（Cmd+K や Agent Chat）、Tab の自動補完中、それ以外のアプリライフサイクル。

テキトー教師.AI認定講師

Agent 系は細かい。preToolUse はツール呼び出し直前、postToolUse は直後、beforeShellExecution はシェル実行前。

タブの補完だと、beforeTabFileRead でファイル読み取りを制御できるんですね。

室谷代表取締役

アプリ系は workspaceOpen だけ。ワークスペースを開いたタイミングで1回だけ発火する。

initial context を注入したいときとか。

テキトー教師.AI認定講師

つまり、agent が何をするかによって適切なフックポイントを選べる。最初は「とりあえず postToolUse で全部キャッチ」って人が多いけど、実際はもっと細かく制御できます。

HooksとRules、Skills、Commandsの違い

テキトー教師.AI認定講師

これ、よく混乱されるんですよ。Rules は「常に適用されるお作法」で、特定のファイルタイプに絞って .mdc に書く。

Skills は「たまに使うワークフロー」をまとめたもの。

室谷代表取締役

Commands はユーザーが手動で実行する単発コマンド。で、Hooks は「自動的に発動するスクリプト」。

言ってみれば、Rules が静的なルールなら、Hooks は動的なイベントハンドラー。

テキトー教師.AI認定講師

役割が全然違うので、最初に「何を解決したいか」を整理したほうがいい。定型ルールなら Rules、自動化したいなら Hooks。

室谷代表取締役

そう。例えば「agent に特定のコード規約を守らせたいだけ」なら Rules で十分。

でも「agent が何か危ないことをする前に止めたい」なら Hooks が必要。コスト対効果で考えると、まず Rules で試して、足りない部分を Hooks で補うのが現実的ですね。

Cursor Hooksの設定方法：hooks.jsonの書き方と配置場所

プロジェクトレベルとユーザーレベルの設定

室谷代表取締役

設定ファイルの配置場所、知っておくと結構大事なんですよね。プロジェクトルートに .cursor/hooks.json を置くか、ユーザーのグローバルディレクトリに置くかで振る舞いが変わる。

テキトー教師.AI認定講師

そうなんです。プロジェクトに置けばチームで共有できるけど、個人の好みで設定したいならユーザーレベル。

最初に戸惑うのが「どっちに書けばいいんだ？」ってところですね。

室谷代表取締役

うちの現場でも、プロジェクト固有のルールは .cursor/ に入れて、共通のスクリプトはグローバルに置くって使い分けてます。Enterprise だと管理画面からチーム全体に強制もできるみたいで。

テキトー教師.AI認定講師

あ、それ良いですね。プロジェクトレベルはチームのガバナンス、ユーザーレベルは個人の補助的なスクリプト、みたいな棲み分けが実践的です。

JSON形式の基本構造と記述例

テキトー教師.AI認定講師

で、実際の hooks.json の中身はどんな書き方になるんですか。

室谷代表取締役

基本はこう。

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/check-format.mjs"
          }
        ]
      }
    ]
  }
}

テキトー教師.AI認定講師

これ、Claude Code の hooks に近い構造ですね。matcher でどのツール呼び出しに反応するか指定して、実際のスクリプトを command で書く。

室谷代表取締役

そうです。エージェントループの各イベントに対して、JSON で stdio 通信するサブプロセスを spawn するイメージ。

カスタムロジックを柔軟に差し込める。

テキトー教師.AI認定講師

ハマるポイントとしては、command に渡すスクリプトのパスが通ってないと動かないこと。プロジェクトルートからの相対パスか、絶対パスか、あらかじめ確認しておくといいです。

サポートされているHookイベント一覧

テキトー教師.AI認定講師

イベントの種類、かなり豊富ですよね。ドキュメント見ると agent hooks、tab hooks、app lifecycle hooks の3カテゴリに分かれてる。

室谷代表取締役

そう。Agent 系がメインで、sessionStart / sessionEnd から beforeShellExecution、afterFileEdit まで。

個人的によく使うのは preToolUse と beforeShellExecution。

テキトー教師.AI認定講師

そうそう。beforeShellExecution で危険なコマンドをブロックしたり、afterFileEdit でフォーマッタを走らせたり。

Tab 補完用の beforeTabFileRead なんかもあるんですね。

室谷代表取締役

ワークスペース起動時にだけ動く workspaceOpen も地味に便利。Cloud Agent では一部の hook しか動かないから注意が必要だけど。

テキトー教師.AI認定講師

最初に「どのイベントを監視すればいいか」を決めるのが肝心です。全部に hook 仕掛けるとオーバーヘッドが大きいし、目的に合わせて絞るのがコツですね。

実際の活用例：セキュリティ、フォーマット、自動テスト

危険なシェルコマンドをブロックする

室谷代表取締役

これが一番導入しやすいユースケースですね。MYUUU の現場でも、rm -rf や本番DBへの直接書き込みをフックでブロックしてます。

時給換算すると、事故防止のコストがゼロになるんですよね。

テキトー教師.AI認定講師

たしかに、最初に戸惑うのが「どのコマンドをブロックすべきか」ですが、hooks.json に beforeShellExecution を書いて、危険なパターンをリストアップするだけです。

室谷代表取締役

海外の事例だと、Oasis Security のようなパートナーが、Agentic Access Management として最小権限ポリシーを適用してるみたいです。

コード編集後の自動フォーマット

テキトー教師.AI認定講師

これは一番お手軽な使い方です。afterFileEdit フックで Prettier や ESLint を走らせれば、AI が書いたコードを自動で整形してくれます。

室谷代表取締役

エンタープライズだと、チーム全体のコードスタイルを強制できるのが大きい。個々の開発者の好みに合わせる必要がなくなる。

テキトー教師.AI認定講師

実装も簡単で、hooks.json に「prettier --write を実行」と書くだけ。初めて触る人でもすぐ導入できます。

室谷代表取締役

コードレビューの工数も減るので、ROI で見ると導入コストを即回収できますね。

PIIやシークレットのスキャン

テキトー教師.AI認定講師

ここが一番ホットな話題かもしれません。AI エージェントがうっかり API キーや個人情報をコードに含めてしまうのを、beforeReadFile や beforeSubmitPrompt でブロックできます。

室谷代表取締役

1Password がパートナーとして hooks を提供してて、環境変数ファイルが正しくマウントされてるか検証してからシェルコマンドを実行する仕組みになってる。

テキトー教師.AI認定講師

セキュリティチームとしては、シークレットが AI のコンテキストに載る前に止められるのが安心です。

室谷代表取締役

これマジで、エンタープライズで Cursor を導入するなら必須の設定だと思いますね。

エンタープライズでの活用：ガバナンスとパートナー連携

パートナーツール（MintMCP, Semgrep, 1Password等）との統合

室谷代表取締役

hooks の本当の価値は、社内のセキュリティ基盤とAgentを繋げられることだと思ってます。Cursor は MintMCP や Semgrep、1Password といったパートナー統合を用意してるんですよね。

テキトー教師.AI認定講師

たしかに、単体で使うより既存のツールチェーンに組み込めるかどうかが現場の導入を左右します。MintMCP は MCP ツールの実行をフックして監視する仕組みですし。

室谷代表取締役

Semgrep なんかは、AIが生成したコードを自動でスキャンして脆弱性があればエージェントに修正させる。これ、従来のレビュープロセスをショートカットできるんですよ。

テキトー教師.AI認定講師

1Password の統合も面白い。環境変数が正しくマウントされているか shell 実行前にチェックして、シークレットをディスクに書かずに使えると。

チーム全体にフックを適用する方法

テキトー教師.AI認定講師

個人で試すのは簡単なのですが、組織全体で hooks を管理するとなると話が変わります。どうやって展開するのが現実的ですか。

室谷代表取締役

Enterprise プランだと、チームフックとエンタープライズ管理フックが使えます。管理画面から組織全体の hooks を設定して、全プロジェクトに強制適用できる。

テキトー教師.AI認定講師

プロジェクト固有の hooks を .cursor/hooks.json に置く方法もありますし、ユーザーレベルの設定も可能。現場では「まずはプロジェクトで試して、チームに昇格させる」という流れが多いですね。

室谷代表取締役

そう。Cloud Agents でも hooks は有効で、リポジトリの .cursor/hooks.json を読み込む。

Enterprise なら管理フックも並走するから、ガバナンスを効かせつつ開発者に自由を与えられる。

監査ログとコンプライアンス対応

室谷代表取締役

hooks の導入で見逃せないのが監査です。Admin API に audit-logs エンドポイントがあって、team_hook イベントを記録できる。

テキトー教師.AI認定講師

どのフックがいつ有効化されたか、誰が変更したか、組織のコンプライアンス要件に合わせて追跡できると。うちの現場でも、定期的に監査ログをエクスポートしてチェックしています。

室谷代表取締役

しかも Audit Logs のイベントタイプ一覧に team_hook が明記されてるから、API 経由でプログラム的に取得できる。SIEM に流すのも難しくない。

テキトー教師.AI認定講師

とはいえ、初めて監査ログを設定する人は「どのイベントを取ればいいか」で迷いがち。まずは hooks の有効化・変更ログだけでも押さえておくと、後々役立ちます。

パフォーマンスとデバッグ：Hooks導入のベストプラクティス

フックによるレイテンシへの影響

室谷代表取締役

Hooks、仕組みとしては便利なんですけど、どうしてもレイテンシとのトレードオフが出るんですよね。プロセスをspawnしてstdioでJSONのやりとりをするので、軽量なスクリプトならいいんですが、重い処理をフックで回すとAgentのターン終了が遅れる。

テキトー教師.AI認定講師

たしかに。最初にハマる人は「とりあえずLintやフォーマッタをフックで毎回実行」ってやるんですが、コード保存のたびに数秒待たされることになる。

フックはあくまで「観察・ブロック・変更」のための仕組みで、バックグラウンド処理を全部フックに押し込む設計は避けたほうがいい。

室谷代表取締役

そう。時給換算すると、毎回1秒のロスでもチーム全体で見ると馬鹿にならない。

特にbeforeShellExecutionのような同期的にブロックするフックは、本当に必要なときだけ仕込むべき。

デバッグ手法とトラブルシューティング

テキトー教師.AI認定講師

フックが動かない、というトラブルは現場でよく聞きます。例えばWindows環境だとバージョンによってフックが呼ばれなくなった事例もあります。

まずやるべきは、最小限のスクリプトで動作確認することです。

室谷代表取締役

具体的には、hooks.jsonにecho "hello"みたいなシェルコマンドを書いて、Cursorの設定画面で「Hooks」パネルを確認する。あそこにフックの呼び出し履歴が出るので、呼ばれているのにスクリプトが動いていないのか、そもそもフックがトリガーされていないのか切り分けられる。

テキトー教師.AI認定講師

さらに、フックの出力はstdoutに書き込むとログとして残るので、デバッグ時にはechoやconsole.log的に使うといいです。あとはパス問題。

.cursor/hooks.jsonの配置場所が間違っているケースも多い。プロジェクトルートかユーザーホームに置くのを忘れずに。

室谷代表取締役

そういう細かいミスで結構ハマる。あと複数のフックを同時に動かすと干渉しないか、という話もありますが…それはまた別の話。

複数フックの連鎖と実行順序

テキトー教師.AI認定講師

hooks.jsonでは複数のフックを配列で定義できますが、実行順序は定義順になります。例えばbeforeShellExecutionに二つフックを書くと、先に書いた方が先に走る。

室谷代表取締役

ここで注意したいのは、前のフックがブロックすると後のフックまで止まる点。特にbeforeShellExecutionでコマンドをブロックする場合、後続のフックに依存関係があると予期せぬ動作になる。

テキトー教師.AI認定講師

実務では、まずセキュリティチェックのフックを先に置いて、通ったらフォーマット用のフックを動かす、みたいな順番がよく使われます。逆順にすると、ブロックすべき処理が先に通ってしまう。

室谷代表取締役

そういう設計は経験がものを言う。最初はシンプルなフック一発から始めて、必要に応じて連鎖を組むのが安全。

エンタープライズだとチームでhooks.jsonをバージョン管理してレビューするのがベターです。

Claude Codeや他のAIエディタとの比較

Claude CodeのHooksとの互換性

室谷代表取締役

Cursor、公式でClaude Codeのhooksとの互換性を謳ってるんですよね。実際にhooks.jsonの構造も近い。

テキトー教師.AI認定講師

たしかに、現場で「Claude Codeで書いた設定そのまま持ってきたけど動く？」って声を聞きます。

室谷代表取締役

ただ、完全互換ではない。Claude CodeのPreToolUseのmatcherとか、その辺は読み替えが必要なケースがある。

テキトー教師.AI認定講師

まずはサードパーティーhooks対応のページを確認するのが確実ですね。

Cursor独自のフック機能と差分

室谷代表取締役

CursorにはClaude Codeにないフックがいくつかある。beforeMCPExecutionとか、MCPと連携するためのフックですね。

テキトー教師.AI認定講師

あと、Tab hooksやcloud agent専用のフックもありますね。Claude Codeはagentループ主体なので、そこは差別化ポイント。

室谷代表取締役

エンタープライズではチームフックや管理フックも使える。Claude Codeにはない機能です。

テキトー教師.AI認定講師

トリガーが細かいので、セキュリティポリシーを細かく設定したい組織にはCursorが有利かもしれません。

移行時の注意点

室谷代表取締役

移行するならhooks.jsonの配置場所を確認してください。Cursorはプロジェクトルートの.cursor/hooks.jsonとユーザーレベルの両方対応してます。

テキトー教師.AI認定講師

フック内のコマンドがWindowsとMacで動くかどうか、事前にテストしたほうがいいですね。

室谷代表取締役

Cloud agentsで使う場合は、一部のフックが動かないのも注意。sessionStartはdeferredになるとか、環境によって制限がある。

テキトー教師.AI認定講師

フォーラムでも「Claude Codeから移して動かない」という質問があります。まずは小さなフックで動作確認するのが無難です。

今後の展望：Cloud Agents対応とHooksの進化

Cloud Agentsでの動作と制限

テキトー教師.AI認定講師

Cloud AgentsでもHooksが使えるようになったのは大きいですね。ただし、ドキュメントを見ると読み取り専用の初期ターンでは動かないとか、一部のフックが制限されているみたいです。

室谷代表取締役

そうなんですよね。sessionStartが遅延する設計とか、Cloud Agentsの実行環境の違いを考慮した実装になってる。

Enterpriseだとチームフックや管理フックも反映されるから、ガバナンス目的で使うなら十分な印象です。

テキトー教師.AI認定講師

初期ターンでHooksが効かないのは、最初の探索フェーズでいきなりブロックされるのを避ける意図なんでしょうね。書き込み環境が確保されてからフックが走る、という動きは現場でも理解しやすいです。

室谷代表取締役

あと、サポートされていないフックのリストが明確にドキュメントに書いてあるのも親切。カテゴリごとに「Cloud Agentsでは使えない」と理由付きで整理されてるので、導入時に勘違いしにくいですね。

ロードマップとコミュニティ要望

室谷代表取締役

コミュニティフォーラムを見てると、プロジェクトレベルのフック対応を求める声が多いんですよね。今はユーザーレベルかプラグイン経由だけど、プロジェクトごとに異なるフックを切り替えたいというニーズは確かにある。

テキトー教師.AI認定講師

実際、Claude Codeではプロジェクトレベルでhooks.jsonを置けるんですよ。Cursorでも同じことができれば、セキュリティ要件の異なる複数プロジェクトを抱える組織には便利ですね。

室谷代表取締役

すでに一部のベータ版でプロジェクトフックが動いているという報告もある。あとは、パートナー連携のエコシステムがどう育つかですね。

MintMCPやSemgrepみたいなサードパーティ製のフック統合が増えれば、導入ハードルはさらに下がる。

テキトー教師.AI認定講師

Hooksのベータが始まったのが1.7からで、まだ半年も経ってない。コミュニティからのフィードバックを元に、サポートするフックの種類や実行タイミングの拡充が進むんじゃないでしょうか。

よくある質問

Q1. Cursor Hooksと.git/hooks/pre-commitって何が違うの？

室谷代表取締役

まったく別物ですよね。Gitフックはコミット前に走るローカルスクリプトですが、Cursor HooksはAIエージェントがコード生成するたびに介入できる仕組み。

目的が違います。

テキトー教師.AI認定講師

現場で「じゃあpre-commit置き換えですか？」って聞かれますが、むしろ併用が正解です。HooksでAIの出力を事前に整形して、pre-commitで最終チェックする、みたいな使い方が現実的ですね。

Q2. Hooksが動かないんだけど、よくある原因は？

テキトー教師.AI認定講師

大半はパス指定のミスか、JSONの末尾カンマでしょうね。hooks.jsonがプロジェクトルートにない、もしくはシェルのexit codeをちゃんと返してないケースが多いです。

室谷代表取締役

デバッグに時間かかるなら、最初はechoだけのフックで動作確認すると良いですよ。ROIで言うと、最初の10分でテストしておけば後々の工数が全然違う。

Q3. チームでHooksの設定を共有するにはどうすればいい？

室谷代表取締役

単純にhooks.jsonをGit管理すればいいんですけど、個人の環境差が出る場合はenv変数で切り替えるのが現実的です。USのチームだと.cursor/hooks/ごとリポジトリに入れてますね。

テキトー教師.AI認定講師

その際、.gitignoreでnode_modulesみたいな重いスクリプトを除外するのを忘れずに。シンボリックリンクで共通管理する手もあります。

Q4. Hooksはどのような言語で書けるの？

テキトー教師.AI認定講師

基本的に実行可能ファイルなら何でも大丈夫です。bashが一番手軽ですし、PythonやNode.jsでも書けます。

ただし、スクリプトの起動オーバーヘッドは考慮したほうがいいですね。

室谷代表取締役

エンタープライズだと、セキュリティポリシーでPythonしか許可されてないケースもあります。その場合でも、Hooks自体はスクリプトを呼ぶだけなので、言語の制約はあまり気にしなくて大丈夫です。

Q5. Cursor Hooksは非開発者でも使える？

室谷代表取締役

基本は開発者向けですが、ドキュメント生成やマークダウンの整形程度なら、非エンジニアでも設定ファイルをコピペすれば使えます。ただし、中身をカスタマイズするにはシェルスクリプトの知識が要るので、そこはハードルですね。

テキトー教師.AI認定講師

こういう時こそ、チーム内で「定型フック集」を共有すると良いですよ。「とりあえずリンターかける」程度なら、非開発者でも使ってもらいやすいです。

まとめ

室谷代表取締役

Cursor Hooks、一言で言えばAIの出力に人間のルールを差し込める仕組みです。これがないと、Agentループが好き勝手にコードを生成して、気づいたらプロジェクトの規約が崩壊してる──みたいな事態になりかねない。

テキトー教師.AI認定講師

特に、自動テストやフォーマットの強制は効果が大きいですね。最初は「手間が増える」と感じる人もいますが、慣れるとAIの提案をそのまま受け入れても安心感が違います。

室谷代表取締役

エンタープライズだと、ガバナンスの観点からHooksの導入が必須になってきてます。セキュリティチェックやコンプライアンス要件をHooksで自動化しておけば、AI活用のスピードと安全性を両立できる。

テキトー教師.AI認定講師

まだ発展途上の機能なので、Cloud Agents対応など今後のアップデートも楽しみです。まずは小さなフックから試してみて、チームに合った使い方を見つけてみてください。

室谷代表取締役

そうですね。まずはpre-commit的にエラーを吐くだけのフックを仕込んでみるのが、一番手軽な始め方だと思います。