Cursor Composerの使い方とAgentモード入門

CursorのComposerは、機能名としての編集ワークフローと、独自モデルとしての「Composer」が同じ名前で語られがちです。
ここを分けて理解すると、Chatとの役割分担がより明確になります。
この記事は、VS Code 感覚のまま複数ファイル編集や自走型の実装を取り入れたい開発者向けに、具体的な操作（⌘I で起動、⌘N で新規 Composer、⌘. で Agent 有効化）から、差分レビュー・Accept／Apply、Checkpoint を使った巻き戻しまで、迷わず再現できる手順として整理します。

私自身、既存のReactプロジェクトでボタン追加からテスト生成、失敗したらCheckpointへ戻すところまで一連で試したとき、ショートカット中心で1タスクごとにComposerを切る運用がいちばん崩れませんでした。
Cursor 2.0 と Composer のご紹介で示された高速化や30秒未満の応答、多エージェント化、さらにAgent Best Practicesが勧めるレビュー前提の運用を踏まえつつ、通常モードとAgentモードで何ができて何ができないのか、安全な判断軸まで含めて解説します。

Cursor Composerとは何か

Composer（機能）とComposerモデルの違い

Cursorでいう Composer は、まず複数ファイルをまたいだ実装や編集をまとめて進めるための作業空間です。
VS Codeベースの画面に近い感覚で使えますが、役割は単なるチャット欄ではなく、「関連ファイルを集めて、差分を出し、レビューして適用する場所」にあります。
たとえば React アプリのボタン追加なら、Button.tsx だけでなく、呼び出し元の画面、スタイル、テストまで一気につなげて扱えるのが Composer の強みです。

ここで紛らわしいのが、Cursor 2.0 以降は Composer が機能名でもあり、独自モデル名でもある 点です。
記事内では、前者を「Composer（機能）」、後者を「Composerモデル」と分けて読むと混乱しません。
Composerモデルについて「同等知能帯のモデル比で4倍高速」で、「多くの対話が30秒未満で終わる」と公式が説明しています。
ただし、これはあくまで公式の説明として受け取るべきで、実際の体感や得意不得意まで断定して読むものではありません。

実際の入り方はシンプルです。
Cursor をインストール済みの状態で対象フォルダを開き、⌘I（Windows は Ctrl+I）で Composer を起動します。
既存セッションに続けず、新しい作業として切りたいときは ⌘N で新規 Composer を作成します。
機能追加、リファクタ、テスト追加のように「変更対象が1ファイルで閉じない」作業は、この時点で Composer に入れたほうが流れが安定します。

関連ファイルの渡し方も、最初に押さえておくと迷いません。
Composer ではエディタで開いているファイルを前提に話を始めるだけでなく、必要なファイルを明示してコンテキストに入れられます。
画面上でファイルを選んで追加する方法でもよいですし、プロンプト内で src/components/Button.tsx、src/pages/Home.tsx、src/components/Button.test.tsx のように具体的なパスを書いて「この3つを見て変更して」と伝えると、意図がぶれません。
Agent を ⌘. で有効化すると、『Composer Overview』 にある通り、コードベースから関連コンテキストを引き込みながら進められます。

最初の一回は、小さめの依頼文が合っています。
たとえば「src/pages/Home.tsx に送信ボタンを追加し、既存の Button.tsx を再利用してください。
必要ならテストも追加し、変更理由を簡潔に示してください」のように、対象ファイル、目的、再利用条件、テスト有無を一文にまとめると、無駄な往復が減ります。
実装が出たら、そのまま即保存ではなく差分ビューで変更内容を見ます。
Composer では Accept、Accept All、Reject などの表記で承認できる場面があり、記事やUIでは Apply と表現されることもあります。
流れとしては「差分確認して、問題なければ Accept／Apply で反映する」と覚えておけば足ります。

このレビュー前提の運用は、実際に触ると意味がよくわかります。
複数ファイルを一度に書き換えるぶん、思わぬ import の消し忘れやテストの更新漏れも同時に出るからです。
私も最初は一気に反映していましたが、Diff を一塊ずつ見てから受け入れる形に変えてから、戻し作業が減りました。
途中で意図と違う方向へ進んだ場合は、Composer の Checkpoint から直前の状態へ戻せます。
長いセッションで修正が連鎖したときほど、この巻き戻しが効きます。

Cursor 2.0 と Composer のご紹介 · Cursor

どちらもエージェントとの連携に特化して設計された、新しいインターフェースと初のコーディングモデル。

cursor.com

Chatとの役割分担

Cursorの Chat は、コードの意味を聞く、方針を相談する、設計案を比較するといった理解と対話の場として見ると噛み合います。
対して Composer は、相談で固めた方針をもとに実際にコードへ差分を出す場です。
どちらも AI と話す点は同じですが、中心にある行為が違います。
Chat では「この hooks 構成で副作用が暴れないか」「フォーム送信をどのレイヤーに置くべきか」といった整理に向き、Composer では「ではその方針で関連ファイルを直して」と進めるほうが自然です。

この切り分けは、最初の一回から使えます。
対象フォルダを開いたら、いきなり Composer で大きく投げるより、先に Chat で「この機能追加ならどのファイルが触れそうか」「既存コンポーネントを再利用するならどこを見るべきか」と整理し、その答えを持って Composer に移る流れのほうが道筋がぶれません。
私はこの二段構えにしてから、長い対話の途中で論点が増え続ける状態を避けやすくなりました。
Chat で地図を描き、Composer で工事する感覚です。

たとえば、既存の React プロジェクトで「一覧画面にフィルタ UI を追加したい」とします。
Chat では「状態管理はローカル state で足りるか」「URL クエリに持たせるべきか」を相談し、触る候補として ListPage.tsx、FilterBar.tsx、テストファイルを洗い出します。
そのあと Composer を ⌘I で開き、新規 Composer を ⌘N で切って、関連ファイルを指定したうえで実装依頼を出します。
ここで Agent を有効化しておくと、関連コードの探索や必要な修正範囲の見立てまで含めて進められます。

最初のプロンプトも、Chat と Composer では書き方が変わります。
Chat なら「この設計の懸念点を挙げて」と聞くのが合いますが、Composer では「src/pages/ListPage.tsx と src/components/FilterBar.tsx を見て、カテゴリ絞り込み UI を追加してください。
既存スタイルに合わせ、テストも更新してください」のように、変更対象と完成条件を明示したほうが結果が安定します。
差分が出たら内容を確認し、問題ない部分だけ Accept、まとめて反映したいなら Accept All 寄りで受ける、という順番です。
もし修正の広がり方が怪しいと感じたら、その時点で Checkpoint に戻して、依頼文を短く切り直したほうが立て直しが早く済みます。

よくある誤解のひとつが、「Composer は高性能なチャット欄の名前」という捉え方です。
実際には Composer（機能）は複数ファイル編集のための専用ワークスペースであり、Chat の延長というより作業モードに近い存在です。
もうひとつの誤解は、「Agent を有効にすれば自動で全部正しく終わる」という見方で、これは期待しすぎです。
Agent は便利な支援を提供しますが、差分は必ず人がレビューする前提で運用してください。

用語を整理すると、読みにくさが減ります。
Composer（機能）は編集の場、Composerモデルは Cursor 2.0 で導入されたモデル名、Chatは理解や相談の場、Agentは Composer 内で自律度を上げる実行モード、という分け方です。
この4つを混同すると、「Chat でも同じように複数ファイルをまとめて直してくれるのでは」「Composerモデルを選べば自動で Composer になるのでは」といったズレが出ます。
名前が重なっているせいで起きる混乱なので、ここは最初に線を引いておく価値があります。

操作まわりでも、誤解が出やすいポイントがあります。
⌘I は Composer を開く操作、⌘N は新規 Composer を作る操作、⌘. は Agent を有効化する操作です。
これらは全部別です。
対象フォルダを開かずに始めると、コードベース全体を前提にした提案になりませんし、関連ファイルを指定せずに大きな依頼だけ投げると、触ってほしい場所とずれた差分が出やすくなります。
最初の実行では、対象フォルダを開く、新規 Composer を切る、関連ファイルを入れる、短い依頼を出す、差分を見る、Accept／Apply する、必要なら Checkpoint で戻す、という一連の流れを一度そのまま通すと、各用語が操作と結びつきます。

