Cursor Agent Mode 完全ガイド：AI アシスタントにプログラミングを任せる
引き継いだコードベースには、200 以上のファイルが散らばり、リファクタリング待ちだった。以前なら Chat Mode で AI に一つずつ聞き、2〜3 時間は往復していた。先週から Agent Mode を使い始めて、Cursor に「このプロジェクトを旧 Vue から Vue 3 にアップグレードして」と一言伝えるだけになった。あとはツールがプロジェクト全体を書き換え、移行で出たエラーも自動修復してくれる。
プログラミングツールへの見方が変わった。「コードを手伝ってもらう」ではなく、「代わりにプログラミングしてもらう」感覚だ。
Cursor Agent Mode とは
テクニックの前に、Agent Mode が何かをはっきりさせよう。Chat Mode と混同しやすいが、差は大きい。
Chat Mode は賢いコードアシスタントに近い。「React コンポーネントの書き方は？」と聞けばコンポーネントが返る。バグがあれば説明すれば修正案が出る。全体は受動的——あなたの指示を待つ。
Agent Mode は別物。自律権のあるプログラミング相手だ。「プロジェクト全体をリファクタリングして」と言えば、コードを書くだけでなく、ファイルを読み、構造を把握し、テスト結果を見て、問題を直す。ターミナルでコマンドを走らせ、複数ファイルを変更し、正しいか検証する。Agent Mode には「考える」余地がある——タスクの流れ全体を自分で組み立て、一歩ずつ教えるのを待たない。
複数ファイル・多段階の作業に向く。新規構築、大規模リファクタ、モジュール横断の変更——ここで Agent Mode の威力が出る。
Agent Mode vs Chat Mode：実践比較
具体例で差を見てみよう。
タスク：既存の Next.js プロジェクトに TypeScript を入れる。ページ 15、API ルート 10、1 年運用済み。
Chat Mode の流れはだいたい次のとおり。
- 「Next.js に TypeScript を足すには？」と聞き、チュートリアルをもらう
- 手動で tsconfig.json を作り、設定をいじる
- 「tsconfig の設定は？」とまた聞く
- .js を .ts に一つずつ変え、都度 AI に聞く
- 型エラーが出たページごとにまた聞く
npm run buildでエラーが山ほど出て、一つずつ聞いて直す
AI と 10 回以上やり取りし、生成コードを毎回コピペする。1 時間かかることも珍しくなく、途中でミスもしやすい。
Agent Modeなら一言——「このプロジェクトを TypeScript に移行し、すべてのコンパイルを通して」。あとは見守るだけ。Agent は次のことを自分で行う。
- プロジェクト全体を読み、構造を把握
- tsconfig.json を作成・設定
- 拡張子と型注釈を順に更新
- コンパイルを実行してエラーを検出
- 型問題を自動修正
- 最後にフルビルドで検証
5〜10 分で終わり、手動設定より品質が高いこともある。手を動かさず、シニアエンジニアが代行してくれたような感覚だ。
違いはここにある。Chat Mode は「情報のやり取り」、Agent Mode は「タスクの実行」。Q&A か、代理人か。
押さえるべき 3 つの Agent Mode テクニック
Agent Mode が強力でも、使い方次第だ。半年の試行でまとめたコアは 3 つ。これで生産性は体感で倍になる。
テクニック 1：目標と制約をはっきり書く
いちばん見落とされがちだ。指令が曖昧だと、ハンドルなしの車のように迷走する。
最終目標を具体化する。「コードを改善して」ではなく「初回表示を 3 秒から 1 秒以内に」。測れる目標が要る。
技術スタックと制限を書く。例：「React 18 + TypeScript + Tailwind CSS、pnpm、Node 18+」。既存スタックとぶつかるライブラリを入れさせない。
禁止事項を列挙する。リファクタ中に認証まわりを触られそうになったことがある。「auth は触るな」と書いていなかったからだ。.cursorrules に「src/auth は変更しない」「DB スキーマは変えない」と明記しよう。
ルートに .cursorrules を置き、制約を一覧化するのがおすすめ。Agent Mode は自動で読み、遵守する。毎回口頭で繰り返すより楽だ。
テクニック 2：Symbol Index でコンテキストを最適化
地味だが効く機能だ。Cursor がバックグラウンドで作る「シンボル表」に、関数・クラス・変数が載る。
Agent Mode はプロジェクト理解のために多くのファイルを読む。Symbol Index がなければコードを総なめ読みし、トークンも時間もかかる。有効にすると「どの関数がどのファイルか」「このクラスに何があるか」をすぐ引け、読む量を抑えられる。
有効化は簡単。Cursor の Settings で「Symbol Index」を探し、オンにする。初回インデックスは時間がかかるが、以降は自動更新。有効後はトークン 30〜50% 減、速度も体感 2 倍近い。小改善ではなく質の差だ。
テクニック 3：チェックポイントと受け入れ基準
Agent も完璧ではない。途中で止まって確認するチェックポイントをプロンプトに書く。一つのミスが連鎖するのを防げる。
例：
- フェーズ 1：新しいディレクトリ構造を出す → レビュー待ち
- フェーズ 2：既存コードを移す
- フェーズ 3：テストとビルド検証
段階のあいだに方向を確認できる。途中でズレてもプロジェクト全体は崩れにくい。
成功指標も具体化する。「バグを直して」ではなく「バグを直し、単体テストを全部走らせ、通過率 95% 以上」。いつ終わりかが Agent にも伝わる。
よくある落とし穴
落とし穴 1：タスクが曖昧
「パフォーマンスを最適化して」だけ渡すと、本当に好き勝手に触られる。曖昧な入力は曖昧な出力。明確な指令が高品質につながる。
落とし穴 2：レビューせず任せきり
Agent Mode を使い始めると放置したくなるが危険だ。論理は合っていても、規約・性能・セキュリティに合わないコードは出る。認証・決済・DB まわりは必ず人間がレビューする。
落とし穴 3：一度に全部やらせる
大きな指令一発は避ける。「大規模リファクタ」なら「ディレクトリ変更 → ファイル移行 → import 修正」と段階に分ける。成功率が上がる。
落とし穴 4：権限と制約の未設定
Agent Mode はターミナル・ファイル・コマンドに触れる。権限を書かないと、誤削除や危険なコマンドのリスクがある。.cursorrules に「実行してよいコマンド」「削除禁止、修正のみ」を明記する。
まとめ
半年使って感じるのは、プログラミングの進め方そのものが変わったことだ。コードを書かなくなるわけではない。思考、アーキテクチャ、重要な判断は人間の仕事だ。拡張子の手変更、ファイルごとのコピペ、同じリファクタの繰り返し——こうした低価値作業は AI に任せられる。
Agent Mode の強みは 自律性（一歩ずつ教えなくてよい）、完全性（断片ではなくプロジェクト単位）、検証可能性（自分でチェックして直せる）の 3 点。
まず小さなタスクで試してみてほしい。「このページに loading を足す」「API エラー処理を標準化する」など。出力を見て問題なければ commit。数回やれば、大きなタスクも自然に任せられるようになる。
これからの進め方は、人間が考えて決め、AI が実装と検証を担う形に近づいている。その協業の仕方を身につけることが、私たちの次の一歩だ。
Cursor Agent Mode を使う完全フロー
目標の明確化から成果検証まで、Agent Mode のワークフローを押さえる
Estimated time: PT45M
-
1
Step 1: ステップ 1：プロジェクトと .cursorrules の準備
ルートに .cursorrules を置き、制約とルールを書く。 -
2
Step 2: ステップ 2：Symbol Index を有効化
Settings で Symbol Index をオンにし、効率を上げる。 -
3
Step 3: ステップ 3：タスク目標を明確に
測定可能なプロンプトを渡す。 -
4
Step 4: ステップ 4：チェックポイントと受け入れ基準
段階を分け、一発ミスの波及を防ぐ。 -
5
Step 5: ステップ 5：Agent Mode を起動して監視
Cursor で Agent を走らせ、進捗を見る。 -
6
Step 6: ステップ 6：成果を検証して完了
Agent 終了後に最終確認。
FAQ
Agent Mode と Chat Mode の違いは？いつどちらを使うべき？
Agent Mode は能動的な実行です。目標を渡すと、AI が自律的にファイルを読み、コンテキストを把握し、複数ファイルを直し、コマンドを走らせ、結果を確認して自動修正します。大きなタスク、複数ファイルの変更、多段階の作業向きです。
使い分けの目安：
• 単一バグの修正 → Chat Mode で十分
• 1 つの関数の書き方 → Chat Mode
• プロジェクト全体のアップグレード → Agent Mode
• 複数ファイルのリファクタリング → Agent Mode
• 広い範囲の変更と検証 → Agent Mode
ざっくり言えば、手で「一歩ずつ」進める必要があるなら Agent。一言で済む小さなことなら Chat です。
Symbol Index を有効にするのはなぜ重要？どう動く？
なぜ効くか：
• 無効：Agent が全体を理解するためにコードを総なめ読みし、トークンを大量消費
• 有効：「この関数はどこ？」を素早く引け、必要な部分だけ読める
効果の目安：
• トークン消費 30〜50% 削減
• 実行速度 1 倍以上
• プロジェクト理解が正確になり、ミスが減る
流れ：
1. Symbol Index を有効にすると、Cursor がバックグラウンドでプロジェクトをスキャン
2. シンボル表を構築（クラス X はファイル A、メソッド Y はクラス Z 内、など）
3. Agent はファイル丸ごとではなくシンボル表を参照
4. コンテキスト消費を大幅に削減
ファイル 1000 超の大規模プロジェクトほど効果が出ます。
Agent Mode がファイルを誤って削除・破壊することはある？
想定されるリスク：
• ファイルの変更・削除
• 任意のターミナルコマンド実行
• git 変更のコミット
回避策：.cursorrules に例のように明記します。
```
# ファイル削除禁止。修正と新規作成のみ
操作制約：
- 既存ファイルの削除禁止
- src と config 配下のみ修正可
- .git、node_modules、dist は触らない
- rm など削除コマンド禁止
- git コミット禁止。ファイル修正のみ
```
ベストプラクティス：
1. git で commit し、新しい branch を切る（ロールバック点）
2. .cursorrules で操作範囲を限定
3. チェックポイントで段階ごとにレビュー
4. 権限を広げすぎず、段階的に実行
.cursorrules が明確なら、Agent は概ね厳守します。勝手に削除に走ることは稀です。
なぜ .cursorrules？毎回プロンプトで言えない？
利点 1：永続化。プロジェクトに置いておけば、以降の Agent タスクが毎回読める。繰り返し不要。
利点 2：チーム共有。git に載せれば全員が同じ制約を参照できる。
利点 3：漏れ防止。プロンプトで制限を忘れると誤操作の原因に。.cursorrules は一元管理。
利点 4：詳細さ。数百行でもよいが、毎回のプロンプトが長すぎると冗長になる。
運用：
• 新規プロジェクト：.cursorrules を作り、制約を一覧化
• 以降：Agent が自動で読むので、プロンプトはタスク目標中心でよい
• ルール変更：.cursorrules だけ直せばよい
比較：
❌ 毎回「auth を消すな、DB スキーマを変えるな、.git を触るな…」
✓ .cursorrules に一度書けば、以降 Agent が自動遵守
推奨：.cursorrules で全体制約 + プロンプトでタスク目標。
Agent Mode が途中で失敗したら？修正できる？
エラー時：
1. 「Stop」で即停止
2. 何が変わったか確認（部分的な変更が残ることが多い）
3. 手動で直して次へ進む、または Agent に誤りを伝えて直させる
よくあるパターン：
エラー 1：理解のズレ。「トップを直して」→ プロジェクト全体を触る
→ 即 Stop。「src/pages/index.tsx だけ」と伝えてやり直し
エラー 2：コードの論理ミスでテスト失敗
→ Stop し、具体的な error message を渡すと自動修正しやすい
エラー 3：範囲外のファイルを変更
→ .cursorrules があれば稀。起きたら Stop して制約を更新
中断後：同じ Agent に続けさせるか、手動修正後に次フェーズを任せるか。Agent はこれまでの変更とコンテキストを保持します。
大きなタスクは段階実行が最善。各段階で Stop して確認し、再開。影響範囲を最小にできます。
4分で読めます · 公開日: 2026年1月10日 · 更新日: 2026年6月15日
Cursor 完全ガイド
検索からこのページに来た場合は、前後の記事もあわせて読むと同じテーマの理解がかなり早く深まります。
前の記事
Cursor Agent モード完全ガイド：3 ステップで始める自動化プログラミング（2026 年最新）
2026 年最新：3 ステップで Cursor Agent モードに切り替え、AI にファイル作成・依存インストール・バグ修正を任せる方法。Auto-run（旧 Yolo）設定、現行モデル、5 つの実践例も収録。
第 2 / 25 記事
次の記事
Cursor Composer 完全ガイド：複数ファイル編集のコツと実践事例
Cursor Composer と Chat の違いを押さえ、5 秒判断法・複数ファイル編集の黄金律・7 つの落とし穴回避策を解説。axios 移行の実践事例付きで開発効率を倍増させます。
第 4 / 25 記事
関連記事
もう使い方を間違えるな！Cursor 3 機能の正しい開き方
もう使い方を間違えるな！Cursor 3 機能の正しい開き方
Cursor Rules 完全ガイド：プロジェクト規範に沿ったコードを AI に書かせる（実戦設定付き）
Cursor Rules 完全ガイド：プロジェクト規範に沿ったコードを AI に書かせる（実戦設定付き）
Cursor Rules 上級設定：自分専用の AI コーディングアシスタントを作る
コメント
GitHubアカウントでログインしてコメントできます