最終更新日：2026年8月24日

Cursor AIのHooks機能を使えば、コード補完・レビュー・テスト実行などの繰り返し作業を自動化し、開発効率を大幅に向上できます。この記事では、Hooks機能の設定手順から実践的な活用事例まで、すぐに使える形で解説します。

読了時間：約8分

この記事で分かること：

  • ✔ Cursor AIのHooks機能が何をするものか、3分で理解できる
  • ✔ 設定ファイルの書き方からデバッグまで、ステップごとに実践できる
  • ✔ よくある設定ミスと、詰まったときの具体的な対処法が分かる

30秒で選ぶなら： → 単純なファイル保存時の自動フォーマットなら onSave Hook、コミット前の品質チェックなら preCommit Hook、AI補完のカスタマイズなら onCompletion Hookを選ぶ。

目次

  1. Cursor AI Hooks機能とは何か
  2. Hooks機能の設定に必要なツールと選び方
  3. Hooks機能の設定手順
  4. よくある失敗と対処法
  5. よくある質問（FAQ）
  6. まとめ

Cursor AI Hooks機能とは何か

Cursor AIのHooks機能とは、特定のイベント（ファイル保存・コミット・補完完了など）をトリガーとして、カスタムスクリプトやAI処理を自動実行する仕組みです。

たとえば、ファイルを保存するたびにESLintを走らせたり、AIによるコードレビューコメントを自動挿入したりできます。設定はJSON形式の設定ファイルに記述するだけで、追加ツールのインストールは最小限で済みます。

Hooks機能はCursor 0.40以降で正式にサポートされており、プロジェクト単位でも、グローバル設定でも適用できます。

Hooks機能の設定に必要なツールと選び方

Hooks機能を活用するうえで、連携するツールの選択が重要です。以下の表で主要な組み合わせを整理しました。

ツール・技術用途難易度主な用途
Node.js（v18以上）Hook用スクリプト実行低フォーマット・リント自動化
Python 3.10以上AI処理・データ変換スクリプト中カスタムAI連携
ESLint / Prettierコードフォーマット・品質チェック低保存時の自動整形
Git hooks（Husky）コミット前チェック中preCommit Hookとの併用
Shell Script（bash/zsh）軽量な自動化処理低〜中ファイル操作・通知

※2026年8月時点。各ツールのバージョン要件は公式ドキュメントを参照してください。

選び方の基準は「何をトリガーにするか」で決まります。

  • ファイル保存 → Node.js + Prettier/ESLintの組み合わせが最も設定コストが低い
  • コミット前の品質チェック → HuskyとCursorのpreCommit Hookを併用する
  • AI補完のカスタム処理 → Pythonスクリプトで柔軟に対応できる

チーム開発では、全員が同じバージョンのNode.jsを使っているかどうかを事前に確認してください。バージョンの不一致がHook失敗の原因No.1です。

Hooks機能の設定手順

最初は何から始めればいいか分からない人がほとんどです。以下のステップを順番に進めれば、30分以内に最初のHookを動かせます。

ステップ1：設定ファイルの場所を確認する

Cursor AIのHooks設定は、プロジェクトルートの .cursor/settings.json に記述します。グローバル設定の場合は ~/.cursor/settings.json を使います。

ファイルが存在しない場合は新規作成してください。

mkdir -p .cursor
touch .cursor/settings.json

Cursorを再起動すると設定ファイルが自動認識されます。この確認を省くと後で必ず詰まります。

ステップ2：基本構造を記述する

.cursor/settings.json に以下の基本構造を記述します。

{
  "hooks": {
    "onSave": {
      "command": "npx prettier --write ${file}",
      "enabled": true
    },
    "preCommit": {
      "command": "npx eslint . --fix",
      "enabled": true
    }
  }
}

${file} はCursorが自動で現在のファイルパスに置換する変数です。${workspaceRoot} でプロジェクトルートも参照できます。

ステップ3：使用可能なトリガーを選ぶ

Cursor AIのHooksが対応しているトリガーは以下の通りです。

トリガー名発火タイミング
onSaveファイル保存時
preCommitGitコミット直前
onCompletionAI補完完了後
onFileOpenファイルオープン時
onDiagnosticChangeエラー・警告の変化時

個人的には、最初に設定する価値が最も高いのは onSave だと思います。保存のたびにフォーマットが走ることで、コードレビューのコメントが「インデントのズレ」に集中しなくなり、本質的なレビューに時間を使えるようになります。

ステップ4：スクリプトファイルを作成する（応用）

複雑な処理が必要な場合は、コマンドに直接スクリプトファイルを指定します。