長いセッションほど精度が上がると思われがちですが、実務では逆の場面も出ます。
会話が伸びるほどコンテキストが膨らみ、もともとの依頼から外れた前提を引きずることがあるためです。
だからこそ、1タスクごとに新規 Composer を切る運用が効きます。
機能追加を一回、テスト修正を一回、リファクタを一回という単位で分けると、差分の意味が追いやすく、Checkpoint で戻す位置も明確になります。
これは使ってみると地味ですが効く整理法です。

ComposerとAgentモードの違い

ショートカットとUIの基本

Cursorの『Composer』は、複数ファイルにまたがる実装を進めるための作業スペースです。
起点になる操作はシンプルで、Composerを開くショートカットは ⌘I（Windowsは Ctrl+I）、新しいComposerを切る操作は ⌘N（Windowsは Ctrl+N）です。
ここまでは通常モードでもAgentモードでも共通で、まずComposerを開いてから何をどこまで任せるかを決める流れになります。
起動方法や。

実際に触ってみると、CursorはVS Codeベースのため、画面の感覚が大きく外れません。
エディタ中央でコードを見ながら、横や下にComposerを開いて依頼を書き、出てきた差分を確認して受け入れる、という流れです。
Chatが「相談しながら考える場」だとすると、Composerは「変更候補を並べて、反映まで持っていく場」と捉えると混乱しません。

ここで押さえたいのは、AgentはComposerの別製品ではなく、Composer内で切り替える実行モードだという点です。
Agentの有効化は ⌘.（Windowsは Ctrl+.）で行います。
通常モードのままなら、依頼に対して主にコード変更案や差分提案が返ってきて、それを人が見て適用します。
つまり基本の形は提案→人が適用です。
この段階でも十分に便利ですが、実装の前後で調査やコマンド実行が必要になるタスクでは、次のH3で触れるAgentモードのほうが役割が広がります。

Agentモードで変わること

AgentをONにした瞬間に変わるのは、AIが「コードを書く相手」から「作業を進める実行者」に近づくことです。
通常モードでは、依頼文と渡されたコンテキストをもとに差分を作るのが中心です。
一方でAgentモードでは、関連ファイルを探しにいき、必要なコンテキストを自動で集め、ツールを使い、ターミナルでコマンドを実行しながら進められます。
Cursor MCPドキュメントでも、Composer AgentがMCPのAvailable Toolsを自動利用する前提が説明されています。

この違いは、たとえば「テストが落ちているので直したい」という依頼でよく出ます。
通常モードだと、まず関連ファイルを人が示し、修正案を受け取り、その後に自分でテストを回して結果を見ることになります。
Agentモードでは、その一連の流れをまとめて進めやすくなります。
実際に使ってみると、テストが落ちたあとにエラー内容を読んで修正案を出し、追加でテスト実行まで進む場面がありました。
ただ、その時点で安心して任せ切るのではなく、修正の意図と影響範囲を人が見直す工程は外せません。
Agentが前に進める量は増えますが、最終判断まで自動化されるわけではない、という感覚です。

また、AgentはMCP経由の外部ツールも使えます。
MCPはAIツールが外部サービスや独自ツールとつながるための共通規格で、設定済みのサーバーがAvailable Toolsとして見えていれば、Agentが必要に応じてそれを呼び出します。
コードベース内の編集だけで終わらず、周辺の情報取得や補助処理まで含めて進められるのが、通常モードとの大きな差です。

できること/できないことの境界

Agentモードでできることは、単なるコード生成より広いです。
代表的なのは、関連ファイルの探索、複数ファイルにまたがる差分提案、テスト実行、そしてMCPのAvailable Toolsの利用です。
たとえばルーティング定義、コンポーネント、型定義、テストコードが別々の場所にあるプロジェクトでも、Agentは必要な箇所を拾いながら変更候補を組み立てられます。
こうした作業は、人が毎回ファイルを指定する通常モードよりも一歩先まで進みます。

一方で、できないことの線引きも明確です。
まず、無制限に長時間自走する仕組みではありません。
Composer 。
つまり、延々と調べ続けて全部を完了させるタイプではなく、一定回数の中で調査・編集・実行を組み合わせる形です。
長い会話ほど文脈が膨らみ、途中から狙いがずれることがあるのも、実務では意識しておきたいところです。

もうひとつの境界は、プロジェクト固有の規約や暗黙知を自動で守り切る保証がないことです。
たとえば命名規則、レビュー文化、テストの粒度、既存設計の優先順位のようなチーム固有ルールは、Rulesやプロンプトで寄せることはできても、毎回期待通りに揃うとは限りません。
さらに、意図していないファイルへの編集を100%防ぐことはできません。
だからこそ、Agentが出した差分はDiffで確認し、Accept / Apply 相当の操作に進む前に内容を見る、という前のセクションで触れた流れがそのまま効いてきます。

並列エージェントと実行制御

Cursor 2.0では、複数エージェントを並列で動かす新しいUIが紹介されました。
最新情報としては、最大8つのエージェントを同時に走らせる構成が解説されています。
たとえば、1つは実装、1つはテスト修正、1つは関連箇所の調査、という分担を切るイメージです。
単純な1往復のチャットではなく、作業単位でAIを並べる発想に近いです。

ここで見えてくるのは、Agentモードの本質が「自動実行」だけではなく「実行をどう区切るか」にあることです。
エージェントの数を増やせば万能になるわけではなく、依頼の粒度が粗いままだと、複数のAgentが広い範囲を触って収拾がつきにくくなります。
実際には、1Composerに1タスクを保ちつつ、必要なら別Composerや並列エージェントに役割を分けるほうが運用しやすいと感じます。
実装担当と調査担当を分離すると、差分レビューの観点もはっきりします。

加えて、Agentには回数の上限があるので、実行制御は「どこまでを1回でやらせるか」の設計でもあります。
テスト実行、ログ確認、修正、再実行までを1本にまとめるのか、修正と検証を分けるのかで、結果の安定感が変わります。
Cursor 2.0 と Composer のご紹介で示されている並列実行の方向性は魅力的ですが、実務ではタスクを小さく切って、各Agentの責務を明確にしたほうが差分の意味を追いやすくなります。
Composerの通常モードとAgentモードの違いは、機能の多さだけではなく、この「どこまで自律的に進めさせるか」を操作できる点にあります。

Cursor Composerの始め方

プロジェクト準備とComposer起動

前提は、すでにCursorをインストール済みであることです。
履歴が残っている状態なら、AIが触った変更と自分の手作業を切り分けて追えますし、あとで戻す判断も速くなります。

まずCursorで対象フォルダを開きます。
プロジェクトルートが開けたら、Composerを ⌘I / Ctrl+I で起動し、そのまま新しいComposerを ⌘N / Ctrl+N で作成します。
この順番にしておくと、既存の会話に続けて投げてしまう事故を避けやすく、1つのComposerに1タスクという形を保ちやすくなります。
小修正でも新規Composerを切っておくと、差分の意図があとから追いやすくなります。

この時点で、編集前のGitコミットを1つ置いておくと扱いが安定します。
CursorのCheckpointだけでも戻せますが、Gitのコミットがあると「AIに触らせる前の状態」と「AIの提案を受け入れた後の状態」を別レイヤーで管理できます。
複数ファイルにまたがる変更ほど、この二段構えが効いてきます。

筆者の体験では、エラーログを貼って Agent を有効にすると原因箇所の当たりが早く、短めの修正では応答の待ち時間が比較的短く感じる場面がありました。
ただし、応答時間や体感はタスク内容や環境に依存します。

コンテキスト指定と最初のプロンプト例

（注: 本記事内での応答時間や速度感に関する記述は筆者の体感や公式発表の引用を含み、環境やタスクにより変動します。
実運用では条件に応じて変わる点にご留意ください。
）

