Cursor Agent モード＆YOLO モード実践ガイド

Agent モードは Cursor の中で間違いなく最も強力な機能ですが、多くの人がまだ正しく使うのを怖がっています。通常のチャットに留まり、コードスニペットを求めて手動でファイルに貼り付ける——それでも動作しますが、Cursor の潜在能力のおそらく 80% を捨てていることになります。

このガイドは、Cursor フォーラムで共有された実際のワークフローに基づいています。理論偏重の冗長な説明はなし——実際に機能する実用的な内容だけです。

Agent モードと通常チャット：実際の違い

新人が見落としがちなポイントはここです：Agent モードと通常チャットは完全に異なるものです。

機能	通常チャット	Agent モード
コードベースの読み取り	はい	はい
コード変更の提案	はい	はい
ターミナルコマンドの実行	いいえ	はい
ファイルの作成・変更	いいえ	はい
複数ファイル横断の検索	いいえ	はい
複数ステップのタスク	いいえ	はい
確認が必要	該当なし	はい（YOLO 除く）

通常チャットは、質問できる賢い同僚のようなものです。Agent モードは、実際に作業を実行できるジュニア開発者のようなものです——コマンドを実行し、ファイルを作成し、プロジェクト全体でコードを編集します。

チャットパネルのロボットアイコンで Agent モードに切り替えると、Cursor はファイルの読み書き、ターミナルコマンド、コード検索などのツールにアクセスできるようになります。複数ステップのアプローチを計画し、実行できます。

Agent モードを使うべき場面

「コードを見せて」以上のことを必要とするすべてのタスクです。チャットからコードをコピーしてファイルに貼り付けている自分に気づいたら、代わりに Agent モードを使うべきです。

YOLO モード：何か、そして使うべき場面

YOLO は "You Only Live Once" の略です。Cursor での YOLO モードとは、Agent がすべての確認ダイアログをスキップして、ただ……実行することです。

「ファイルの書き込みを許可しますか？」のポップアップなし。「このコマンドを実行しますか？」のプロンプトなし。Agent はタスクが完了するか、壁にぶつかるまで自律的に実行します。

YOLO が有効な場面

• 新規プロジェクトのスキャフォールディング——ディレクトリの作成、パッケージのインストール、ボイラープレートの生成
• バッチリファクタリング——50 ファイルでの変数名変更、import パスの更新
• 自動化タスク——テストファイルの生成、マイグレーションスクリプトの作成、ドキュメントの作成
• 使い捨ての作業——失敗したら git reset で元に戻せるもの

YOLO をオフにしておくべき場面

本番ブランチでは絶対に YOLO モードを使わないでください

マジで。悪い rm -rf や壊れたデータベースマイグレーションが発生した時に、確認ダイアログがなぜ存在するのか理解できます。

• 本番コードや main ブランチ——ここでは常に変更をレビューしてください
• データベース操作——マイグレーション、スキーマ変更、シードデータ
• CI/CD 設定——1 行間違えるとパイプラインが壊れます
• 元に戻せないもの——元に戻せない場合は、YOLO しないでください

YOLO モードの切り替え方法

1. Agent チャットパネルを開く（Cmd/Ctrl + Shift + A）
2. パネル上部の YOLO トグルを探す
3. クリックして有効/無効を切り替える

YOLO が有効な時、トグルに小さな警告アイコンが表示されます。注意してください。

実践ワークフロー 1：ゼロから新規プロジェクトを構築する

これが Agent モードが最も輝く場面です。手動で create-react-app を実行したり、フォルダ構造を設定したり、ボイラープレートを書いたりする代わりに——Agent にすべて任せましょう。

ステップ 1： 空のディレクトリで Agent モードを開きます。

ステップ 2： 明確で詳細なプロンプトを与えます：

Create a Next.js 14 project with the following structure:
- App router with TypeScript
- Tailwind CSS for styling
- Authentication pages (login, register)
- A dashboard layout with sidebar navigation
- API routes for user management
- ESLint and Prettier configured
- Environment variables for database connection

