Cursor Agentのツール活用術 - 検索・編集・実行を自動化

はじめに

Cursor Agentは、自然言語の指示を受けて自律的にタスクを実行するAIアシスタントです。その自律性を支えているのが、Agentが利用できる多様なツール群です。ファイルの読み取り、コードベースのセマンティック検索、Grep検索、Web検索、そしてターミナルでのコマンド実行まで、Agentは必要なツールを自動で選択して活用します。

本記事では、Cursor Agentのツール群を詳しく解説します。この記事を読むことで、以下のことができるようになります。

• Agentが利用するツールの種類と役割の理解
• 編集と再適用のワークフロー習得
• ターミナルコマンド実行の活用とセキュリティ設定
• Auto-run設定による自動化の最適化

実行環境と前提条件

実行環境

前提条件

• Cursor Agentの基本操作を理解していること
• 対象プロジェクトをCursorで開いていること
• ターミナル操作の基本知識があること

Agentのツール概要

Cursor Agentは、タスク実行に必要なツールを自動的に選択して使用します。これらのツールを理解することで、より効果的な指示を出せるようになります。

ツール一覧

Agentが利用できる主要なツールは以下のとおりです。

Agentはこれらのツールを組み合わせて、複雑なタスクを段階的に実行します。

flowchart TD
    A[指示を受け取る] --> B{必要なツールを判断}
    B --> C[File Read]
    B --> D[Codebase Search]
    B --> E[Grep]
    B --> F[Web Search]
    C --> G{編集が必要?}
    D --> G
    E --> G
    F --> G
    G -->|はい| H[File Edit]
    G -->|いいえ| I[結果を報告]
    H --> J{実行が必要?}
    J -->|はい| K[Terminal]
    J -->|いいえ| I
    K --> I

ファイル読み取りツール

File Readツールは、Agentがプロジェクト内のファイル内容を理解するための基本ツールです。

動作の仕組み

Agentは指示の内容から、読み取るべきファイルを自動的に判断します。たとえば「認証機能を改善して」という指示を受けると、以下のような流れでファイルを読み取ります。

1. プロジェクト構造を確認
2. 認証関連のファイルを特定（auth、login、jwt等のキーワード）
3. 関連ファイルの内容を読み取り
4. コンテキストを理解した上で改善案を提示

効率的なファイル読み取りの促し方

@メンションで明示的にファイルを指定することで、Agentの読み取り精度が向上します。

1
2
3
4
5
6

効率的な指示:
@src/auth/jwt.service.ts と @src/middleware/auth.middleware.ts を確認して、
トークン検証のロジックを改善してください

非効率な指示:
プロジェクト内の認証関連のファイルを全部読んで改善してください

大規模ファイルの扱い

Agentは大規模なファイルも効率的に処理します。ただし、コンテキストウィンドウには上限があるため、以下の点に注意してください。

• 必要な部分だけを読み取るよう指示する
• 複数の大規模ファイルを一度に参照しない
• ファイル全体ではなく特定の関数やクラスを指定する

コードベース検索ツール

Codebase Searchは、セマンティック検索によって関連コードを発見するツールです。単純な文字列マッチングではなく、意味的な類似性に基づいて検索します。

セマンティック検索の仕組み

Cursorは、プロジェクト全体を解析し、コードを埋め込みベクトルとしてインデックス化しています。このインデックスにより、以下のような検索が可能です。

• 「ユーザー認証を行っている箇所」→ 認証関連の全コードを発見
• 「データベースにアクセスしているサービス」→ DB操作を含むファイルを特定
• 「エラーハンドリングのパターン」→ try-catchや例外処理のコードを収集

検索精度を高める指示

セマンティック検索の精度を高めるには、具体的な機能や概念を指示に含めます。

1
2
3
4
5
6
7
8

良い例:
このプロジェクトでJWTトークンを生成している箇所を探してください

良い例:
ユーザーのパスワードをハッシュ化しているコードを特定してください

改善の余地がある例:
認証関連のコードを探してください（範囲が広すぎる）

2025年11月の改善：セマンティック検索の強化

Cursor 2.1で発表された研究によると、セマンティック検索はコーディングエージェントの性能を大きく向上させ、正確性を平均12.5%高めることが確認されています。コード変更の定着率も改善され、ユーザーの不満につながるリクエストが減少しました。

Grepツール

Grepツールは、テキストベースの高速検索を行います。正確な文字列やパターンを検索する場合に最適です。