{
  "hooks": {
    "onSave": {
      "command": "node .cursor/hooks/onSave.js ${file}",
      "enabled": true
    }
  }
}

.cursor/hooks/onSave.js の中身の例：

const { execSync } = require('child_process');
const file = process.argv[2];

if (file && file.endsWith('.ts')) {
  execSync(`npx prettier --write ${file}`);
  execSync(`npx tsc --noEmit`);
}

TypeScriptファイルのみを対象にするなど、条件を細かく制御できます。

ステップ5：動作確認とログの確認方法

設定後は必ず動作確認をしてください。

  1. Cursorの「Output」パネルを開く（表示 > 出力）
  2. ドロップダウンから「Cursor Hooks」を選択
  3. 対象ファイルを保存してログが流れるか確認する

ログに Hook executed successfully が表示されれば正常動作しています。エラーが出た場合は次のセクションを参照してください。

よくある失敗と対処法

失敗1：Hookが実行されない（無音で何も起きない）

原因： enabled: true の記述漏れ、またはJSONの構文エラー。

JSONは1文字のミスで全体が無効になります。settings.json をJSONバリデーター（jsonlint.comなど）で確認してください。

// 悪い例（カンマ忘れ）
{
  "hooks": {
    "onSave": {
      "command": "npx prettier --write ${file}"
      "enabled": true  ← カンマなし
    }
  }
}

正直なところ、筆者も最初にこのミスで30分溶かしました。JSONの構文エラーはCursorがエラーメッセージを出さないケースがあるため、バリデーターの活用を強くすすめます。

失敗2：コマンドが見つからないエラー（command not found）

原因： CursorがシェルのPATH設定を引き継いでいない。

対処法：コマンドをフルパスで指定します。

{
  "hooks": {
    "onSave": {
      "command": "/usr/local/bin/node /path/to/project/.cursor/hooks/onSave.js ${file}",
      "enabled": true
    }
  }
}

which node でNode.jsのフルパスを確認し、そのまま貼り付けてください。npx もフルパス指定が必要なケースがあります（which npx で確認）。

失敗3：onCompletion Hookが補完の速度を下げる

原因： onCompletion に重い処理を紐付けると、AI補完のレスポンスが体感2〜3秒遅くなります。

これが意外と盲点になりやすいポイントです。onCompletion に指定するスクリプトは、処理時間200ミリ秒以内を目安にしてください。重い処理は非同期で実行するか、onSave に移す設計をとりましょう。

// 非同期実行の例
setImmediate(() => {
  // 重い処理をメインスレッドから切り離す
  require('./heavyProcess').run(file);
});

よくある質問（FAQ）

Q. HooksはCursorの全プランで使えますか？

A. Hooks機能はCursor Pro以上のプランで全機能が利用できます。Freeプランでは onSave と preCommit のみ対応しており、onCompletion などのAI連携HookはPro以上が必要です（2026年8月時点）。

Q. チームで同じHooks設定を共有する方法は？

A. .cursor/settings.json をGitリポジトリにコミットして共有します。ただし、絶対パスを記述した場合は各環境で動作しないため、${workspaceRoot} などの相対変数を使う設計にしてください。

Q. WindowsとMacでHooksの設定を共通化できますか？

A. コマンド部分にOSの差異が出るため、完全な共通化は難しいです。Node.jsスクリプトでコマンドを書き、Cursorの設定ファイルには node .cursor/hooks/xxx.js のみを記述する構成にすると、OS差異をスクリプト側で吸収できます。

まとめ

Cursor AIのHooks機能は、設定ファイル1つで繰り返し作業を自動化できる強力な仕組みです。

まず onSave フックでPrettierを動かす設定から始め、慣れたら preCommit と onCompletion に拡大するのが最も失敗しない進め方です。

この記事でやること：

  • ✔ .cursor/settings.json を作成して onSave Hookを設定する
  • ✔ Outputパネルでログを確認し、正常動作を確かめる
  • ✔ 慣れたらスクリプトファイルを分離して処理を高度化する

こんな人に向いています：

  • □ コード保存のたびに手動でフォーマットをかけている
  • □ コミット前のリントチェックを忘れることがある
  • □ 複数人開発でコードスタイルの統一に困っている

こんな人には向いていません：

  • □ Cursorを使い始めたばかりでエディタ設定に慣れていない（まずはAI補完の基本から始めるほうが効率的）
  • □ Freeプランで全Hooks機能を使いたい（Pro以上が必要な機能がある）

最終更新日：2026年8月24日

関連記事