Cursor Agent Mode 完全ガイド：AIアシスタントにプログラミングを代行させる
深夜1時、私は引き継いだばかりのコードベースを見つめていました。200以上のファイルが散らばり、リファクタリングを待っています。以前なら、Chat Mode を使って AI に一つずつ質問し、行ったり来たりしながら2〜3時間かけてようやく解決していたでしょう。しかし先週から Agent Mode を使い始めました。Cursor に一言「このプロジェクトを旧版 Vue から Vue 3 にアップグレードして」と伝えるだけで、コーヒーを一杯飲んでいる間に、Agent がプロジェクト全体を一新し、アップグレードによるエラーも自動修正してくれました。
正直なところ、これはプログラミングツールに対する私の理解を変えました。「ツールがコードを書くのを手伝う」のではなく、「ツールが私の代わりにプログラミングする」のです。
Cursor Agent Mode とは
テクニックを話す前に、Agent Mode とは何かをはっきりさせておきましょう。多くの人が通常の Chat Mode と混同しがちですが、実際には大きな違いがあります。
Chat Mode は「インテリジェントなコードアシスタント」のようなものです。「React コンポーネントをどう書く？」と聞けばコンポーネントを提示し、バグに遭遇して問題を説明すれば修正案を出します。プロセス全体は受動的で、あなたの指示を待っています。
Agent Mode は全く異なります。これは自律権を持つ「真のプログラミングアシスタント」のようなものです。「プロジェクト全体をリファクタリングして」と伝えれば、コードを書くだけでなく、自らファイルを読み、プロジェクト構造を理解し、テスト結果を確認し、発見した問題を自動修正します。プロジェクト内を動き回り、ターミナルでコマンドを実行し、複数のファイルを修正し、その変更が正しいか検証します。簡単に言えば、Agent Mode には「思考」があります。あなたが手取り足取り教えるのを待つのではなく、タスクの完全なフローを自分で考えます。
このモードは、複数ファイルに関わるタスクや多段階のタスクに特に適しています。新規プロジェクトの構築、大規模なリファクタリング、モジュールを跨ぐ複雑な変更など、Agent Mode の威力はこうした場面で真に発揮されます。
Agent Mode vs Chat Mode：実践比較
実際の例を使って、2つのモードの違いを見てみましょう。
タスク：既存の Next.js プロジェクトに TypeScript サポートを追加する。このプロジェクトには15のページ、10の API ルートがあり、すでに1年間運用されています。
Chat Mode のフローはおおよそこうなります：
- ステップ1：「Next.js プロジェクトに TypeScript を追加するには？」と聞き、チュートリアルを得る
- ステップ2：チュートリアルに従って tsconfig.json を作成し、手動で設定する
- ステップ3：「tsconfig.json はどう設定する？」と聞き、修正を繰り返す
- ステップ4：ファイルを一つずつ .js から .ts に変更し、その都度 AI に聞きながら修正する
- ステップ5：あるページで型エラーが発生し、また修正方法を聞く
- ステップ6：npm run build を実行すると大量のエラーが出て、一つずつ聞いて解決する
全工程で少なくとも10回以上 AI とやり取りし、毎回生成されたコードを手動でコピー＆ペーストする必要があります。通常1時間はかかり、途中でミスもしやすいです。
Agent Mode なら：一言伝えるだけです——「このプロジェクトを TypeScript にアップグレードして。すべてのコンパイルが通るようにして」。あとはスマホでも見ていればいいのです。この間に Agent は：
- プロジェクト全体を読み込み、ファイル構造を理解する
- tsconfig.json を自動作成・設定する
- ファイルごとの拡張子変更と型注釈の追加を行う
- コンパイルコマンドを自ら実行し、エラーを発見する
- エラーを見て自動的に型問題を修正する
- 最後に完全なビルド検証を実行する
全工程が5〜10分で完了し、コード品質も私が手動で設定するより高いです。重要なのは、私は一切手動操作をする必要がなく、優秀なシニアエンジニアが代わりに作業してくれたようなものです。
違いはここにあります：Chat Mode は「情報交換」、Agent Mode は「タスク実行」です。一方は質疑応答、もう一方は代理人です。
学ぶべき3つの Agent Mode テクニック
Agent Mode がこれほど強力なら、どうすれば使いこなせるでしょうか？半年間の試行錯誤の中で多くの落とし穴を経験し、3つの核心テクニックをまとめました。これらをマスターすれば、生産性は倍増します。
テクニック1：プロジェクトの目標と制約条件を明確に指定する
これは最も見落とされがちな点です。多くの人の失敗は、指令が曖昧すぎることです。「プロジェクトを最適化して」とだけ言っても、Agent Mode はハンドルのない車のようなもので、間違った方向へ進む可能性があります。
正しい方法はこうです：
最終目標を明確にする。「コードを改善して」ではなく、「初期表示時間を3秒から1秒に短縮して」と言います。AI には具体的で測定可能な目標が必要です。
技術スタックと制限を説明する。例えば「これは React 18 + TypeScript + Tailwind CSS のプロジェクトで、パッケージ管理には pnpm を使用し、ターゲット環境は Node 18+ です」。こうすれば、AI が既存の技術スタックと競合するライブラリをインストールするような愚行を避けられます。
禁止事項をリストアップする。これは特に重要です。あるリファクタリングで「auth 関連のコードは変更しない」と明言しなかったために、AI が認証システム全体を書き換えようとして冷や汗をかいたことがあります。ですから、.cursorrules ファイルを使って明確に書きましょう：「src/auth ディレクトリは修正しない」「データベーススキーマは変更しない」といった制限です。
私の提案は、プロジェクトのルートディレクトリに .cursorrules ファイルを作成し、その中にすべての制約を明確にリストアップすることです。Agent Mode は自動的にこのファイルを読み、厳格に遵守します。毎回口頭で繰り返すより遥かに効率的です。
テクニック2：Symbol Index を使用してコンテキストを最適化する
これは少し隠れた機能で、知らない人も多いです。簡単に言えば、Symbol Index は Cursor がバックグラウンドでプロジェクトのために構築する「シンボルテーブル」です。すべての関数、クラス、変数がインデックス化されます。
なぜこれが重要なのでしょうか？Agent Mode がプロジェクト全体を理解するには、多くのファイルを読む必要があります。Symbol Index がなければ、プロジェクト全体のコードを読み込む必要があり、大量のトークンを消費し、効率も悪くなります。Symbol Index があれば、AI は「どの関数がどのファイルにあるか」「このクラスにはどんなメソッドがあるか」を素早く把握でき、読み込む必要のあるコード量を大幅に削減できます。
Symbol Index の有効化は簡単です：Cursor の settings で “Symbol Index” オプションを見つけ、オンにするだけです。そしてインデックス構築の完了を待ちます（初回は少し時間がかかりますが、以降は自動更新されます）。その後 Agent Mode を使うと、トークン消費は30-50%減少し、実行速度も倍になります。これは小さな最適化ではなく、質的な飛躍です。
テクニック3：明確なチェックポイントと受け入れ基準を設定する
Agent Mode がいくら賢くても、完璧ではありません。そのため、「中間チェックポイント」を設定し、AI がいつ停止して確認を待つべきかを知らせる必要があります。これにより、一つのミスが連鎖的に広がるのを防げます。
方法は、指令の中に明確な段階的目標を入れることです：
- 第1段階：新しいファイル構造を生成し、私のレビューを待つ
- 第2段階：既存コードを新構造に移行する
- 第3段階：テストとビルド検証を実行する
各段階の間で、AI の作業をチェックし、方向性が正しいことを確認してから次へ進めます。こうすれば、途中で問題があってもプロジェクト全体が崩壊することはありません。
同時に、明確な「成功指標」を定義します。「バグを修正して」ではなく、「このバグを修正し、すべての単体テストを実行して通過率95%以上を確保して」と言います。これで AI はいつタスクが本当に完了したかを知ることができます。
一般的な落とし穴と回避ガイド
テクニックの次は、いくつか共通の落とし穴について注意喚起しておきます。
落とし穴1：タスク記述が曖昧すぎる
前述しましたが、再度強調する価値があります。「パフォーマンスを最適化して」と Agent Mode に頼んで、本当にコードを好き勝手に書き換えられた人を見たことがあります。曖昧な指令は曖昧な結果を招きます。常に覚えておいてください：明確な指令 = 高品質なアウトプット。
落とし穴2：過度な依存、コードレビューをしない
Agent Mode を使い始めてから、完全に放任してしまう人がいますが、これは非常に危険です。AI が生成したコードは論理的に正しくても、規範、パフォーマンス要件、セキュリティ基準に適合していない可能性があります。特に認証、決済、データベース操作などの重要モジュールに関わる場合は、生成されたコードを必ずレビューしてください。
落とし穴3：一度にすべての作業を完了させようとする
一つの大きな指令ですべての問題を解決しようとしないでください。大きなタスクは分解が必要です。「プロジェクトの大規模リファクタリング」なら、「ステップ1：ディレクトリ構造変更」「ステップ2：ファイル移行」「ステップ3：インポート修正」のように段階的に進めます。この方が成功率は遥かに高いです。
落とし穴4：ツール権限と制約を設定していない
Cursor の Agent Mode はターミナルへのアクセス、ファイルの修正、コマンドの実行が可能です。権限を明確に設定しないと、誤ってファイルを削除したり、危険なコマンドを実行したりする可能性があります。必ず .cursorrules で「これらのコマンドは実行可能」「ファイルの削除は禁止、修正のみ」といったルールを明確にしてください。
結論
半年間 Cursor Agent Mode を使ってみて、最も強く感じるのは、これがプログラミングのあり方を変えたということです。コードを書く必要がなくなったわけではありません——私たちは永遠に思考し、アーキテクチャを設計し、重要な決定を下す必要があります。しかし、拡張子の手動変更、ファイルごとのコピー＆ペースト修正、反復的なリファクタリングといった「低価値」な単純作業は、AI に任せられるようになりました。
Agent Mode の3つの大きな利点は：自律性（手取り足取り教える必要がない）、完全性（コード断片ではなくプロジェクト全体を扱える）、検証可能性（自分でチェックして修正できる）です。
私のアドバイスは、もう迷わないことです。「ページにローディング状態を追加する」や「API エラー処理を標準化する」といった小さなタスクから Agent Mode を体験してみてください。アウトプットを見て、満足したら commit する。何度か経験すれば、自然とより大きなタスクを任せるようになるでしょう。
未来のプログラミングスタイルはこのようになるでしょう：人間が思考と決定を行い、AI が実装と検証を処理する。私たちがすべきは、このようなツールと共に働く方法を学ぶことです。
Cursor Agent Mode を使用する完全なフロー
目標の明確化から成果の検証まで、Agent Mode のワークフローをマスターする
⏱️ Estimated time: 45 min
- 1
Step1: ステップ1：プロジェクトと .cursorrules ファイルの準備
プロジェクトのルートディレクトリに .cursorrules ファイルを作成し、プロジェクトの制約とルールを明確にします。
記述例：
```
# プロジェクト制約
- 技術スタック：React 18 + TypeScript + Tailwind CSS + pnpm
- Nodeバージョン：18+
- パッケージ管理：pnpm を使用（npm や yarn は禁止）
- 修正禁止：src/auth ディレクトリ、データベーススキーマファイル
- コード規範：ESLint 設定、Prettier フォーマットに従う
- テスト要件：すべての変更には単体テスト必須
# 許可される操作
- src ファイルの修正（auth ディレクトリを除く）
- npm/pnpm コマンドの実行
- 設定ファイルの修正（tsconfig.json, vite.config.ts）
- 新しいページやコンポーネントの作成
# 禁止される操作
- ファイルの削除は禁止、修正または新規作成のみ
- .git ディレクトリの修正禁止
- 危険なコマンドの実行禁止（rm -rf 等）
``` - 2
Step2: ステップ2：Symbol Index 最適化の有効化
Cursor 設定で Symbol Index を有効にし、Agent Mode の効率を高めます。
操作手順：
1. Cursor 設定を開く（Cmd/Ctrl + ,）
2. "Symbol Index" を検索
3. "Indexing: Enable Symbol Index" オプションを見つける
4. 有効（On）に切り替える
5. インデックス構築の完了を待つ
インデックス構築時間はプロジェクトサイズに依存します：
• 小規模（<1000ファイル）：1-2分
• 中規模（1000-5000ファイル）：5-10分
• 大規模（>5000ファイル）：10-30分
完了後、Agent Mode のトークン消費は30-50%減少し、実行速度は倍以上になります。 - 3
Step3: ステップ3：タスク目標の明確な指定
Agent Mode に明確、具体的、測定可能な指令を与えます。
悪い指令：
❌ "プロジェクトのパフォーマンスを最適化して"
❌ "コード品質を改善して"
❌ "このモジュールをリファクタリングして"
良い指令：
✓ "トップページの読み込み時間を3秒から1秒以内に最適化して。コード分割、画像遅延読み込み、キャッシュ戦略を使用して"
✓ "LoginPage コンポーネントに TypeScript 型定義を追加して。すべての props に型宣言があり、ESLint チェックを通過することを確認して"
✓ "utils ディレクトリを機能別に auth, string, date の3つのサブディレクトリに分割し、すべての import 文を更新して"
重要な要素：
1. 具体的な目標結果（曖昧な改善ではない）
2. 測定基準（秒数、カバレッジ、テスト通過率）
3. 制約条件（何を変更してよいか、いけないか） - 4
Step4: ステップ4：チェックポイントと受け入れ基準の設定
指令の中で段階を分け、一つのミスが全体に影響するのを防ぎます。
段階的指令テンプレート：
```
Task: プロジェクト認証システムのリファクタリング
フェーズ1：分析と計画（私の確認待ちで停止）
- 現在の auth 関連コードを分析
- 新しいディレクトリ構造と API 設計を生成
- 修正が必要なファイルリストを作成
→ 停止して、私のレビューを待つ
フェーズ2：コード移行（継続して実行）
- 新しい auth ディレクトリとファイルの作成
- 既存の認証ロジックの移行
- import 文の更新
フェーズ3：検証とテスト（私の確認待ちで停止）
- すべての単体テストを実行し、通過率≧95%を確保
- ログインフローの手動テスト
- ビルドを実行し、エラーがないことを確認
→ 停止して、すべてのテスト通過を私が確認するのを待つ
成功指標：
- すべての単体テスト通過（>95%）
- npm run build 成功（エラーなし）
- ESLint チェック通過
- 機能テストでの退行なし
``` - 5
Step5: ステップ5：Agent Mode の起動と進捗監視
Cursor で Agent Mode を起動し、実行プロセスを観察します。
操作手順：
1. Cursor エディタを開く
2. Chat パネルにタスク指令を入力
3. "Agent" モードボタンをクリック（Chat ではなく）
4. "Send" をクリックまたは Enter で起動
監視のポイント：
• Agent がタスクを正しく理解したか観察
• 読み込むファイルや修正範囲が予想通りかチェック
• 実行方向が間違っていれば、すぐに "Stop" で中断
• 設定したチェックポイントで Agent が停止した際、コードをレビュー
一般的な実行ステップ：
1. プロジェクトファイル構造のリストアップ
2. 重要ファイルの読み込みと現状理解
3. 修正計画の生成
4. ファイル修正の実行
5. テストと検証の実行
6. 発見された問題の自動修正 - 6
Step6: ステップ6：成果の検証と完了
Agent 完了後、最終的なレビューと検証を行います。
検証リスト：
□ コード品質：生成コードが規範に適合しているか確認
□ テスト通過：npm test または package.json の test スクリプト実行
□ ビルド成功：npm run build を実行しエラーなしを確認
□ 新たな問題なし：関連機能が正常かテスト
□ Git 変更：git diff をチェックし、変更範囲が予想通りか確認
問題が見つかった場合：
1. 直接修正せず、Agent に問題箇所を伝える
2. Agent が自動修正し、再検証
3. または手動修正後、次のタスクを Agent に任せる
コミット前の最終チェック：
✓ git status で全変更が追跡されているか確認
✓ git diff --staged でコミット予定の変更を確認
✓ 満足なら git add && git commit
次回タスクへ：Agent の経験は現在のプロジェクトコンテキストに保持され、後続タスクはより効率的になります。
FAQ
Agent Mode と Chat Mode の核心的な違いは何ですか？いつどちらを使うべきですか？
Agent Mode は能動的な実行です。目標を設定すれば、AI が自律的にファイルを読み、コンテキストを理解し、複数ファイルを修正し、コマンドを実行し、結果をチェックし、自動修正します。大規模タスク、複数ファイルにまたがる変更、多段階の作業に適しています。
使用のヒント：
• 単一バグの修正？Chat Mode で十分
• つの関数をどう書くか？Chat Mode
• プロジェクト全体のアップグレード？Agent Mode
• 複数ファイルのリファクタリング？Agent Mode
• 広範囲の修正と検証？Agent Mode
簡単な判断基準：手動で「ステップバイステップ」で処理する必要があるなら Agent、一言で解決できる小さな問題なら Chat です。
なぜ Symbol Index を有効にすることが重要ですか？具体的にどう機能しますか？
重要性：
• 無効時：Agent はプロジェクトを理解するために全コードを読む必要があり、大量のトークンを消費します
• 有効時：Agent は「この関数はどこか」を素早く照会でき、必要なコードだけを読みます
効果データ：
• トークン消費30-50%減
• 実行速度1倍以上アップ
• Agent のプロジェクト理解が正確になり、ミスが減少
具体的な仕組み：
1. Symbol Index を有効にすると、Cursor がバックグラウンドで全プロジェクトをスキャン
2. シンボルテーブルを構築：クラスXはファイルA、メソッドYはクラスZ内
3. Agent がコードを理解する際、ファイル全体を読まずにシンボルテーブルを直接参照
4. コンテキスト消費を大幅に削減
大規模プロジェクト（1000+ファイル）で特に効果が顕著です。
Agent Mode が誤ってファイルを削除したり壊したりしませんか？
潜在的リスク：
• Agent はファイルの修正や削除が可能
• Agent は任意のターミナルコマンドを実行可能
• Agent は git 変更をコミット可能
リスク回避方法：
.cursorrules に明確なルールを記述します。例：
```
# ファイル削除は禁止、修正と新規作成のみ許可
操作制約：
- 既存ファイルの削除禁止
- src および config ディレクトリ内のファイルのみ修正許可
- .git, node_modules, dist ディレクトリの修正禁止
- rm や削除コマンドの実行禁止
- git 変更のコミット禁止、ファイル修正のみ
```
ベストプラクティス：
1. git で commit し、新 branch を作成する（ロールバックポイントを作る）
2. .cursorrules で Agent の操作範囲を制限する
3. チェックポイントメカニズムを使い、各段階でレビューする
4. Agent に過度な権限を与えず、ステップごとに実行させる
基本的に、.cursorrules が明確であれば、Agent は厳格に遵守します。勝手に削除するようなことはしません。
なぜ .cursorrules ファイルが必要なのですか？毎回指令で言ってはいけませんか？
利点1：永続性。.cursorrules はプロジェクト内にあり、後続の全 Agent タスクで読み込まれるため、毎回繰り返す必要がありません
利点2：チーム共有。git にアップロードすれば、チーム全体でプロジェクトの制約ルールを共有できます
利点3：漏れ防止。指令で制限を言い忘れると Agent が誤操作する可能性がありますが、.cursorrules は一元管理されます
利点4：完全性。.cursorrules は非常に詳細に記述できます（数百行でも可）が、指令が長すぎると冗長になります
実際の使用：
• 初回プロジェクト：.cursorrules を作成し、全制約をリストアップ
• 後続タスク：Agent が自動で .cursorrules を読み、指令は簡潔に済む
• ルール変更：.cursorrules だけ修正すればよく、全タスク指令を変える必要がない
比較：
❌ 毎回言う：「auth ディレクトリは削除しないで、DB スキーマは変えないで、.git は修正しないで...」
✓ .cursorrules に一度書けば、以降 Agent が自動遵守
推奨：.cursorrules で全体制約＋指令でタスク目標、という使い分け。
Agent Mode でエラーが出たらどうすればいいですか？途中で修正できますか？
実行エラー時：
1. "Stop" ボタンで Agent を即時停止
2. 何が行われたか確認（通常は部分的に変更されている）
3. 選択肢A：手動でエラー修正し、他のタスクを継続
4. 選択肢B：どこが間違っているか Agent に伝え、修正を継続させる
Agent のエラータイプと対応：
エラー1：理解のズレ。「トップページを直して」と言ったらプロジェクト全体を修正し始めた
→ 即時 Stop、「src/pages/index.tsx だけ修正して」と伝え、やり直させる
エラー2：コード問題。生成コードのロジックミスでテスト失敗
→ Stop、具体的な error message を Agent に伝えると、自動修正する
エラー3：操作範囲外。修正禁止ファイルを修正しようとした
→ .cursorrules が設定されていれば稀ですが、発生したら Stop して制約を更新
中断後の継続：
• 同じ Agent に問題修正を継続させる
• または手動修正後、Agent に次の段階のタスクを任せる
• Agent は既に行った変更と現在のコンテキストを記憶している
大タスクへの最良の戦略は、段階的に実行し、各段階後に Stop してチェックし、再開することです。これによりエラー時の影響範囲を最小限に抑えられます。
7 min read · 公開日: 2026年1月10日 · 更新日: 2026年2月4日
関連記事
AI コード生成のミスを減らす？この5つの Prompt テクニックで効率50%アップ
AI コード生成のミスを減らす？この5つの Prompt テクニックで効率50%アップ
Cursor 上級テクニック：開発効率を倍増させる10の実践的手法（2026年版）
Cursor 上級テクニック：開発効率を倍増させる10の実践的手法（2026年版）
Cursor バグ修正完全ガイド：エラー分析から解決策検証までの効率的ワークフロー
コメント
GitHubアカウントでログインしてコメントできます