Instant Grepの導入

Cursor 2.1で導入された「Instant Grep」により、Agentが実行するすべてのgrep コマンドがほぼ即時に完了するようになりました。この改善はすべてのモデルでサポートされています。

Grepの活用シーン

Grepは以下のようなシーンで特に有効です。

正規表現の活用

Grepは正規表現をサポートしています。複雑なパターンマッチングが必要な場合に活用できます。

1
2
3
4

指示例:
正規表現で「async function」で始まり「Service」で終わる関数定義を検索してください

パターン: async function \w+Service

Web検索ツール

Web Searchツールは、インターネット上の最新情報やドキュメントを取得します。

Web検索の活用シーン

以下のような状況でWeb検索が自動的に使用されます。

• 最新のライブラリバージョン確認
• APIドキュメントの参照
• エラーメッセージの解決策検索
• ベストプラクティスの調査

1
2
3

指示例:
Next.js 15の新しいApp Routerの使い方を調べて、
このプロジェクトに適用してください

Web検索の制御

Web検索が不要な場合は、指示で明示的に無効化できます。

1
2

Web検索を使わずに、プロジェクト内のコードだけを参照して
この問題を解決してください

ファイル編集ツール

File Editツールは、Agentがコードを追加、修正、削除するためのツールです。

編集の仕組み

Agentはファイルを編集する際、以下の流れで処理を行います。

1. 編集対象のファイルを読み取り
2. 変更内容を計画
3. 差分を生成
4. ユーザーに確認を求める（Auto-runが無効の場合）
5. 承認後、変更を適用

差分プレビューの確認

Cursor 2.0以降では、Agentが行った複数ファイルへの変更を、個々のファイルを行き来することなく、まとめて確認できるようになりました。差分プレビューでは、以下の情報が表示されます。

• 追加された行（緑色でハイライト）
• 削除された行（赤色でハイライト）
• 変更されたファイルの一覧
• 変更の概要説明

編集の承認と却下

差分プレビューを確認した後、以下の操作が可能です。

再適用（Re-apply）機能

編集が期待と異なる場合、追加の指示で修正を依頼できます。

1
2
3

初回の編集後:
エラーハンドリングは良いですが、ログ出力も追加してください。
また、日本語のエラーメッセージに変更してください。

Agentは前回の編集内容を踏まえて、差分だけを再適用します。

ターミナルコマンド実行

Terminal ツールは、Agentがシェルコマンドを実行するためのツールです。ビルド、テスト、パッケージ管理など、開発ワークフローの自動化に不可欠な機能です。

ターミナル実行の流れ

Agentがターミナルコマンドを実行する際の流れは以下のとおりです。

flowchart TD
    A[コマンド実行の必要性を判断] --> B{Auto-run設定}
    B -->|有効| C[コマンドを自動実行]
    B -->|無効| D[ユーザーに確認]
    D -->|承認| C
    D -->|却下| E[実行をスキップ]
    C --> F{サンドボックス設定}
    F -->|有効| G[サンドボックス内で実行]
    F -->|無効| H[通常環境で実行]
    G --> I[結果を報告]
    H --> I

サンドボックス化されたターミナル

Cursor 2.0以降、macOSとLinuxでは、Agentのコマンドがデフォルトで安全なサンドボックス内で実行されます。

サンドボックスの特徴は以下のとおりです。

• ワークスペースへの読み書きは可能
• インターネットアクセスは制限（設定で変更可能）
• 許可リストに登録されていないコマンドは自動的にサンドボックス内で実行
• ファイルシステムへの不正アクセスをブロック

サンドボックス設定のカスタマイズ

設定画面から、サンドボックスの動作をカスタマイズできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "cursor.terminal.sandbox": {
    "enabled": true,
    "allowNetwork": false,
    "allowGit": true,
    "allowedCommands": [
      "npm",
      "yarn",
      "pnpm",
      "node",
      "npx"
    ]
  }
}

Enterpriseでの管理者コントロール

企業プランでは、チーム全体に対してサンドボックス設定を強制適用できます。管理者は以下の項目を制御可能です。

• サンドボックスの利用可否
• Gitへのアクセス許可
• ネットワークアクセス許可

Auto-run設定によるワークフロー自動化

Auto-run設定は、Agentの自律性を制御する重要な機能です。適切に設定することで、確認作業を減らしつつ、安全性を確保できます。

Auto-runの設定レベル

Auto-runには複数の設定レベルがあります。

Safe モードで自動実行される操作