Composerの精度は、最初の指示文そのものより、何を文脈として渡したかで変わります。
関連ファイルの指定方法は主に2つあります。
ひとつはComposer内のContext Pillsから、対象ファイルやフォルダを追加する方法です。
もうひとつは、エディタで開いているファイルを参照として含める方法です。
前者は複数ファイルにまたがる作業向きで、後者は今見ている実装を起点に直したいときに向いています。

たとえば、src/components/Header.tsx だけを直したいのに、src ディレクトリ全体を渡すと、Agentが周辺まで触りに行く余地が増えます。
逆に、ルーティング・画面・型・テストが散らばっている機能追加では、関係するフォルダをまとめて入れておいたほうが筋の通った差分になりやすいのが利点です。
コンテキストは「広く入れる」より「変更の理由がつながる範囲を入れる」と考えるとぶれません。

最初のプロンプトは、粒度をそろえて書くと結果が安定します。次のような形から始めると、Composerの挙動を把握しやすくなります。

1. 小修正の例

「Header.tsx のボタン文言を ログイン から サインイン に変更し、既存のスタイルは崩さずに関連テストも必要なら更新してください」

1. 複数ファイル変更の例

「ユーザー一覧画面に status フィルタを追加してください。
対象は一覧コンポーネント、検索条件の型定義、API呼び出し部分です。
既存の命名規則に合わせて差分を出してください」

1. テスト生成の例

「formatDate 関数の現在の実装を読んで、主要ケースをカバーするユニットテストを作成してください。
既存テストフレームワークに合わせ、実装変更が必要なら分けて提案してください」

1. エラーログ調査の例

「このエラーログを基に原因箇所を特定し、最小限の修正案を出してください。修正後に関連テストがあれば更新案も含めてください。ログ: ...」

Cursor 2.0 と Composer のご紹介では、Composerモデルについて「同等知能帯と比べ4倍高速」「多くの対話が30秒未満で完了する」といった性能表現が記載されています（公式発表、参照: 2026-03-18）。
これらは公式の説明であり、実際の応答時間や体感はプロジェクトやタスクによって変わるため、断定的に扱わないよう注意してください。

（参考）Cursor 2.0 と Composer のご紹介の記述では、Composerモデルについて公式に「同等知能帯と比べ4倍高速」「多くの対話が30秒未満で完了する」と説明されています。
これらは公式の主張であり、実際の応答時間や体感はプロジェクトやタスク、環境によって変動する可能性があることに注意してください。

Composerは、返答文を読むだけで終わらせず、提案されたDiffを見るところまでが1セットです。
変更対象が1ファイルでも、関数名の変更が別ファイルの参照切れを生んでいないか、テスト追加が既存方針から外れていないかを見ます。
通常のコードレビューと同じで、「何を変えたか」より「なぜこの変更で直るのか」を読みにいく感覚が合っています。

適用操作のラベルは、現行UIで Accept と表示される場面と、文脈によって Apply と書かれている解説が混在しています。
実際の画面では Accept、Accept All、Reject、Reapply などの表記が見られる一方、コードブロック側で Apply を経由する説明もあります。
ここは記事やUI世代で揺れがあるため、手元のCursorでは差分プレビュー後のボタン名をそのまま読むのが確実です。
操作の意味としては、提案差分をレビューして受け入れる流れで捉えておけば迷いません。

レビューでは、次の3点を見ると判断が速くなります。
変更が依頼範囲の中に収まっているか、既存のコーディング規約に沿っているか、そしてテストや実行確認まで筋が通っているかです。
Agentが自走してくれたとしても、意図しないリネームや無関係ファイルの整形が混ざることがあります。
Diffでそこを拾えるのがCursorの強みで、CLI中心のClaude Codeとは違って、IDE上で前後比較しながら採否を決められます。

差分を受け入れたあとは、そのまま終わらせず、テスト実行やアプリ起動までつなげます。
ユニットテストがあるなら回し、フロントエンドなら該当画面を開いて手元で挙動を見ます。
Composerがコードを作る段階と、実際に動くかどうかは別の確認です。
ここまで通して、最初の1タスクが完了します。

Checkpointとロールバック

Composerを試すときは、Checkpointを「保険」ではなく「作業の区切り」として使うと扱いやすくなります。
小さな修正を始める前、複数ファイル変更に入る前、Agentでエラーログ調査を走らせる前のように、節目でCheckpointを切っておくと、戻したい単位が明確になります。

操作としては、Composerの実行前後でCheckpointを作り、もし提案が期待と違ったら、そのCheckpointからロールバックします。
実務では、いったんAcceptしたあとに「あの変更だけ外したい」と思う場面があり、このときCheckpointがあると会話履歴をたどって手で戻すよりずっと速いです。
私自身、エラーログを貼ってAgentに調査させ、原因箇所の修正Diffを見て一度は適用し、挙動が気に入らなければCheckpointから巻き戻す、という往復を短時間で何度も回しました。
修正、確認、破棄のサイクルが軽いので、最初の仮説が外れても作業が止まりません。

Checkpointだけに頼らず、適用前後でGitコミットも挟むと履歴が整理されます。
たとえば、適用前に「baseline」、Accept後に「composer-fix-login-error」のように分けておけば、あとでGitの履歴から意図を追えます。
CheckpointはCursorの中で戻るための手段、Gitコミットはプロジェクト全体の履歴を管理する手段として分けておくと、復旧の判断がぶれません。

つまずきやすいポイント

最初につまずきやすいのは、1つのComposerに依頼を詰め込みすぎることです。
「バグ修正、設計整理、テスト追加、README更新」まで一気に頼むと、差分の評価軸が混ざります。
まずは1タスク1Composerに切り、修正対象と完了条件を短く書くほうが、出てきた変更の良し悪しを判断しやすくなります。

次に起きやすいのが、関連ファイルを渡していないのに「思った通りに直らない」と感じるケースです。
たとえばReactの画面だけ開いていて、実際のバリデーションが zod のスキーマ定義やサーバー側APIにあるなら、そこをContext Pillsで含めないと、表面だけ整えた差分になりがちです。
逆に、フォルダごと広く渡しすぎると、Agentが余計な場所まで読みに行きます。
症状がある層と、その原因がありそうな層をセットで渡すくらいがちょうどいいです。

Agentの進捗表示を見ずに放置するのも、最初に起きやすい失敗です。
ツール実行が進むと、どのファイルを探し、何を読んでいるかが見えます。
ここで意図と違う方向に進み始めたら、停止してプロンプトを切り直したほうが、広がった差分をあとで片付けるより早く済みます。
Agentは前に進む力があるぶん、ズレたまま数手進むと修正コストが増えます。

日本語化して使っている場合は、メニュー類は日本語でも、ComposerやAgentまわりの一部ラベルが英語のまま残ることがあります。
チームで手順共有するときに、ある人の画面は「新しいComposer」、別の人の画面は New Composer のように見え方がずれるので、操作説明はラベル名だけでなくショートカットも併記したほうが混乱が減ります。

もうひとつ見落としやすいのが、Acceptした時点で終わった気になってしまうことです。
Composerの役目は差分提案までで、完成判定はテストや実行結果で行います。
最初の1回は、対象フォルダを開く、Composerを起動する、新規Composerを作る、関連ファイルを入れる、短いプロンプトを投げる、Diffを見る、AcceptまたはApply相当の操作で反映する、CheckpointやGitで戻せる状態を保つ、という流れを一通り通すと、次のタスクから迷いが減ります。

基本的な使い方4パターン

単一機能追加

CursorのComposerを最初に仕事で試すなら、単一機能追加がいちばん感覚をつかみやすいのが利点です。
たとえば「ボタンを1つ足す」「入力欄のバリデーション関数を追加する」「一覧に並び替えトグルを置く」といった、変更点が目で追えるタスクです。
狙いは、Agentに任せる範囲を小さく保ちつつ、受け入れ条件を先に固定することです。
ここが曖昧だと、動いてはいるけれど欲しかった実装ではない差分が返ってきます。

