結論: Cursor Composerは、自然言語の指示で複数ファイルをまとめて編集できるCursorのコア機能であり、Plan・Agent・Manualの3モードを使い分けることで、単純なコード補完では不可能なリファクタリングや機能追加を圧倒的に効率化できます。
この記事の要点:
- 要点1: ComposerはCmd+Shift+Iで起動し、1つの指示で10ファイル以上を同時編集できる
- 要点2: Plan Modeで事前計画→確認→実行の順番を踏むことで、大規模リファクタリングのリスクを大幅に低減できる
- 要点3: @codebase / @file / @docs / @webのコンテキスト指定が出力品質を決定的に左右する
対象読者: Cursorを使い始めた開発者・Composerを活用しきれていないエンジニア・チームでCursorを導入検討中のDX推進担当者
読了後にできること: 今日からComposerのPlan Modeを使って、安全・確実にマルチファイル編集を実行できるようになる
「Cursorって入れたけど、Tab補完しか使ってない……」
企業向けのAI研修で、こういう声をよく聞くんです。Cursorを導入したものの、実態はIntelliSense+α程度の使い方で止まっていて、「どうマルチファイル編集するの?」「PlanモードとAgentモードは何が違うの?」という疑問を抱えたまま放置されているケースが本当に多い。
実際に私自身、Cursorを本格導入して最初の2週間はComposerをほとんど使っていませんでした。「なんか怖い」「どこまで変えるか分からない」という感覚があったんですよね。でも、Plan Modeの存在を知ってからは全然違いました。事前に「こういう手順で変えます」と計画を見せてくれるので、安心してエンジニアの仕事を任せられるんです。
この記事では、Cursor Composerの3つのモードの使い分けから、@コンテキストの指定方法、マルチファイル編集のベストプラクティス、そしてBackground AgentsやGitHub Copilot Workspaceとの比較まで、コピペ可能なプロンプト例つきで全部解説します。今日からComposerを「Tab補完の次」として使い始めましょう。
まず試したい「5分即効」Composerワークフロー3選
ComposerはCmd+Shift+I(WindowsはCtrl+Shift+I)で起動します。まず3つの即効ユースケースから入ってみてください。
即効1: 関数をリネームして全ファイルに反映
研修先のエンジニアに最初に見せるのが、このケースです。「えっ、これをやってくれるの?」と全員びっくりするんですよ。関数名の変更は手動でやると修正漏れが発生するんですが、Composerに任せると一発で終わります。
@codebase
`handleUserLogin` という関数名を `authenticateUser` にリネームしてください。
呼び出し元のファイルも含めてすべて変更し、コメントや文字列の中に含まれる場合も更新してください。
変更前に「どのファイルをどう変えるか」を一覧で確認させてください。
不足している情報があれば、最初に質問してから作業を開始してください。ポイント: 最後の2行が重要です。「確認させてください」でComposerが差分を見せてから適用に移るため、意図しない変更を防げます。
即効2: 新しい環境変数を全設定ファイルに追加
@codebase
新しい環境変数 `REDIS_URL` を追加します。
以下のファイルにそれぞれ適切な形で追記してください:
- .env.example(コメントと例示値つきで)
- docker-compose.yml(environmentセクションに)
- README.md(環境変数の説明セクションに)
- 既存コードで環境変数を読み込んでいる箇所があれば、そこにも追加
変更内容を確認してから適用してください。即効3: テストファイルを一括生成
@file:src/services/UserService.ts
@file:src/services/PaymentService.ts
上記の2つのサービスに対するユニットテストファイルを作成してください。
テストフレームワーク: Jest
モックの方針: jest.mock()でdependencyをモック化
カバレッジ対象: public methodsすべて
ファイル名規則: *.test.ts(サービスファイルと同じディレクトリ)
仮定した点は必ず"仮定"と明記してください。Composerの基本的な動かし方を掴んだところで、3つのモードの詳細に入っていきます。
Cursorが持つ3大機能(Composer / Tab API / Background Agents)の位置づけについては、Cursor 3.0完全ガイドで全体像をまとめています。
Cursor Composerとは|Tab・Chatとの決定的な違い
Cursorには大きく3つのコード編集インターフェースがあります。それぞれの役割を整理しましょう。
| 機能 | 用途 | 操作範囲 | ショートカット |
|---|---|---|---|
| Tab(自動補完) | 1行〜数行の補完・修正 | カーソル付近のみ | Tab |
| Chat(Ask/Chatモード) | コードの質問・調査・説明 | 読み取り専用(編集なし) | Cmd+L |
| Composer(Agent/Manual/Normal) | 複数ファイルにわたる編集・生成 | プロジェクト全体 | Cmd+Shift+I |
ChatはAIに「聞く」ツールで、ファイルを書き換えません。Composerは「やらせる」ツールです。この区別を最初に理解するだけで、Cursorの使い方が劇的に変わります。
Composerの3つのモード詳細
| モード | 旧名称 | 特徴 | 適したシーン |
|---|---|---|---|
| Agent | Agentモード | ターミナル実行・Web検索・ファイル読み書きを自律的に実行 | 複雑な機能追加・バグ修正・テスト実行まで含む作業 |
| Manual | Composer(初期) | 1ファイルずつ変更を承認してから適用 | 精密な編集・意図しない変更を防ぎたい場合 |
| Normal | — | 全変更をDiffで提示してから一括適用 | 中程度の変更・確認してからまとめて適用 |
モードの切り替えはCmd+.(Mac)またはCtrl+.(Windows/Linux)でAgent / Ask / Manualを循環させます。
起動方法と基本ワークフロー
Composerの開き方
3つの起動方法があります。
# 方法1: キーボードショートカット(最速)
Cmd+Shift+I # Mac
Ctrl+Shift+I # Windows/Linux
# 方法2: メニューから
View > Composer
# 方法3: コマンドパレット
Cmd+Shift+P → "Open Composer" と入力基本ワークフロー(5ステップ)
Composerを使った編集の基本的な流れはこうです。
- コンテキストを指定する — @メンションで関連ファイル・ドキュメントを追加
- 指示を書く — 自然言語で「何をどう変えてほしいか」を記述
- Diffを確認する — 変更内容をレビュー(緑=追加、赤=削除)
- 適用する — 全体Apply or ファイルごとに選択して適用
- 動作確認する — ターミナルでテスト実行
正直に言うと、最初は「AIが勝手に変えて壊れないか」という不安があると思います。でも、ステップ3のDiffレビューが丁寧に設計されていて、何がどう変わるかが一目で分かるんです。慣れてくると、Diffを見ながら「ここは意図と違う」とその場で修正指示が出せるようになります。
Plan Mode|事前計画→確認→実行のワークフロー
Plan Modeは、複雑なタスクを「実行前に計画を立てて確認する」フローです。2025年10月に公式が「Introducing Plan Mode」として発表した機能で、大規模なリファクタリングや新機能追加で特に威力を発揮します。
Plan Modeの起動方法
# Agentモードの入力欄で
Shift+Tab # Plan Modeに切り替わる
# または入力欄のボタンからPlan Modeを選択Plan Modeのフロー
- タスクを入力する — 実現したいことを自然言語で記述
- CursorがCodebaseを調査する — 関連ファイルをgrepとセマンティック検索で特定
- 計画を生成する — Markdownファイルでファイルパス・変更内容・手順を一覧表示
- 計画を編集する — インラインで不要ステップを削除・追記が可能
- 承認して実行する — 計画を承認するとAgentが順番に実行
Plan Modeに適したプロンプト例
@codebase
RESTful APIのエンドポイントをGraphQLに移行してください。
対象: /api/users、/api/products、/api/orders の3エンドポイント
要件:
- Apollo Server 4.x を使用
- 既存のREST APIは互換性のために残す(移行期間中)
- TypeScriptの型定義も更新する
- テストファイルも更新する
まず実行計画を立ててください。各ファイルへの変更内容を箇条書きで確認したい。
計画を私が承認したあとに実行してください。事例区分: 想定シナリオ
以下は100社以上の研修経験をもとに構成した典型的なシナリオです。あるエンジニアチームが既存のREST APIをGraphQLに移行しようとして、最初は通常のAgentモードで実行したところ、15ファイルに変わらず6ファイルが意図と異なる変更を受けました。Plan Modeに切り替えてからは、計画の段階でエンジニアが「このファイルは触らないでいい」と3箇所修正し、実行後は1箇所の修正のみで済んだとのことです。
Plan Modeの保存機能
生成された計画はMarkdownファイルとしてリポジトリに保存できます。
# Composerが生成する計画ファイルの保存
.cursor/plans/graphql-migration-2026-05-06.mdチームで作業する場合、この計画ファイルをGitにコミットしてレビューに使うことができます。「AIが何をしようとしているか」が文書化されるので、レビュープロセスに組み込みやすいんです。
Agent Mode|自律実行の仕組みと制御方法
Agent Modeは、Composerの中で最も強力なモードです。ターミナルコマンドの実行、Webでの情報検索、ファイルの読み書き、エラーの自動修正まで、自律的に進めてくれます。
Agentが使えるツール一覧
| ツール | できること |
|---|---|
| ファイル読み書き | 任意のファイルを読んで編集・新規作成 |
| ターミナル実行 | テスト実行、ビルド、npm install等のコマンド |
| Webブラウジング | エラーの調査・最新ドキュメントの参照 |
| セマンティック検索 | @codebaseによる関連ファイルの自動探索 |
| MCP連携 | 外部ツール(Notion、Linear等)との連携 |
Agentのツール呼び出し制限
Agentは1セッションで25ツールコール(Max modeは200コール)が上限です。複雑なタスクで制限に達した場合は、タスクを分割してセッションを分けることを推奨します。
Agent Modeプロンプト例|バグの自動修正
@codebase
ユーザー登録フローでエラーが出ています。
エラーメッセージ: "TypeError: Cannot read property 'email' of undefined at validateUser"
以下の手順で対処してください:
1. エラーの発生箇所を特定する
2. 根本原因を分析する
3. 修正コードを実装する
4. ユニットテストを追加する
5. npm test を実行してすべてのテストが通ることを確認する
仮定した点は必ず"仮定"と明記してください。Agentの暴走を防ぐ設定
// .cursor/rules/safe-agent.md
# Agent実行ルール
## 必須の確認事項
- データベースのスキーマ変更は事前に確認を求めること
- 本番環境の設定ファイルは変更しないこと
- テスト以外のコマンドを実行する前に確認を求めること
## 変更禁止ファイル
- .env.production
- database/migrations/*.sql(既存のもの)
- package-lock.json(手動変更禁止).cursor/rules/ディレクトリにルールファイルを置くと、Agentは常にそのルールを参照します。「何を変えてよくて何はダメか」をあらかじめ定義しておくことが、安全なAgent活用の鍵です。
@ コンテキスト完全解説|4種類の使い方
Composerの出力品質を最も左右するのが、@コンテキストの指定方法です。正直、ここを理解するかどうかで、Composerの体験が全然変わります。
@codebase|プロジェクト全体をセマンティック検索
最も強力な@メンションです。プロジェクト全体をセマンティックインデックスで検索し、指示に関連するファイルを自動的に選んでコンテキストに含めます。
@codebase
認証周りのすべての処理を確認したい。
JWT検証のロジックはどこにあり、それがどのAPIエンドポイントで使われているか教えてください。
その後、リフレッシュトークンの有効期限を7日から30日に変更してください。注意点: @codebaseを使うと関連性の低いファイルも入ることがあります。「20ファイルで3つしか必要ない」という状況ではAIの注意が分散するので、@fileで絞り込む方が精度が高いです。
@file|特定ファイルを直接指定
@file:src/auth/AuthService.ts
@file:src/auth/jwt.utils.ts
上記のファイルを参照しながら、JWTのリフレッシュトークンロジックを改善してください。
- 現在の問題: リフレッシュ時に古いトークンが無効化されていない
- 期待する動作: リフレッシュのたびに古いトークンをブラックリストに追加する@docs|外部ドキュメントを参照
Cursor Settings > Features > Docs でURLを追加しておくと、@docsで参照できます。
@docs:React
@docs:TailwindCSS
React 18のSuspenseとTailwind CSSのgridを組み合わせたローディングUIを作成してください。
ファイル: src/components/ProductGrid/ProductGridSkeleton.tsx
不足している情報があれば、最初に質問してから作業を開始してください。@web|リアルタイムWeb検索
@web
Next.js 15 App RouterでのSSRとSSGの最適な使い分けを調べて、
現在の @file:src/app/page.tsx がどのパターンを採用すべきか提案してください。コンテキスト指定のベストプラクティス
| 状況 | 推奨コンテキスト | 理由 |
|---|---|---|
| 関連ファイルが分からない | @codebase | 自動探索で網羅 |
| 変更対象が明確 | @file(2〜5ファイル) | コンテキスト汚染を防ぐ |
| 最新APIを使いたい | @docs + @web | 学習データより新しい情報が必要 |
| 外部ライブラリの使用 | @docs | 正確なAPI呼び出しに |
Multi-File Edit ベストプラクティス10選
1. コミットしてからAgentを走らせる
研修でも毎回強調していることなんですが、Agentを走らせる前には必ずGit commitしてください。Agentの変更が意図と違っていたとき、git checkout .で一発で戻せます。
git add -A && git commit -m "before: cursor agent session $(date +%Y%m%d-%H%M)"
# この後にAgentを走らせる2. タスクを小さく分割する
# NG: 大きすぎるタスク
@codebase
このECサイト全体をTypeScriptに移行して、テストを100%カバレッジにしてください。
# OK: 小さく分割
@file:src/components/ProductCard/ProductCard.jsx
このコンポーネントをTypeScriptに移行してください。
props typeの定義とreturn typeも追加してください。3. 新しいセッションをタスクごとに開始する
長いセッションを続けると、Composerの文脈が蓄積して品質が落ちることがあります。タスクが完了したら新しいComposerセッションを開くのが鉄則です。
4. .cursor/rulesでコーディング規約を定義する
// .cursor/rules/style.md
# コーディング規約
## TypeScript
- anyは使用禁止。unknownを使うこと
- interfaceよりtypeを優先する
- 非同期処理はasync/awaitを使う(.then()チェーンは禁止)
## ファイル命名
- コンポーネント: PascalCase(例: UserProfile.tsx)
- ユーティリティ: camelCase(例: formatDate.ts)
- テスト: *.test.ts または *.spec.ts5. プロンプトに「確認してから」を入れる
変更を適用する前に、変更対象のファイル一覧と変更内容の概要を確認させてください。6. Diffを部分適用する
ComposerのDiff画面では、変更を全体適用だけでなく、ファイルごと・変更ハンクごとに適用/スキップを選べます。「このファイルの変更はOKだけど、こっちのファイルは自分で直す」という使い方ができます。
7. セマンティックインデックスを最新化する
# Cursor Settings > Codebase Indexing > Resync
# または新しいファイルを追加した後は再インデックスを実行8. Max modeはここぞという時に使う
Max modeはツールコール上限が200になる代わりにコストが高くなります。大規模なリファクタリング(10ファイル以上・複雑な依存関係)のときだけMax modeを使い、通常は標準モードで十分です。
9. エラーが出たらエラーメッセージをそのまま貼る
@codebase
以下のエラーが出ています。原因を特定して修正してください:
```
Error: ECONNREFUSED 127.0.0.1:5432
at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1148:16)
```
接続先: PostgreSQL(Dockerコンテナ)
環境: 開発環境(docker-compose)
数字と固有名詞は根拠(出典/計算式)を添えてください。10. 大きなリファクタリングはPlan Modeから始める
10ファイル以上に影響するリファクタリングは、必ずPlan Modeで計画を立ててから実行してください。計画段階で「このファイルは触らないでいい」「この手順は3番と4番を入れ替えて」と修正できるので、実行後の手戻りが圧倒的に減ります。
Diffレビューと適用|安全に変更を管理する
Diffビューの見方
ComposerがDiffを提示したとき、画面には次の情報が表示されます。
- 緑色の行: 追加されるコード
- 赤色の行: 削除されるコード
- 変更ファイル数: パネル上部に「3 files changed」のように表示
- Accept All / Reject All ボタン: 全変更の一括適用または却下
ファイルごとの選択適用
# Diffビューでの操作
Accept File # このファイルの変更だけ適用
Reject File # このファイルの変更を却下
Accept All # すべてのファイルに適用
Reject All # すべての変更を却下研修先で「ファイルごとに選べるの?」と驚かれるポイントがここです。5ファイル変えたうちの3ファイルだけ適用する、なんてことが簡単にできます。
History機能|変更履歴とチェックポイント
チェックポイントの仕組み
Composerが変更を適用するたびに、自動的にチェックポイントが作成されます。チェックポイントはローカルに保存される変更スナップショットで、Gitとは別の履歴として機能します。
# Composerの変更を元に戻す手順
1. Composerパネル右上の「History」をクリック
2. 戻りたいチェックポイントを選択
3. 「Restore to checkpoint」をクリックチェックポイントとGitの使い分け
| 機能 | チェックポイント | Git |
|---|---|---|
| 保存場所 | ローカルのみ(隠しディレクトリ) | リポジトリ(チーム共有可) |
| 対象 | AIが変更したファイルのみ | すべての変更 |
| 用途 | Agentセッション内のUNDO | 永続的なバージョン管理 |
| 共有 | 不可 | 可(push後) |
重要: チェックポイントはGitの代替ではありません。手動での編集はチェックポイントに記録されないため、Gitと組み合わせて使うことを強く推奨します。
Background Agentsとの連携|使い分けの基準
Cursor Background Agentsは、クラウドVM上で非同期実行される別機能です。ComposerのAgentモードとは明確に用途が異なります。
| 比較項目 | Composer Agent | Background Agents |
|---|---|---|
| 実行環境 | ローカルマシン | クラウドVM(隔離環境) |
| 実行スタイル | 対話型(リアルタイム確認) | 非同期(バックグラウンド) |
| Git管理 | 手動commit | 自動的に別ブランチ作成 |
| 適したシーン | 積極的に操縦したい作業 | 明確な仕様が決まった自動化 |
| コスト | モデルコストのみ | VM時間コスト追加あり |
使い分けの基準: 「今、自分がアクティブに操作したい」ならComposer Agent。「仕様を渡して後で結果を受け取ればいい」ならBackground Agents。
Background Agentsの詳細な使い方はCursor Background Agents完全ガイドを参照してください。
GitHub Copilot Workspaceとの比較
GitHubが2024年に発表したCopilot Workspaceも、マルチファイル編集エージェントとして注目されています。2026年時点の主要な差異はこうです。
| 比較項目 | Cursor Composer | GitHub Copilot Workspace |
|---|---|---|
| 起動方法 | IDE内でCmd+Shift+I | GitHub Issueから起動 |
| コンテキスト | プロジェクト全体をセマンティックインデックス化 | アクティブワークスペース+明示的添付 |
| ターミナル実行 | あり(Agent mode) | あり(テスト・ビルド) |
| PR連携 | 手動(Git操作) | ネイティブ統合(PRを自動作成) |
| 並列実行 | Background Agentsで対応 | 単一エージェント |
| モデル選択 | GPT-5.4 / Claude Opus 4.6 / Gemini 3 Pro等 | GitHub公式モデルセット |
どちらを選ぶか: GitHub Actionsやissueドリブン開発を中心にしているチームはCopilot Workspaceが馴染みやすい。IDE中心・モデル選択の自由度を重視するならCursorが強い。
Claude Code Edit(Edit機能)との比較
Claude Codeにも複数ファイルを編集する機能があります。Cursor ComposerとClaude Code Editの違いをまとめます。
| 比較項目 | Cursor Composer | Claude Code Edit |
|---|---|---|
| インターフェース | IDE統合(VS Codeベース) | ターミナル・CLI優先 |
| Diff表示 | グラフィカルDiffビュー | ターミナル上のテキストDiff |
| トークン効率 | 標準 | 同等タスクで約5.5倍少ないトークン(公開ベンチマーク比) |
| Plan相当機能 | Plan Mode(Shift+Tab) | TodoWrite + 思考モード |
| 適したスタイル | GUI好みの開発者 | ターミナル操作が得意な開発者 |
「どちらかを選ばなければいけない」ではなく、多くの開発者は両方を使い分けています。IDE作業中はComposer、ターミナルベースの自動化はClaude Codeという分け方が自然です。
Claude Codeとの詳細な比較はAI導入戦略完全ガイドでも触れています。
実用Composerワークフロー10選
1. 新機能追加(Plan Mode使用)
@codebase
ユーザープロフィール編集機能を追加してください。
要件:
- エンドポイント: PUT /api/users/:id/profile
- 変更可能フィールド: name, bio, avatarUrl
- バリデーション: nameは1-50文字、bioは0-200文字
- 既存のAuthMiddlewareを使って認証を必須にする
Plan Modeで事前計画を立ててから実行してください。
不足している情報があれば、最初に質問してから作業を開始してください。2. コードレビューコメントの一括対応
@file:src/services/OrderService.ts
PRレビューでもらったコメントを反映してください:
1. 行45: エラーハンドリングが不十分。try-catchを追加して適切なエラーメッセージを返すこと
2. 行78: N+1クエリ問題。ユーザー情報をまとめて取得するように変更
3. 行102: マジックナンバーを定数化すること(30 → MAX_RETRY_COUNT)
仮定した点は必ず"仮定"と明記してください。3. ライブラリのバージョンアップ対応
@codebase
@web
React Router v5からv6へのマイグレーションを行ってください。
変更が必要な可能性があるファイルを探し、v6の新しいAPIに合わせて書き換えてください。
主な変更点:
- Switch → Routes
- Redirect → Navigate
- useHistory → useNavigate
- exact prop → 不要に
まず影響を受けるファイル一覧を確認させてください。4. 環境別設定ファイルの整合性チェック
@file:.env.example
@file:.env.staging
@file:.env.production.template
3つの設定ファイルを比較し、.env.exampleにあるがstagingやproductionにない変数を一覧で表示してください。
不足している変数には適切なデフォルト値または説明コメントを追加してください。5. ドキュメントの自動更新
@file:src/api/UserController.ts
@file:docs/api/users.md
UserControllerに追加した新しいエンドポイントに合わせて、
docs/api/users.mdのOpenAPI形式のドキュメントを更新してください。
既存のフォーマットに合わせて記述してください。6. データベースマイグレーション生成
@file:src/models/User.ts
@file:database/schema.sql
User modelに avatarUrl カラムを追加します。
以下を作成してください:
1. database/migrations/20260506_add_avatar_url_to_users.sql
2. TypeScriptモデルの型定義を更新
3. 既存のUserServiceへの影響を確認して必要な修正を実施
数字と固有名詞は根拠(出典/計算式)を添えてください。7. テストのリファクタリング
@codebase
test/ ディレクトリ内のテストファイルを確認し、以下の問題を修正してください:
1. describe/itのネストが3階層以上のものを整理
2. beforeEach/afterEachの重複を共通ファイルに切り出す
3. テスト名が日本語になっていないものを翻訳(英語名のみのものを対象)
まず問題のあるファイルをリストアップしてから修正を開始してください。8. セキュリティ脆弱性の修正
@codebase
npm audit の結果で高リスクと評価された脆弱性を修正してください。
以下の条件で:
- High・Critical severity のもののみ対応
- breaking changeを伴うアップグレードは事前に確認を求めること
- package.jsonとpackage-lock.jsonの両方を更新
修正後、npm audit を実行してCleanになっていることを確認してください。9. アクセシビリティの改善
@file:src/components/Form/ContactForm.tsx
このフォームコンポーネントのアクセシビリティを改善してください:
- すべての入力フィールドにaria-labelまたはhtmlForとlabelを追加
- エラーメッセージをaria-live regionで通知
- キーボードナビゲーションの順序を確認・修正
- フォーカス時のスタイルを明示的に追加(outline-noneを外す)10. CI/CDパイプラインのセットアップ
@codebase
@docs:GitHub Actions
このプロジェクトに GitHub Actions の CI パイプラインを追加してください。
要件:
- mainへのPRで自動実行
- ステップ: lint → typecheck → test → build
- Node.js 20.x でテスト
- テスト失敗時にPRにコメントを投稿
ファイル: .github/workflows/ci.yml
不足している情報があれば、最初に質問してから作業を開始してください。【要注意】Composerでよくある失敗パターン4選
失敗1: コンテキストなしで「全部やって」と指示する
❌「このプロジェクトのコードをきれいにしてください」
⭕「@codebase TypeScriptのanyを使っているファイルを特定し、適切な型定義に修正してください。まず対象ファイル一覧を確認させてください」
なぜ重要か: コンテキストがないとComposerはコードベース全体を推測で変更しようとします。研修先でこの失敗をしたエンジニアが、50ファイルを一気に書き換えられて3時間かけて元に戻した、という事例を見ています。@codebaseかファイル指定は必須です。
失敗2: コミットせずにAgentを走らせる
❌ Gitが綺麗な状態でないまま大規模変更をAgentに依頼
⭕ git add -A && git commit -m "before agent"してからAgent起動
なぜ重要か: Agent Modeは自律的に複数ファイルを変更します。意図と違う変更があっても、コミットがあればgit checkout .で戻せます。コミットなしで進めて「どこが変わったか分からなくなった」というケースが本当に多いです。
失敗3: 1つのセッションで複数の無関係なタスクを処理する
❌ 1つのComposerセッションで「バグ修正→ドキュメント更新→新機能追加」を連続して依頼
⭕ タスクごとに新しいComposerセッションを開く(Cmd+Shift+Iで新規)
なぜ重要か: セッションが長くなると前の変更内容が文脈に混入し、意図しない変更が増えます。タスクが完了したら必ず新しいセッションを開いてください。
失敗4: Plan Modeを使わずに大規模リファクタリングをAgentに任せる
❌ 「@codebase 全部のクラスコンポーネントをfunctionコンポーネントに変換して」
⭕ Plan Modeで計画を立てて、変更対象ファイルを確認→承認→実行
なぜ重要か: 大規模なリファクタリングは影響範囲が読めません。Plan Modeで「このファイルとこのファイルを変えます」という計画を先に見ることで、「このファイルは今触らないでいい」という修正ができます。Agentにいきなり任せると、予想外のファイルまで変更されることがあります。
Cursor Composerのモデル設定|最適なモデルの選び方
Composerで使うAIモデルは、Cursor Settings > Models から変更できます。2026年5月時点で利用可能な主要モデルと推奨ユースケースを整理します。
| モデル | 特徴 | ComposerでのUseCase |
|---|---|---|
| Claude Opus 4.6 / Sonnet 4.6 | 高品質・長文コンテキスト | Plan Mode・複雑なリファクタリング |
| GPT-5.4 | バランス型 | 通常のマルチファイル編集 |
| Gemini 3 Pro | 大規模コンテキスト(100万トークン) | 大規模コードベース・大量ファイル参照 |
| Cursor Fast | 軽量・低レイテンシ | Tab補完・簡単なInline Edit |
コスト最適化のヒント: Tab補完はCursor FastやHaiku系の軽量モデルに設定し、ComposerのPlan Mode・Agentはより能力の高いモデルを使う、という組み合わせが経済的です。
参考・出典
- Introducing Plan Mode — Cursor公式ブログ(参照日: 2026-05-06)
- Best practices for coding with agents — Cursor公式ブログ(参照日: 2026-05-06)
- Cursor 2.0 Expands Composer Capabilities for Context-Aware Development — InfoQ(参照日: 2026-05-06)
- Cursor Agent Mode: How It Works, Tips & Pricing — morphllm.com(参照日: 2026-05-06)
- Understanding Cursor Checkpoints for Safe AI Edits — Steve Kinney(参照日: 2026-05-06)
- Context Management Strategies for Cursor — DataLakehouseHub(参照日: 2026-05-06)
まとめ:今日から始める3つのアクション
- 今日やること:
Cmd+Shift+IでComposerを開き、@codebaseを使って「このプロジェクトで最も複雑なファイルはどれですか?説明してください」と入力してみる。Composerのコンテキスト理解力を実感できます - 今週中: 次の機能追加やバグ修正を、Plan Mode(Shift+Tab)で計画を立ててから実行してみる。計画を見ながら「ここは修正しよう」を経験することで、Plan Modeの価値が体感できます
- 今月中:
.cursor/rules/にコーディング規約ファイルを追加し、Composerが常にプロジェクトのルールを守るように設定する。チーム開発での一貫性が格段に向上します
あわせて読みたい:
- Cursor Background Agents完全ガイド2026|並列実行とコスト — Composerと組み合わせるクラウドAgent活用法
- Cursor Tab API完全ガイド2026|オートコンプリート・カスタムモデル統合 — Tab補完とComposerの最適なモデル設定
著者: 佐藤傑(さとう・すぐる)
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X(旧Twitter)で活用法を発信(@SuguruKun_ai、フォロワー約10万人)。100社以上の企業向けAI研修・導入支援を展開。著書『AIエージェント仕事術』(SBクリエイティブ)。SoftBank IT連載7回執筆(NewsPicks最大1,125ピックス)。
ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。