Safeモードでは、以下の操作が自動実行されます。

• ファイルの読み取り
• コードベース検索
• Grep検索
• 安全なターミナルコマンド（lint、format等）

以下の操作は確認が必要です。

• ファイルの書き込み
• 破壊的なターミナルコマンド
• 外部APIへのリクエスト

Auto-runのカスタマイズ

設定画面から、Auto-runの動作を細かくカスタマイズできます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

{
  "cursor.agent.autoRun": {
    "level": "safe",
    "autoApplyEdits": false,
    "autoRunTerminal": true,
    "terminalAllowList": [
      "npm test",
      "npm run lint",
      "npm run format"
    ],
    "terminalDenyList": [
      "rm -rf",
      "sudo"
    ]
  }
}

自動化のベストプラクティス

効果的なAuto-run設定のポイントを以下に示します。

1. 段階的に自動化: 最初はOffで操作を確認し、慣れてきたらSafeに移行
2. 許可リストの活用: よく使う安全なコマンドを許可リストに追加
3. 拒否リストの設定: 危険なコマンドを明示的にブロック
4. プロジェクトごとの設定: セキュリティ要件に応じてプロジェクトごとに設定を変更

実践：ツールを活用したタスク実行

実際のシナリオを通じて、ツールの活用方法を確認しましょう。

シナリオ1：新機能の実装

1
2
3
4
5
6
7
8

プロンプト:
ユーザープロファイル更新APIを実装してください。
以下の要件を満たしてください：
- PUT /api/users/:id/profile
- 名前、メールアドレス、アバターURLを更新可能
- 認証済みユーザーのみアクセス可能
- バリデーションエラーは400を返す
- 実装後、テストを実行してください

Agentの実行フロー:

1. Codebase Search: 既存のユーザー関連コードを検索
2. File Read: 認証ミドルウェア、バリデーションユーティリティを読み取り
3. File Edit: 新しいエンドポイントを実装
4. Terminal: npm test を実行してテスト

シナリオ2：バグの調査と修正

1
2
3
4
5

プロンプト:
本番環境で「TypeError: Cannot read property 'email' of undefined」
というエラーが発生しています。
@src/services/notification.service.ts が原因のようです。
調査して修正してください。

Agentの実行フロー:

1. File Read: 指定されたファイルを読み取り
2. Grep: email プロパティの使用箇所を検索
3. Codebase Search: 関連する呼び出し元を特定
4. File Edit: null チェックを追加して修正
5. Terminal: テストを実行して修正を確認

シナリオ3：依存関係の更新

1
2
3

プロンプト:
このプロジェクトの依存関係を最新バージョンに更新してください。
破壊的変更がある場合は、コードも修正してください。

Agentの実行フロー:

1. File Read: package.json を読み取り
2. Web Search: 各パッケージの最新バージョンと変更点を調査
3. File Edit: package.json を更新
4. Terminal: npm install を実行
5. Codebase Search: 破壊的変更の影響を受けるコードを特定
6. File Edit: 必要な修正を適用
7. Terminal: テストを実行

期待される結果

本記事の内容を実践することで、以下の状態を達成できます。

• Agentが使用するツールの役割と動作を理解し、効果的な指示を出せる
• 編集の差分プレビューを確認し、安全にコード変更を適用できる
• ターミナルコマンド実行のセキュリティ設定を適切に構成できる
• Auto-run設定を活用し、反復的なタスクを自動化できる

次の記事では、To-do機能とチェックポイントを活用した、大規模タスクの計画と管理方法について解説します。

まとめ

Cursor Agentのツール群を理解し活用することで、AI駆動開発の効率が大幅に向上します。ポイントは以下の3点です。

1. 適切なツールの理解: 各ツールの特性を理解し、指示に反映させる
2. セキュリティの確保: サンドボックスとAuto-run設定で安全性と効率性を両立
3. 段階的な自動化: 慣れに応じてAuto-runレベルを調整し、ワークフローを最適化

Agentは単なるコード生成ツールではなく、検索、編集、実行を統合した開発パートナーです。ツールの特性を理解し、適切な指示を出すことで、複雑なタスクも効率的に委任できます。

参考リンク

• Cursor公式ドキュメント
• Cursor Agent Tools
• Cursor Terminal - Sandboxing
• Cursor Changelog 2.1 - Instant Grep
• セマンティック検索によるエージェントの改善
• Cursor Features
• Cursor Enterprise - LLM Safety and Controls