私がよく書くのは、変更対象、触ってよいファイル、完了条件をひとまとめにした短い依頼です。
Composerは短い依頼でも複数ファイルにまたがって補完しようとするので、「何を足すか」だけでなく「どこまでで止めるか」も明記したほうが、Diffの読み味が安定します。
Composer Overviewでも、Composerは複数ファイル編集を前提にした導線になっていますが、最初はその力をあえて絞ったほうが狙い通りに進みます。
Composer Overviewは で確認できます。

具体例はこうです。

設定画面のプロフィール欄に「表示名をリセット」ボタンを追加してください。
対象は src/pages/settings/Profile.tsx のみ。必要なら既存の hooks は利用可、新規ライブラリ追加は禁止。
受け入れ条件:

- ボタンは表示名入力欄の右側に表示
- クリックで初期値に戻る
- 未変更時は disabled
- 既存の保存処理には影響を与えない
- lint が通る
変更前に実装方針を1段落で説明し、その後に差分を作成してください。

この書き方だと、UI配置、挙動、禁止事項、完了判定がそろいます。
単一機能追加では、Agentに「考えてから書く」順番を踏ませるだけで、意図しないファイル追加や命名ぶれが減ります。
小さな機能ほど、その差がはっきり出ます。

Cursor Docs

Cursor is the best way to build software with AI.

docs.cursor.com

複数ファイルのリファクタリング

リファクタリングでは、Agentの自走力がいちばん活きます。
反面、雑に頼むと命名変更が広がりすぎたり、呼び出し元だけ直して型定義が残ったりします。
ここでは「影響範囲」と「守ってほしい約束」を最初に固定するのがコツです。
単に「整理して」ではなく、どのディレクトリまで触るか、命名規約は何か、CIで何を通すかまで書くと、レビューの軸がぶれません。

実務では、components と hooks と tests をまたぐ程度の整理を任せる場面が多いはずです。
そのときは、関数名の方針や import 順、既存の ESLint・Prettier ルール準拠まで含めます。
Agentモードはツール実行まで進められるので、テストやlintの失敗を見つけてそのまま直しにいけますが、最初からCI要件を書いておくと、直したつもりで終わるのを防げます。

たとえば次のように依頼すると、広がりすぎない形で複数ファイル変更を回せます。

ユーザー検索まわりをリファクタリングしてください。
対象範囲は src/features/user-search 配下と、その呼び出し元である src/pages/users.tsx、関連テストのみです。
目的:

- useUserSearch.ts に検索ロジックを集約
- コンポーネントから API 呼び出し詳細を分離
- 重複している型定義を1か所に統合
制約:

- public な props 名は変えない
- 命名は camelCase、React コンポーネントは PascalCase
- 新規依存追加は禁止
- 既存の ESLint / TypeScript 設定に従う
完了条件:

- pnpm lint
- pnpm test
- 既存テストを壊さない
作業前に変更計画を示し、変更後は影響ファイル一覧を要約してください。

こういう依頼では、途中でDiffを見ながら受け入れる単位を細かく切るほうが安全です。
複数ファイルの変更は一見きれいでも、副作用が後から出ます。
私はこの手の作業で、テストが落ちたらまずAgent Best Practicesで勧められている Review から Find Issues を回し、修正余地を洗い出してから追加指示を書く流れに変えてから、手戻りが目に見えて減りました。
失敗したテストを見てその場で思いつき修正を足すより、機械的に抜け漏れを洗うほうが、2回目の差分が締まります。

エラー修正

バグ修正でいちばん効くのは、説明をうまく書くことではなく、再現材料をそのまま渡すことです。
失敗テスト、スタックトレース、再現手順、期待結果の4点がそろうと、Agentは調査の入口を見失いません。
逆に「たまに落ちます」「保存でエラーです」だけだと、検索範囲が広がり、関係ないファイルまで触り始めます。

エラー修正では、現象の文章化よりも、生のログを貼るほうが強いです。
とくにCursorのAgentはターミナル出力や既存テストと相性がよく、失敗箇所を起点にファイルをたどれます。
ComposerとAgentの役割の違いは前述の通りですが、再現性のある不具合ではAgent側に一段深く入ってもらうと、調査から修正までの流れがつながります。

プロンプト例は次の形が使いやすいのが利点です。

ログイン後に /dashboard へ遷移すると 500 エラーになります。原因を調査して修正してください。

再現手順:
1. dev サーバーを起動
2. [email protected] でログイン
3. /dashboard に遷移

期待結果:

- ダッシュボードが表示される
- 500 エラーが発生しない

失敗テスト（実行コマンド）:
pnpm test src/features/dashboard/dashboard.test.ts

スタックトレース:
TypeError: Cannot read properties of undefined (reading 'id')
  at buildDashboardResponse (src/features/dashboard/service.ts:42:18)
  at getDashboard (src/features/dashboard/controller.ts:15:10)

制約:

- 修正は dashboard 関連のコードに限定
- API レスポンス仕様は変えない
- 修正後に関連テストを実行し、結果を要約する

この形式なら、Agentは再現、読解、修正、検証の順で動けます。
私の感覚では、バグ修正は「原因を当てるゲーム」にしないほうがうまくいきます。
仮説を長く書くより、事実を並べたほうが差分の質が上がります。
修正後に落ちたテストが残ったときも、いきなり追加修正を促すより、いったん Review と Find Issues を挟んで残件を拾わせると、局所修正で別の箇所を壊す流れを抑えられます。

テスト作成と実行確認

テスト追加は、ComposerとAgentの組み合わせがもっとも素直に効く場面です。
ポイントは、テストの書き方をAgentに推測させないことです。
どのテストランナーを使うのか、既存スタイルは何か、どの粒度まで書くのか、実行コマンドは何かを明示すると、読みやすいテストが返ってきます。
既存プロジェクトにVitestがあるのにJest風の記法で書かせてしまう、といったズレも防げます。

ここでは、実装だけでなく実行確認まで任せる書き方にします。
Cursor 2.0 と Composer のご紹介で説明されている通り、Composerまわりは対話完了が短時間で収まる設計になっているので、テスト生成から実行結果の要約までを1往復で取りにいく運用と相性がいいです。
Cursor 2.0 と Composer のご紹介は で確認できます。

プロンプト例は次の通りです。

src/utils/formatPrice.ts のテストを追加してください。
要件:

