Cursorのエージェント機能。 知っておきたい基本から実践まで

AIを「なんとなく使っている」という人は意外と多い。特にエージェント機能は、ただ質問するだけの使い方とは一線を画す強力な機能だ。この記事では、Cursor のエージェント機能を実際に使ってみてわかった基本的な仕組みから実践的な使い方まで、開発者向けに整理してみました。

そもそも「エージェント」って何をしてくれるの？

Chat ツールに慣れていると、エージェントとの違いが最初はピンとこないかもしれない。
一言で言うと、エージェントは「自律的に動く」。コードベースを横断して検索し、複数ファイルを編集し、ターミナルコマンドを実行し、エラーが出れば自分で直しにいく。人間がレビューしながら一緒に進めていく感覚です。

内部的には、次の3つで構成されています。

構成要素	内容
Instructions	system prompt とルール（後述）
Tools	ファイル編集、コードベース検索、ターミナル実行、ブラウザ操作など
Model	タスクに応じて選択するモデル

つまり、エージェントは「指示・道具・頭脳」を持つ自律的な存在です。

4つのモード、使い分けていますか？

エージェントには4つのモードがあり、Shift + Tab で順番に切り替えることができます。

モード	向いている場面	ファイル編集
Agent	機能開発、リファクタリング、バグ修正全般	あり
Ask	コードの読解、アーキテクチャ把握	なし（読み取り専用）
Plan	複雑な機能を計画してから進めたい	あり（プラン承認後）
Debug	実行時情報が必要な厄介なバグ	あり

よくやりがちなのが、なんでもかんでも Agent モードで突っ込むパターン。「このコードの意図を理解したい」だけなら Ask モードで十分だし、「大規模なリファクタリングを慎重に進めたい」なら Plan モードで一度計画を立ててもらうと精度が上がります。

起動と基本操作

Mac：Cmd + I
Win/Lin：Ctrl + I

これで右側にエージェントパネルが開きます。
主なショートカットはこちら。

操作	キーボードショートカット
Agent パネルを開く	Cmd/Ctrl + I
モードを切り替える	Shift + Tab
モデルを切り替える	Cmd + /
実行中にメッセージをキュー追加	Enter
キューをスキップして即時送信	Cmd + Enter
エージェントを停止	Cmd + Shift + Backspace

@ メンションを使いこなして適切なコンテキストを渡す

エージェントへの指示の質は、どれだけ的確なコンテキストを渡せるかに左右される。入力欄で @ を打つと候補が出てくる。

内容	＠メンション
特定のファイルやフォルダを渡す	@<file> / @<folder>
インデックス済みのドキュメントを参照	@Docs
ターミナルの出力をコンテキストに含める	@Terminals
過去のチャット内容を参照	@Past Chats
未コミットの変更差分	@Commit
ブランチ全体の差分	@Branch
組み込みブラウザのコンテキストを添付	@Browser

関連ファイルが分かるなら @ で明示的に渡す、分からないなら自然文で依頼して自動検索に任せる、という使い分けをしましょう。

「何を作るか」だけではなく「どこに・何を・どう作るか」

エージェントへの指示は、具体的であるほどより良い成果物を得ることができます。

また、既存ファイルを @ で渡して「この規約に揃えて」と伝えるのも有効です。かならずしもこのやり方が有効ではありませんが、複雑な変更は一度に頼まず、小さく刻んで進めるのが鉄則。もし細かく指定する部分が曖昧な場合は、一旦Planモードで仕様を整理し、AIとともに詰めていくのも有効だと感じました。

ルール：エージェントへの「永続的な指示書」

毎回プロンプトに書かなくても、繰り返し使いたい指示はルールとして設定できる。

種類	場所・範囲
プロジェクトルール	.cursor/rules/ 配下（Git管理可）
ユーザールール	Cursor Settings → Rules（全プロジェクトに適用）
チームルール	ダッシュボード（Team / Enterprise 限定）
GENTS.md	プロジェクトルートに置く Markdown

手軽に始めるならまずは AGENTS.md 一枚から。こんな形で書けます。

# プロジェクト指示

## コードスタイル
- TypeScript を使用する
- 関数コンポーネント + Hooks を基本とする
- スタイリングは Tailwind CSS

## アーキテクチャ
- コンポーネントは `src/components/` 配下
- 共通ロジックは `src/lib/` または `src/hooks/` に集約

より細かく制御したいなら、.cursor/rules/ 配下に .mdc ファイルを作り、適用範囲をフロントマターで指定する。

--- 
globs: src/components/**/*.tsx
alwaysApply: false 
---
- named export を使う（default export は禁止）
- 200行を超えたら分割する

ルールは /create-rule コマンドで自動生成もできる。ただし「エージェントが同じミスを繰り返すようになったとき」だけ追加し、ルールを増やしすぎることは避けましょう。
ルールが肥大化していくと、大量のルールを読み込むこととなり追加しているはずのルールに従えなくなってしまいます。

ターミナルとブラウザ連携

ターミナル

エージェントはサンドボックス環境でコマンドを実行する。自動実行モードは3段階。

モード	挙動
Run in Sandbox	サンドボックス内で自動実行（推奨）
Ask Every Time	すべて手動承認
Run Everything	承認なしで全実行

Run Everything はいきなり設定しない方が良いでしょう。信頼できないリポジトリで使うのは特に危険な行為で、破壊的なコマンドを知らずに実行されることになる可能性もあります。

モードを選び作業しだす前に、保護設定（ファイル削除保護・ドットファイル保護・外部ファイル保護）も確認しておこう。

ブラウザ

@Browser を使うと、実ブラウザを操作してページ遷移・クリック・入力・スクリーンショット取得・コンソールログの確認まで行えます。開発サーバーを立ち上げた状態で使うと、エージェントが起動中のポートを認識してくれる。

チェックポイントと Gitの違い

エージェントは大きな変更の前に自動でチェックポイントを作成します。過去のメッセージにホバーして「Restore Checkpoint」をクリックするだけでロールバックできる。

ただし、これはローカル保存でGitとは独立している。永続的なバージョン管理は必ず Git など他の方法で別途行うこと。「チェックポイントがあるから大丈夫」は危険かもしれません。

エージェントとうまく使いこなすコツ

1. モードを意識して使い分ける —
   Ask / Plan / Agent / Debug をタスクに合わせて選ぶ
2. コンテキストを明示する —
   @ メンションと具体的な指示でブレを減らす
3. 小さく刻んでレビューする —
   一気にやらせず、差分を確認しながら進める

エージェントはなんでも出来て心強いけど、指示の曖昧さはそのまま結果の曖昧さになる。この３点を意識しながら使えば使うほど「何を伝えれば動いてくれるか」のコツが身についていきます。ぜひ試してみてください。