Use PostgreSQL with Prisma ORM. Set up the basic schema for users with email, password hash, and timestamps.

ステップ 3： その作業を見守ります。Agent は以下を実行します：

1. npx create-next-app でプロジェクトを作成
2. 依存関係をインストール（Prisma、Tailwind など）
3. フォルダ構造を生成
4. 初期設定ファイルを作成
5. Prisma スキーマを設定し、初期マイグレーションを実行
6. ページコンポーネントと API ルートを作成

ステップ 4： 出力を確認します。Agent モードでも、次に進む前に作成されたものに目を通すべきです。

フォーラムからのプロのヒント

「初期スキャフォールドは必ずコミットしてから変更を加えましょう。Agent が軌道を外れたら、git checkout . でクリーンな状態に戻してやり直せます。」——Cursor Forum の @devops_mike さん

実践ワークフロー 2：自動化されたコードレビュー

別のコードレビューツールは必要ありません。Agent モードで一般的な問題をコード監査できます。

プロンプト例：

Review the src/api/ directory for:
1. Security vulnerabilities (SQL injection, XSS, missing auth checks)
2. Error handling gaps (unhandled promises, missing try-catch)
3. Performance issues (N+1 queries, missing indexes)
4. Code quality (unused imports, duplicated logic, inconsistent naming)

For each issue found, explain the problem and suggest a fix. Don't apply changes yet -- just report.

Agent はファイルを検索し、コードを分析し、構造化されたレポートを提供します。その後、どの修正を適用するかを決定できます。

さらに一歩進める

レビュー後、Agent に特定の問題を修正させられます：

Fix the SQL injection vulnerabilities you found. Apply the parameterized query pattern to all database calls in src/api/users.ts and src/api/orders.ts.

この 2 段階のアプローチ（先にレビュー、後で修正）は、Agent の速度を活かしつつ、コントロールを保つことができます。

実践ワークフロー 3：.cursorrules を使ったバッチリファクタリング

フォーラムユーザーが絶賛する強力なコンボはこれです：YOLO モード + .cursorrules。

アイデアはシンプルです——.cursorrules ファイルがプロジェクトの動作を Agent に正確に伝えるため、大規模なリファクタリングを依頼した時に、自分の規約に従ってくれます。勝手に新しい規約を作ることはありません。

ルールの設定

プロジェクトルートに .cursorrules ファイルを作成します：

## Project Conventions
- Use TypeScript strict mode
- All API responses follow the format: { success: boolean, data: T, error?: string }
- Components use named exports, not default exports
- State management uses Zustand stores in src/stores/
- All async functions must have proper error handling with try-catch
- Use the repository pattern for database operations
- Test files go in __tests__/ directories next to source files

リファクタリングの実行

YOLO モードをオンにし、良いルールを整えた状態で：

Refactor all API routes to use the repository pattern:
1. Create src/repositories/ directory
2. Extract database operations from src/api/ into repository classes
3. Update API routes to use the repositories
4. Add proper TypeScript interfaces for all repository methods
5. Create corresponding test files

YOLO + リファクタリング = 必ず先に Git を

YOLO モードでのバッチリファクタリングの前に：

1. 現在の変更をすべてコミットする
2. フィーチャーブランチを作成する
3. リファクタリングを実行する
4. git diff で差分を確認する
5. すべてが正しそうな場合のみマージする

安全第一：プロジェクトを破壊しない方法

Cursor フォーラムには恐怖の話で溢れています。以下が、被害者にならないための方法です。

Shadow Workspace を使う

Cursor の Shadow Workspace 機能は、Agent にコードのコピーで作業させることができます。問題が発生しても、実際のファイルは無傷です。

1. 設定を開く
2. Features に移動
3. Shadow Workspace を有効にする
4. Agent は分離された環境で作業するようになる

Git はあなたの安全網

当たり前のことですが、フォーラムの投稿を見ると、そうではないようです：

# 重要なコードで Agent タスクを実行する前に
git add .
git commit -m "checkpoint before agent refactoring"