- 既存テストは Vitest + Testing Library のスタイルに合わせる
- describe / it の粒度、命名、expect の書き方は既存の src/utils/*.test.ts を踏襲
- 正常系3件、境界値2件、異常系1件を含める
- カバレッジ目標はこのファイルで主要分岐を網羅することです。
作業:
1. 関連する既存テストを読んで方針を合わせる
2. テストファイルを作成
3. 該当テストを実行
4. 通らない場合は原因を修正
5. 実行コマンドと結果を要約

この依頼だと、Agentはまず既存テストを読みにいき、書きぶりを合わせてから新規テストを書きます。
ここで「主要分岐を網羅」と置いておくと、数値だけのカバレッジ目標を書くより、必要なケースに集中しやすくなります。
テスト作成を人が先にやるか、Agentに先に書かせるかは案件ごとに変わりますが、少なくとも実行確認まで含めて1タスクに閉じると、Accept後に放置される確率が下がります。

4パターンに共通しているのは、Agentに自由を与えることではなく、自由の枠を文章で決めることです。
小さなUI変更では受け入れ条件、リファクタでは影響範囲、バグ修正では再現材料、テストでは実行条件を先に置く。
この順番で依頼すると、出てきた差分をAcceptするかどうかの判断も速くなります。

うまく使うコツ

タスク分割とGit運用

実務で精度を上げるいちばん手堅い方法は、1タスクを1つの『Composer』に閉じ込めることです。
画面調整、API修正、テスト追加、命名整理をひとつの会話に詰め込むと、途中から前提が混ざります。
私も以前、大きめの改修を1つの『Composer』で引っぱったことがありますが、途中から「今どの制約で動いているのか」が薄れ、修正の筋道より辻褄合わせが増えました。
そこから機能単位で『Composer』を切る運用に変えたところ、差分の意図が揃いやすくなり、Acceptする判断も速くなりました。

この運用は、公式のAgent Best Practicesで長い会話を適宜切り替える方針と噛み合います。
短いセッションを積み重ねると、いま見ているファイルと受け入れ条件の結びつきが保たれます。
Cursorは『Composer』をすばやく開き直せるので、1回の会話を延命するより、新しい前提で新規作成したほうが結果として安定します。

Git運用も同じ発想です。
新規作業に入る前に必ずコミットし、適用後も小さく区切ってコミットしておくと、失敗した変更を切り離せます。
機能追加用のブランチ、検証用のブランチ、リファクタ用のブランチを分けておけば、Agentが複数ファイルへ触れたときもリスクが本線に流れ込みません。
『Composer』は複数ファイルをまとめて触れるぶん、便利さと引き換えに変更の面積が広がります。
だからこそ、AIの前にGitで退路を作っておく、という順番が効きます。

プロンプト設計の型

プロンプトは長く書くより、目的・制約・受入基準・影響範囲の4点を先に固定したほうが、返ってくる差分の質が安定します。
実装系の依頼で曖昧になりやすいのは、「何を達成したいか」は書いてあっても、「どこまで触ってよいか」が抜けることです。
ここが空欄だと、Agentは親切心で周辺まで整えに行き、意図していない変更を増やします。

たとえば「フォーム送信後のトースト表示を追加したい」なら、目的は機能追加、制約は既存APIや文言キーを変えないこと、受入基準は成功時に指定文言が出ること、影響範囲は該当コンポーネントとテストに限定、という形にできます。
抽象だけだと解釈が広がり、具体だけだとその場しのぎになります。
この2つの間を埋めるのが4点セットです。

加えて、プロジェクト固有の前提はRulesやDocsに寄せておくと強いです。
命名規則、Lint、CI要件、テストの流儀、使ってはいけないライブラリ、ディレクトリ責務の分け方を文章で残し、必要なときに参照させる形です。
Composer Overviewで説明されているコンテキストの扱いと同じで、毎回すべてを打ち直すより、参照先を明文化したほうが前提のブレが減ります。
実務では「camelCaseで統一」「ESLintエラーゼロ」「型エラーゼロ」「既存のVitest構成に合わせる」といった条件を最初から書いておくと、あとでレビューコメントとして差し戻す回数が減ります。

コンテキスト肥大化対策

長く使うほど難しくなるのが、会話が育ちすぎる問題です。
前半では正しかった前提が後半で薄れ、すでに捨てた案をまた拾ってきたり、直前の指示だけを強く反映したりします。
Cursor 2.0 と Composer のご紹介で示されているように、『Composer』は短い往復で回す設計と相性がよく、実務でもその前提で運用したほうが安定します。
記事は で確認できます。

対策は単純で、新しい論点に入ったら新規の『Composer』を切ることです。
Macなら ⌘N で新しい『Composer』を作れるので、関連はあるが別タスク、という段階で会話を分けるだけでも精度の落ち方が変わります。
ひとつの会話で設計相談、実装、テスト失敗、追加修正まで抱え込むより、「設計を固めるComposer」「実装するComposer」「失敗テストを直すComposer」と切ったほうが、各セッションの責務がはっきりします。

コンテキストに残すファイルも絞ったほうがいい場面があります。
常に全部を抱えるのではなく、いま判断に必要な重要ファイルだけをPillとして残し、終わった論点のファイルは外す。
これだけで、Agentが参照すべき範囲が狭まり、無関係な変更が減ります。
会話が長くなったと感じたら、「ここまでの前提、決定事項、未解決点を3項目で要約して」と一度まとめさせ、その要約を持って新しい『Composer』へ移る運用も効きます。
長大な会話を延命するより、要約を橋にしたほうが誤読が起きにくくなります。

レビュー運用と品質確保

AIが出した差分は、生成できた時点では完成ではありません。
『Composer』の強みはDiffを見ながらAcceptできることですが、その価値は人間がレビューして初めて出ます。
差分は必ず人間が読み、意図した変更か、余計な副作用がないか、命名や責務分割が既存コードと噛み合っているかを確認する。
この手順を外すと、動いて見えるけれど保守性が落ちるコードが混ざります。

レビューでは、まずDiffで変更範囲を見ます。
そのうえでテスト、型チェック、静的解析で裏を取る流れが安定します。
見た目の辻褄が合っていても、型やLintで崩れる変更は珍しくありませんし、テストが通っていない差分はAcceptの判断材料が足りません。

CursorのDiff画面でまとまりごとにAcceptしていく運用は、レビュー単位を小さく保てるのが利点です。
1回の提案を丸ごと飲み込むのではなく、意図が明確な変更から受け入れ、曖昧な差分はRejectかReapplyで再検討する。
この刻み方だと、レビューコメントも具体的になります。
たとえば「このユーティリティ化は今回の影響範囲を超える」「テスト名は既存規約に合わせる」「この例外処理は握りつぶさず呼び出し元へ返す」といった指摘を、Diffの塊ごとに返せます。
AIに任せる工程を増やすほど、レビューの粒度はむしろ細かくしたほうが、全体の品質が揃います。

MCP連携でできること

MCPの概要と導入の最小構成

MCPはModel Context Protocolの略で、外部ツールをCursorのエージェントから呼び出すための接続方式です。
たとえば検索、社内ドキュメント参照、Issue管理、データベース照会のような機能を、単なるテキスト貼り付けではなく「使える道具」として渡せます。
『Composer』のAgentは、この道具群を Available Tools として認識し、必要だと判断したときに自動で使います。
『Cursor MCPドキュメント』でも、この関係が基本線として説明されています。

導入の導線はGUIから追えます。
CursorでMCPサーバーを追加し、有効化すると、対応するツールがComposer Agentの利用候補に並びます。
設定ファイルを先に書き込む運用もありますが、最初の把握という意味ではGUIから追加して、どのツールが見えているかを確認したほうが全体像を掴みやすいのが利点です。
接続後は「何が使えるのか」がAvailable Toolsとして見えるので、Agentに与えた手足の範囲を把握しやすくなります。

実務では、最初から何種類も足すより、1〜2サーバーから始めたほうが安定します。
私も最初は検索系を1つだけ入れて試しましたが、この状態だとAgentがなぜそのツールを選んだのかを追いやすく、誤作動が起きたときも「ツール選択の問題なのか、プロンプトの問題なのか」を切り分けやすくなりました。
MCPは増やすほど便利になる一方で、判断分岐も増えます。
導入初期は、できることを広げるより、挙動を読める状態を保つほうが運用が整います。

AgentとAvailable Toolsの動作

Composer Agentの特徴は、Available Toolsを明示的に毎回指定しなくても、タスクの途中で必要なツールを自動利用できる点にあります。
通常のチャット的な使い方だと「このURLを見て」「このIssueを開いて」と人が逐一段取りを組みますが、Agentモードでは「原因調査して修正して」という依頼に対して、必要に応じて検索し、関連ファイルを見て、テストや外部ツール参照まで連続で進めます。
前のセクションで触れた「自走力」が、MCPによってIDE外へ伸びるイメージです。

ここで押さえたいのは、Agentが勝手に万能になるわけではなく、見えているAvailable Toolsの範囲で動くということです。
検索系MCPだけをつないでいれば、情報探索には強くなりますが、Issueの更新や社内ナレッジ参照はできません。
逆に、社内ドキュメントとチケット管理までつないでおけば、「仕様を確認して、関連Issueを読んで、コードの修正方針を立てる」といった流れが一気通貫になります。
道具が増えるほど行動の幅は広がりますが、何を見せたかでAgentの振る舞いははっきり変わります。

Composer Overviewで説明されているAgentの操作感と合わせて見ると、MCPは「Agentを有効化したあとに手が伸びる先」を増やす仕組みだと捉えると理解しやすいのが利点です。
コード編集そのものは『Composer』が担い、外部の文脈取得や操作をMCPが受け持つ。
この役割分担が見えると、どこまでをCursor内で閉じ、どこから外部ツール連携に任せるかの設計もしやすくなります。

セキュリティ・権限・監査の設計

MCPを実務に入れるときは、機能面より先に認証情報の置き場を詰める必要があります。
検索APIのキー、社内SaaSのトークン、Issue管理ツールのアクセストークンを雑に置くと、Agentが便利になる前に管理が崩れます。
MCPサーバーは外部ツールの入口なので、認証情報の保護が甘いと、そのまま操作権限の漏れに直結します。

権限は最小権限で切るのが基本です。
たとえばGitHub連携なら、最初から書き込み権限まで持たせるより、まず参照中心でつなぎ、必要な操作だけ段階的に広げたほうが事故が少ないです。
AgentはAvailable Toolsを自動利用するので、人間が明示的にボタンを押す運用より一段抽象化されています。
だからこそ「読めるが書けない」「本番は読めるが更新は不可」のように境界を先に作っておくと、誤って触ってほしくない場所を守れます。

監査ログも同じ文脈で効いてきます。
誰がどのMCP経由で何を呼び出したかが追えない状態だと、便利になったぶんだけ原因追跡が難しくなります。
社内導入では、ツール提供元の信頼性確認も外せません。
MCPは仕組みとして中立ですが、実際に入れるのは第三者が配布したサーバーやプラグインです。
コード編集エージェントに渡す道具なので、配布元が不明確なものを気軽に混ぜると、後から統制が取れなくなります。

運用の落とし穴

MCP運用で詰まりやすいのは、「足せば賢くなる」と考えてツールを増やしすぎることです。
実務では、ツール数が増えるほどAgentの選択肢も増えます。
便利さは上がりますが、どのツールを選ぶかの判断コストも膨らみます。
外部の実務ガイドでは40ツール前後がひとつの目安として語られていますが、上限近くまで積む前に、実際によく使うものへ絞ったほうが挙動を追いやすいのが利点です。

もうひとつの落とし穴は、接続方式の安定性です。
リモート環境ではstdio接続が不安定になる場面があり、HTTP系の接続のほうが落ち着くことがあります。
ローカルでは問題なくても、リモート開発環境やコンテナ越しになると、標準入出力ベースのやり取りが詰まり、Agent側では「ツールがあるのに反応しない」ように見えることがあります。
こういうときはプロンプトを調整するより、接続層を疑ったほうが早く片づきます。

運用では、Agentが外部ツールを呼ぶ回数にも意識を向けたいところです。
ツール呼び出しは無限ではなく、タスクの流れの中で上限があるため、無駄な探索を増やす構成だと肝心の実装前に回数を消費します。
MCPは「何でもつなぐ」より「この作業で必要な道具だけ見せる」ほうが、結果として短い往復で収まります。

最新拡張

MCPまわりはここ数か月で拡張の速度が上がっています。
2026年3月時点でAutomationsや30以上の新規プラグイン追加が確認でき、Agentをコード編集だけで終わらせない方向へ伸ばしているのが見えます。
MCPの価値は単体の接続仕様より、「どれだけ周辺ツールがこの入口に集まるか」で決まるので、この増え方はそのまま実務での守備範囲の広がりに直結します。

Cursor 2.0 と Composer のご紹介で見えるマルチエージェントや自動化の流れと合わせると、MCPは補助機能ではなく、Agent運用の前提インフラに近づいています。
コードを書くAgentに、検索、知識参照、チケット、運用自動化の入口が順番につながっていくと、Cursorは単なるAI付きエディタではなく、作業ハブとして振る舞います。
今の段階では、その広がりを最初から全部取り込むより、1〜2本のMCPで確実に回る経路を作り、そこから必要な拡張だけを足していく形がもっとも現実的です。

Changelog · Cursor

New updates and improvements.

cursor.com

よくある失敗と対処法

意図外の変更対策

『Composer』で最初につまずきやすいのが、頼んだつもりのないファイルまで触られる場面です。
原因の多くは、最初の指示が広すぎるか、コンテキストに入れた範囲が広すぎるかのどちらかです。
実務では「どのフォルダの、どのファイルに、何を変えて、何は変えないか」まで先に書いた回のほうが、差分の収まりが安定しました。
逆に、私自身Context Pillsでフォルダを広く入れすぎた回は、意図外の修正が目に見えて増えました。
最小限のファイルから渡し、必要になったら足す順番のほうが事故が減ります。

効くのは、影響範囲を文章で明示したうえで、Context Pillsを狭く保つことです。
たとえば「src/auth 配下のみ変更」「package.json とテスト以外は触らない」と切るだけでも、Agentの探索先が絞られます。
複数ファイル編集が前提の作業でも、最初からプロジェクト全体を見せるより、関連フォルダだけに限定したほうが差分の意図を追えます。

差分の適用では、未承認のものを流し込まない姿勢が効きます。
『Composer』のDiffビューでは『Accept』RejectReapply系の操作が見えるので、ひとまとまりずつ確認し、納得できない変更はその場で弾く運用が合います。
特に命名変更やimport整理のように一見きれいな差分ほど、周辺ファイルへ波及していることがあります。
前述の運用と同じく、Gitの細かいコミットとDiff確認を組み合わせると、意図外の広がりを局所で止められます。

長会話の精度低下対策

会話が長くなると、Cursorは最初に共有した前提より、直近の往復を強く拾う挙動が目立ってきます。
途中で方針転換が入ったり、試行錯誤のログが積み上がったりすると、古い指示と新しい指示が混ざり、修正の軸がぶれます。
長い会話はAgentのフォーカスを落とすので、新しい会話へ切り替える運用が勧められています。

詰まりを感じたら、同じスレッドで粘るよりセッションを分けたほうが早く戻せます。
『Composer』の起動は ⌘I / Ctrl+I、新規作成は ⌘N で切り替えられるので、機能追加、テスト修正、リファクタのように作業単位で会話を分けると文脈の濁りが減ります。
途中までの経緯が必要なら、古いセッションの内容をそのまま引きずるのではなく、「現状」「決めたこと」「未解決」の3点だけを短く要約して新しい『Composer』へ渡すと、解像度が戻りやすくなります。

ここで効くのが、Rulesや作業ルールの再読込です。
長会話では、最初に効いていたコーディング規約や禁止事項が薄れがちです。
新しいスレッドで「このプロジェクトのRulesに従う」「直近の変更方針はこれ」と再宣言すると、会話の軸が揃います。
速度面ではCursor 2.0 と Composer のご紹介で多くの対話が30秒未満で完了するとされていても、長大セッションの精度まで保証してくれるわけではありません。
速く返ることと、前提を保ったまま返ることは別の話として扱ったほうが運用が安定します。

Cursor エージェントのベストプラクティス

プラン作成からコンテキスト管理、ワークフローのカスタマイズ、コードレビューまで、コーディングエージェントとの連携方法を網羅的に解説します。

cursor.com

Lint自動修正の仕様理解

Lintの自動修正が効かないときは、「AIが直せなかった」と考える前に、そもそも自動修正の前提条件を外していないかを見ると整理しやすくなります。
たとえばESLintやPrettierは対象言語や設定ファイル、保存時実行の有無で挙動が変わります。
保存をトリガーにしているのにDiff上で止めている、ワークスペース設定ではなくユーザー設定だけに入っている、修正可能なルールではなく警告だけ出している、といったズレで止まることがよくあります。

もうひとつ見落としやすいのが、自動修正の回数です。
Cursorまわりの実務解説や運用観察では、Lintの自動修正は1回で終わる前提で組んだほうが噛み合います。
1回のfixで整形は入っても、その結果で新しい警告が出るケースまでは面倒を見切れないことがあります。
たとえばimport順の修正後に未使用importが露出するような流れです。
この場合はIDE側で何度も期待するより、CIやローカルスクリプト側で lint --fix を再実行する構成のほうが安定します。

『Composer』に頼む文面も具体的にしたほうが通ります。
「lintを直して」だけだと、エラー一覧の読解と修正方針の推定を同時にやることになります。
「ESLint の未使用変数だけ修正」「Prettier の整形差分のみ適用」のように切ると、Diffの確認範囲も狭くなります。
自動修正が空振りしたときほど、AIの能力不足ではなくツール側の仕様を疑う視点が効きます。

MCPツール未表示の原因切り分け

MCPを入れたのにツールが見えないときは、Agentのプロンプトをいじる前に、接続面の切り分けをしたほうが近道です。
CursorではAgentがAvailable Toolsに見えている道具を使うので、そこに出ていない段階では、指示文を工夫しても呼ばれません。
見る順番は、MCPサーバーが起動しているか、認証が通っているか、Cursor側とサーバー側のバージョンが噛み合っているかです。

ツール数の持ち込みすぎも盲点です。
外部の実務ガイドでは40ツール前後がひとつの目安として扱われていて、数が増えるほど表示や選択の追跡が難しくなります。
最初の導入で検索、Issue参照、社内ドキュメント参照を一気に積むより、1〜2サーバーから始めたほうが、見えない理由を切り分けやすくなります。
前のセクションでも触れた通り、道具を減らすと「Agentが判断していない」のか「接続できていない」のかを分けて見られます。

認証切れもよくある詰まり方です。
GitHubや社内SaaS系のMCPは、サーバー自体は生きていても、トークン失効で中身だけ使えないことがあります。
この状態だと、ツール名は見えても実行時に失敗したり、そもそも一覧へ現れなかったりします。
Cursor MCPドキュメントで案内されているAvailable Toolsの見え方を基準にすると、UIに出ているかどうかで、Agentの問題と接続の問題を切り分けやすくなります。

Cursor Docs

Cursor is the best way to build software with AI.

docs.cursor.com

remote/stdio対処

リモート開発環境でstdio接続が不安定になると、MCPが「あるのに使えない」状態になりがちです。
ローカルでは普通に通っていたのに、リモートVM、コンテナ、踏み台越しの環境へ移した途端に黙るケースは珍しくありません。
標準入出力ベースの通信はシンプルですが、プロセス寿命やバッファ詰まりの影響を受けやすく、接続が切れても見た目上は静かに失敗することがあります。

こういう場面では、stdioに固執せずHTTPやWebSocket系のトランスポートへ切り替えたほうが収まりやすいのが利点です。
特にリモート常駐のMCPサーバーは、ソケット越しのほうが監視や再接続の設計と相性が合います。
加えて、タイムアウト値が短すぎると「起動に時間がかかっただけ」のサーバーを不達と誤認しやすく、再試行回数が少なすぎると一瞬の揺れで消えます。
接続方式、タイムアウト、再試行の3点をまとめて見ると、原因がプロンプトではなく通信層にあることが見えやすくなります。

料金・クレジットの見え方

（執筆時点: 2026-03-18）。
料金は更新されやすく、国別の課税やモデル別の消費量で実コストが変わるため、最新情報は公式の Pricingと Models & Pricingを必ずご確認ください（確認日: 2026-03-18）。
読みにくさが出るのは、長い会話や長文コンテキストの連発で、消費が目に見えにくいまま積み上がるからです。
短い依頼を区切って投げた月より、ひとつの巨大セッションを引き延ばした月のほうが、減りが早く感じることがありました。
体感としても、重いモデルで長文を何度も往復させる運用は、作業時間より先にクレジット残量が気になります。

そのため、料金の把握は「プラン名」だけでなく、「どのモデルを、どの長さのセッションで使っているか」まで含めて見る必要があります。
モデルごとの細かい単価はModels & Pricing側で追う前提になりますが、執筆時点でも実務では、長大セッションを避けて作業を分けたほうが、精度だけでなく消費の見通しも立てやすいのが利点です。
会話が肥大化すると、品質低下とクレジット消費の両方が同時に出るので、この2つは別問題ではなく同じ運用ミスとして扱うと整理しやすくなります。

Chat・Windsurf・Claude Codeとの使い分け

Chat vs Composer vs Agent

Cursorの中でも、まず迷いやすいのがChat『Composer』Composer Agentの線引きです。
見た目は近くても、実際の向き先はけっこう違います。
短く言うと、Chatは相談窓口、『Composer』は複数ファイル編集の作業台、Agentはツール実行まで含めて前に進める実行役という捉え方だと整理しやすくなります。

これらは公式の表現であり、実際の応答速度や対話時間は環境やタスクに左右されるため、」といった前置きや、実運用では変動する旨の注意書きを入れてください。
起動の導線も分かれていて、『Composer』は ⌘I / Ctrl+I、新規Composerは ⌘N、Agentの有効化は ⌘. です。
日常運用では、この導線の違いがそのまま役割の違いになりやすい印象があります。
質問から入るならChat、差分を作る前提なら『Composer』、ローカルの実行環境やMCPまで巻き込みたいならAgent、という切り替えです。

実務だと、Chatで要件や設計の叩き台を出してから、『Composer』で差分化し、必要なところだけAgentに渡す流れが収まりやすいのが利点です。
いきなりAgentに全部任せるより、どこまでを相談で止めるか、どこから実ファイル編集に入るかを分けたほうが、Diffの確認範囲も狭くなります。

CursorとWindsurfの使い分け

CursorとWindsurfは、どちらが上というより、普段の開発姿勢で向き先が分かれる印象です。
コミュニティでよく見かける評価の傾向として、CursorはVS Code系の操作感を保ったままAI編集を濃くしたい人に刺さりやすく、Windsurfは画面をすっきり保ちながら自動化寄りの体験を求める人に選ばれやすいのが利点です。

Cursorの強みとして語られやすいのは、差分確認のしやすさと『Composer』中心の編集フローです。
複数ファイルをまたぐ変更でも、どこを受け入れるかを細かく見ながら進められるので、既存コードベースに段階的に手を入れたい人に合います。
一方で、長いセッションを引き延ばすと文脈が崩れたと感じる声はあり、ひとつの巨大な会話に何でも積み込む使い方だと粗が見えやすくなります。

Windsurfは、文脈の自動収集や操作の単純さを評価する声が目立ちます。
設定を詰め込むより、まず動かして前に進みたい人には馴染みやすいのが利点です。
反面、大きめのコードベースでの安定感は評価が割れていて、細かいDiff管理やIDE内での手綱の握りやすさを重視する人はCursorに戻ることがあります。

この2つで迷うなら、ひとつの目安は「既存のVS Code作法をどこまで残したいか」です。
拡張、ショートカット、パネル構成、差分レビューの感覚まで含めて今の延長線でAI編集を増やしたいならCursor寄りです。
逆に、UIの情報量を減らし、できるだけ自動で文脈を拾ってほしいならWindsurf寄りに振れます。

CursorとClaude Codeの使い分け

CursorとClaude Codeは、用途の軸がもっとはっきり分かれます。
CursorはIDE一体でコードを書き換える体験が中心で、Claude CodeはCLI中心で長い文脈を抱えたまま進めるタスクに向く、という見方がしっくりきます。

自分の運用でも、大規模な長文脈リサーチや、複数の資料・ログ・コード断片をまとめて読ませながら考えさせたい場面ではClaude Codeを使うことが多いです。
ターミナル中心なので派手なGUIはありませんが、そのぶん調査対象を束ねて長い流れで扱いやすい感触があります。
逆に、見ながら直す、差分を受け入れる、ファイルをまたいで編集する、といったIDE一体の作業はCursorのほうが収まりがいいです。
調査はClaude Code、実編集はCursorという分担にすると、両者の得意分野がぶつかりません。

コミュニティの評価でも、Claude Codeは長文脈や大規模タスクに強いという声が多く、その代わりIDEとの一体感は弱めと見られています。
Cursorはその逆で、Diff確認や『Composer』による編集の流れが強い一方、CLI中心の深い調査作業ではClaude Codeのほうが手になじる人もいます。
エディタに閉じたまま完結したいか、シェルを起点に作業を組み立てたいかで、印象は大きく変わります。

どんな人に向くかの目安

道具選びを一文で切るなら、VS Code系でAI編集を増やしたいならCursor、シンプルなUIと自動化志向を重視するならWindsurf、CLI中心で長文脈タスクを深く回したいならClaude Code、という並びになります。
ただし、これは優劣ではなく、どの操作を日常の中心に置くかの違いです。

Cursorに向くのは、既存プロジェクトへ入りながら、差分レビューを挟んで安全に編集を進めたい人です。
Chatで相談し、『Composer』で複数ファイルを直し、必要ならAgentでテストやツール実行まで伸ばせるので、ひとつのIDEの中で作業を閉じたい開発者と相性が合います。

Windsurfに向くのは、設定や画面構成よりも、まずAIに流れを作ってほしい人です。
文脈収集や自動化の感覚を重視するなら候補に入りやすく、IDEに細かい作法を持ち込みすぎないほうが気持ちよく使えるタイプです。

Claude Codeに向くのは、ターミナルや既存エディタを中心に据えたまま、調査・要約・長い思考を扱いたい人です。
コードを書く場所と、AIに深く考えさせる場所を分けたい人に合います。
自分もその使い方に落ち着いていて、編集の現場はCursor、大きな文脈を抱える調査はClaude Codeと分担したほうが、作業のリズムが崩れません。

ツール選定で詰まりやすいのは「全部1本で賄う前提」で考えることです。
実際には、Cursorの中でもChat『Composer』Agentで役割を分けられますし、外ではWindsurfやClaude Codeと住み分けできます。
用途ごとの境界が見えると、どのツールが優れているかではなく、どの作業をどこに置くと自然かで判断しやすくなります。

実務での使い分け判断フロー

小規模修正の最短ルート

1ファイル内の軽い修正や、変更点が頭の中ではっきりしている作業なら、『Composer』を通常モードで開いてそのまま直す流れが最短です。
たとえば文言修正、型の補強、関数の引数追加、既存UIの小さな整形なら、まずは編集範囲を狭く保ったまま差分を見たほうが手綱を握れます。
Cursorの『Composer』はショートカットで素早く呼び出せるので、エディタ上で対象ファイルを開いたまま短い指示を投げ、出てきた差分をその場で受け入れる、という往復が軽いです。

Cursorの料金は月ごとのクレジットプール方式へ移行しており、長いタスクほど消費が増える点に注意が必要です。
最新の料金情報は公式の Pricingおよび Models & Pricingで確認してください（確認日: 2026-03-18）。

複数ファイル修正の安全運転

変更が2ファイル、3ファイルと増えた瞬間に、主役は『Composer』になります。
新しいフックを追加して呼び出し側も直す、型定義を更新して利用箇所を追従させる、UIコンポーネントを分割して import を整理する、といった作業は、単発編集よりも差分のつながりを見る力が求められます。
ここでは「どこまで書き換えたか」を一覧で追える『Composer』の流れが合っています。

ただし、私の経験では、複数ファイルだからといって即Agent全面委任にすると、修正範囲の境界が曖昧になりやすいのが利点です。
自分は、リファクタや横断修正でも中心はあくまで『Composer』に置き、Agentはコンテキスト収集と実行補助に絞ることが多いです。
たとえば「この型を参照しているファイルを洗ってほしい」「古い関数名の利用箇所を拾ってほしい」といった探索を任せ、実際の編集提案は『Composer』の差分で受ける形です。
この分け方だと、修正対象の把握は機械に手伝わせつつ、変更の採否は人間側で刻めます。

作業後のレビューや問題検出を挟む流れが勧められています。
これは現場感覚にも合っていて、まとめて書き換えさせるほど、差分確認の密度が品質を左右します。
『Accept』Rejectを細かく切りながら進める前提なら、『Composer』中心のほうがプロジェクトの形を崩しにくい設計です。

テスト先行の反復設計

テストが絡む実装では、ここだけ判断が変わります。
仕様をテストで先に固定し、その後に実装を寄せていく場面では、Agentを有効にしたほうがサイクルが短く回ります。
狙いは自律性そのものではなく、テスト作成、実行、失敗原因の特定、再修正までを一続きで進めることです。
単にコードを書くだけなら通常モードでも足りますが、赤から緑へ持っていく往復には、実行系の補助が入ったほうがテンポが落ちません。

実務では、新機能の追加よりも「既存仕様を壊していないか」を確認したい修正で、この運用が効きます。
まず失敗するテストを書かせ、次に最小限の実装を入れ、落ちた箇所だけを見て修正し、通ったら差分を読む。
この短い輪を何度も回すと、設計のズレが早い段階で表に出ます。
こうした応答の軽さは、テストを回して直してまた聞く、という反復で効いてきます。
長い設計会議のような1回より、小さな往復を積み重ねる作業で差が出ます。

ここで気をつけたいのは、テストまで自動で通ったから終わり、にしないことです。
テスト付きの実装ほど「通すための迂回」が入りやすく、命名や責務分離が後回しになる場面があります。
そこで、自分はテスト反復のあいだだけAgentをオンにして、緑になった段階でオフへ戻し、整形や命名の磨き込みは『Composer』通常モードで受け直すことが多いです。
この切り替えだと、反復速度と最終品質の両方を拾えます。

MCPが絡むときの段階導入

外部情報や社内ツールの参照が鍵になる作業では、AgentにMCPを組み合わせる価値が出てきます。
たとえば設計書リポジトリ、チケット管理、API仕様、社内ドキュメントのように、IDEの外に判断材料が散っているときです。
ただし、この領域は最初から全部つなぐより、少数から入れたほうが挙動を読みやすいのが利点です。
TrueFoundryの実務知見でも、導入は1〜2サーバーから始める形が勧められていて、ツール数も増やしすぎないほうが管理しやすいとされています。

体感でも、最初に必要最小限のMCPだけを見せたほうが、Available Toolsの振る舞いを観察しやすいのが利点です。
何を優先して呼ぶのか、どの情報源に寄りやすいのか、期待した順序で参照しているかが見えてきます。
ここで一度にたくさんのサーバーやツールを渡すと、探索自体が仕事になり、肝心の実装に入る前に文脈が散ります。
ツール上限の目安として40ツール前後という考え方もありますが、実務ではその上限まで埋める発想より、今のタスクに必要な道具だけ並べるほうが落ち着きます。

Agentはツール呼び出しを自動で進められるぶん、MCPと組み合わさると一気に便利になります。
その反面、どの外部情報を根拠に変更したのかを人間が追える状態を残しておかないと、差分レビューの意味が薄れます。
だから、MCPを使う場面でも、最初の一歩は「調査に使う」「参照元を確定する」までに留め、編集そのものは『Composer』で受ける形が安定します。
外部情報を読む段階ではAgent、コード差分を詰める段階では『Composer』という二段構えにすると、MCPの力を借りながらも編集の主導権は保てます。

まとめと次のステップ

この記事の要点まとめ

Cursorの『Composer』は、まず人間が変更の境界を決め、そのうえでAgentに探索や実行を任せると安定します。
差分は都度レビューし、CheckpointとGitを併用して戻れる状態を保つと、試行錯誤の速度と安全性を両立できます。
自分も最初の1週間は「1タスク1Composer＋必ずGit」だけを徹底しましたが、それだけで安心感と再現性が一段上がりました。
MCPは便利ですが、最初から広げすぎず、必要最小限から挙動を見る進め方が結局いちばん崩れません。

今日から試す3つのアクション

1. まずは小さめのバグ修正を1件だけAgentに任せて、どこまで自走し、どこで確認を挟みたくなるかを観察してみてください。
2. 次はテスト作成込みで依頼し、Diffを読んで適用し、必要ならロールバックする流れを一度通してみると、『Composer』の扱い方が手に入ります。
3. MCPは1つだけ追加して、どのツールをどう呼ぶかを眺めると、実務投入してよい範囲が見えてきます。

料金とモデルの最新情報の追い方

料金まわりはクレジット制への移行以降、体感コストが変わりやすい領域です。
公開時点の判断材料としては、Cursor公式のPricingとModels & Pricingを確認日付きで社内メモに残す運用が堅実です。
月額だけで判断せず、使うモデルとタスクの重さまでセットで見ると、あとから運用がぶれません。

Cursor · 料金プラン

自分に合ったプランを選ぶ

cursor.com