Cursor は AI 補助付きの開発環境として注目を集めています。その中でも「Agent（エージェント）」機能は、ワークフローに合わせて挙動をカスタマイズできる点が特徴です。特に「Hooks（フック）」機能を使うと、Agent の動作の途中で処理を挟むことができ、柔軟な制御や自動化が可能になります。本記事では Hooks の概要と活用方法を整理します。
Hooks とは何か
Hooks は、Agent がタスクを実行する際の特定のタイミングにスクリプトやコマンドを挟める仕組みです。公式ドキュメントでは、Hooks は Agent の処理の前後に実行され、動作を監視・制御できるプロセスとして紹介されています。
簡単に言うと、Agent に指示を出すだけでなく、以下のような操作が可能になります：
- 任意のコマンド実行：例えば、コード編集後に自動でフォーマッタを走らせる
- ガードレール設定：危険なコマンドの実行をブロックしたり、機密情報を保護
- ログ・監査：Agent の操作を記録して利用状況を可視化
Hooks の基本的な使い方
1. 設定ファイル hooks.json を作る
Hooks の設定は JSON ファイルで行います。配置場所にはプロジェクト単位とユーザー単位があります：
- プロジェクト単位：
./.cursor/hooks.json - グローバル／ユーザー単位：
~/.cursor/hooks.json
基本構成の例：
{
"version": 1,
"hooks": {
"afterFileEdit": [
{ "command": "./hooks/format.sh" }
],
"stop": [
{ "command": "./hooks/notify.sh" }
]
}
}
ポイント：
"version": 1は必須です- 各フックイベントごとに複数のコマンドを配列で指定可能
"command"にはスクリプトのパスやシェル文字列を指定- スクリプトには実行権限を付与してください
2. 主なフックイベント
代表的なフックイベントには次のようなものがあります：
beforeSubmitPrompt：ユーザーがプロンプトを送信する直前beforeShellExecution：Agent がシェルコマンドを実行する前beforeMCPExecution：Agent が MCP を実行する前beforeReadFile：ファイルを読み込む前afterFileEdit：ファイル編集後stop：Agent のタスク終了時
例えば beforeShellExecution では、実行内容をチェックして必要なら拒否することも可能です。
3. スクリプトの入出力と制御
Hooks で呼び出されるスクリプトには、Cursor から JSON 形式で情報が渡されます。スクリプトは stdout を通してレスポンスを返します。たとえば beforeShellExecution では、次のような形で許可／拒否を返せます：
{
"permission": "allow" | "deny" | "ask",
"userMessage": "この操作は許可されません",
"agentMessage": "コマンドがブロックされました"
}
4. 導入の手順
Hooks を使い始める手順はシンプルです：
hooks.jsonを作成（最小構成で OK）- 簡単なスクリプトを用意してログ出力を確認
- Agent を実行してスクリプトが呼ばれることを確認
- 問題なければ実務に沿った自動化に拡張
- セキュリティやガードレールも併せて設置
Hooks の活用例
ファイル編集後の自動フォーマット
{
"version": 1,
"hooks": {
"afterFileEdit": [
{ "command": "sh -lc 'npm run format'" }
]
}
}
危険なコマンドのブロック
{
"version": 1,
"hooks": {
"beforeShellExecution": [
{ "command": "./hooks/block-danger.sh" }
]
}
}
block-danger.sh では、受け取った JSON の command をチェックし、対象コマンドであれば "permission": "deny" を返す仕組みです。
セッション終了時のログ記録と通知
{
"version": 1,
"hooks": {
"stop": [
{ "command": "./hooks/notify-session-end.sh" }
]
}
}
注意点とベストプラクティス
- Hooks はベータ版のため、仕様変更や未対応の挙動があり得ます
- スクリプトは必要最小限の権限で実行する
- 入出力データはサニタイズして脆弱性を防ぐ
- 複数のスコープに hooks.json がある場合、設定が合算されることがあるため注意
- ログや通知の頻度による運用負荷にも注意
まとめ
Cursor の Hooks 機能を活用すると、Agent の動作を自分たちのワークフローに合わせて柔軟にカスタマイズできます。ファイル編集後の自動処理、コマンド実行のガード、セッション終了時の通知など、さまざまな自動化を実装可能です。ベータ版である点に注意しながら、Hooks を使って効率的な開発環境を作りましょう。
コメント