# Agent が失敗した場合
git diff            # 何が変わったか確認
git checkout .      # すべてを元に戻す
# または
git reset --hard    # 最終手段

ブランチ戦略

main（本番）     -- 絶対に Agent/YOLO を実行しない
develop         -- Agent モード OK、YOLO はオフ
feature/*       -- Agent + YOLO、自由に使う

本番から離れるほど、Agent に与える自由度を高めます。フィーチャーブランチが遊び場です。Main ブランチは YOLO の禁域です。

黄金律

失う余裕がないものは、バックアップなしで Agent に触らせないでください。

バックグラウンドエージェント：AI に作業を任せて、自分は別のことをする

バックグラウンドエージェント（Cursor 0.50 で導入）は、大きなタスクにとってゲームチェンジャーです。Agent がステップバイステップで作業するのを見守る代わりに、タスクを委任して、自分は別のことをコーディングできます。

仕組み

1. Cmd/Ctrl + E でバックグラウンドエージェントパネルを開く
2. タスクを詳細に記述する
3. 「Start Agent」をクリック
4. エディタに戻って別の作業をする
5. 完了したらバックグラウンドエージェントパネルを確認する

バックグラウンドエージェントに向いているタスク

• "src/components/ 内のすべてのコンポーネントのユニットテストを作成する"
• "src/api/ 内のすべてのエンドポイントの API ドキュメントを生成する"
• "REST から GraphQL への移行マイグレーションスクリプトを作成する"
• "認証モジュールをセッションから JWT にリファクタリングする"

知っておくべきこと

• バックグラウンドエージェントはクラウド環境で動作するため、ローカルマシンを占有しません
• 複数のバックグラウンドエージェントを同時に実行できます
• エージェントが完了すると、結果がローカルプロジェクトに同期されます
• Cursor 1.1 以降、バックグラウンドエージェントの更新を Slack で受け取ることができます

フォーラムのヒント

「毎朝、自分が機能開発している間にテスト作成をバックグラウンドエージェントに任けています。昼までには、レビューできる完全なテストスイートができています。」——Cursor Forum の @testing_alex さん

クイックリファレンス：Agent モードのショートカット

アクション	ショートカット
Agent チャットを開く	Cmd/Ctrl + Shift + A
バックグラウンドエージェントを開く	Cmd/Ctrl + E
YOLO モードを切り替える	Agent パネルの YOLO トグルをクリック
Agent の変更を承認	Cmd/Ctrl + Y
Agent の変更を拒否	Cmd/Ctrl + N
Composer を開く	Cmd/Ctrl + I

避けるべきよくあるミス

1. 曖昧なプロンプト

悪い例："Fix my code" 良い例："Fix the TypeScript errors in src/utils/parser.ts. The date parsing function doesn't handle timezone offsets correctly."

2. 一度に多すぎるタスク

Agent モードは、焦点を絞った単一目的のタスクで最も効果を発揮します。「すべてをリファクタリングしてテストを追加してドキュメントを更新して」ではなく、3 つの別々の Agent セッションに分割しましょう。

3. コンテキストを提供しない

Agent はあなたのプロジェクトの歴史を知りません。どのフレームワークを使っているか、どの規約に従っているか、コードが何をするべきかを伝えてください。

4. 出力を無視する

YOLO モードがオンでも、Agent が何をしたかを確認すべきです。各 Agent セッション後の素早い git diff で、問題が蓄積される前に捉えられます。

まとめ

Agent モードと YOLO モードは、正しく使えば力の乗数になります。鍵は、Agent に自由に走らせるべき場面と、短いリードで管理すべき場面を理解することです。

小さく始めましょう。単一ファイルのタスクに Agent モードを使います。次に、複数ファイルのリファクタリングを試します。最終的に、YOLO が安全な場面とそうでない場面を直感で判断できるようになります。その直感は、どんなチュートリアルよりも価値があります。

---

情報源と参考資料：

• Cursor Forum: Agent Mode Discussion
• Cursor Forum: YOLO Mode Tips
• Shadow Workspace Documentation
• Cursor Rules Best Practices