Cursor Composer：実際に機能する複数ファイル編集
ほとんどのCursorユーザーは通常のチャットに留まっています。関数を尋ね、出力をコピーしてファイルに貼り付け、繰り返します。小さな作業には機能します。しかし、1つの機能を追加するために5つのファイルを変更する必要があるとき、そのワークフローは崩壊します。
ComposerはCursorがこの問題に対して出した答えです。これは別のパネルで、変更したいことを説明すると、Cursorが一度に複数のファイルにわたる編集を提案します。確認して、各変更を承認または拒否し、次に進みます。コピーアンドペーストなし。コンテキスト切り替えなし。
このガイドでは、Cursorフォーラムからの実際のワークフローをカバーします。マーケティングトークはなし。実際に機能するものだけです。
Composer vs 通常のチャット：実際の違い
通常のチャットはQ&Aです。尋ねて、Cursorが答えます。コードをファイルに移すのは依然としてあなたの仕事です。
Composerはアクションです。目標を説明すると、Cursorがどのファイルに触れ、何を変更すべきかを把握します。diffを提示し、あなたがどれを採用するか決めます。
| 機能 | 通常のチャット | Composer |
|---|---|---|
| コードを提案する | はい | はい |
| ファイルを直接編集する | いいえ | はい |
| 複数ファイルの変更 | いいえ | はい |
| 適用前にdiffを表示 | いいえ | はい |
| チェックポイント/ロールバック | いいえ | はい |
| 最適な用途 | 質問、単一スニペット | リファクタリング、機能開発、一括更新 |
重要な機能はチェックポイントです。Composerは変更を加える前にスナップショットを保存します。編集がうまくいかなくなった場合、1クリックでチェックポイントに戻れます。通常のチャットには安全網がありません。
Cmd/Ctrl + I を押すか、左サイドバーのComposerアイコンをクリックします。チャットとは別のパネルです — 混同しないでください。
Composerを使う場面
Composerは、1つのタスクが複数のファイルに触れるときに真価を発揮します。一般的なシナリオ：
- リファクタリング — コンポーネント間でprop名を変更する、共有ユーティリティを抽出する
- 機能開発 — 新しいAPIエンドポイントを追加するには、route、controller、service、テストファイルの変更が必要
- パターン更新 — どこでも
fetchをカスタムのapiClientに切り替える - 型の変更 — 10のファイルに波及するインターフェースを更新する
- インポートの整理 — モジュール構造を再編成する
チャットからコードをコピーして2つ以上のファイルに貼り付けているなら、やめてComposerを使いましょう。
素早い質問、1行のコード、または「この正規表現を説明して」 — 通常のチャットの方が速いです。Composerにはオーバーヘッドがあります。複数ファイルの作業のために取っておきましょう。
実際のワークフロー1：複数ファイルにまたがるリファクタリング
types.ts に User 型があります。displayName フィールドを追加するため、name を fullName に変更したいとします。命名が混乱してきました。
これは以下に触れます：
src/types.ts— 型定義src/components/UserCard.tsx— 名前を表示src/components/UserProfile.tsx— これも名前を表示src/api/users.ts— このフィールドを送受信するAPI呼び出しsrc/lib/validators.ts— ユーザー検証のZodスキーマ
ステップ1： Composerを開きます（Cmd/Ctrl + I）。
ステップ2： 変更内容を説明します：
User型の `name` フィールドを `fullName` に変更し、コードベース全体の使用箇所を更新してください。動作は一切変更しないでください — これは純粋なリネームです。
ステップ3： 提案されたdiffを確認します。Composerは各ファイルの変更をハイライト表示します。以下を確認してください：
- ユーザーに関連する
nameのみがリネームされている（他のnamepropは変更されていない） - API層が正しいデータを送受信している
- ロジックの変更が紛れ込んでいない
ステップ4： ファイルごとに承認または拒否します。1つのファイルが間違っている場合は、そのファイルだけ拒否して手動で修正します。
Composerは時々、手を出しすぎることがあります。コンテキストが似ていると、無関係なコンポーネントの name propもリネームする可能性があります。承認する前に必ずdiffを確認してください。
実際のワークフロー2：複数ファイルにまたがる機能追加
アプリに「ユーザーロール」を追加したいとします。管理者ユーザーには追加のUI要素が表示され、追加のAPIエンドポイントにアクセスできます。
関与するファイル：
src/types.ts— Userにrole: 'user' | 'admin'を追加src/api/auth.ts— JWTペイロードにroleを含めるsrc/components/Navbar.tsx— 管理者のみadminリンクを表示src/components/AdminPanel.tsx— 新しいコンポーネントsrc/hooks/useAuth.ts—isAdminフラグを公開src/middleware/auth.ts— adminロールをチェックする新しいミドルウェア
ステップ1： Composerを開きます。
ステップ2： 計画を与えます。単なる願いではなく：
アプリにユーザーロールを追加してください：
1. src/types.ts のUser型に `role: 'user' | 'admin'` を追加
2. src/api/auth.ts のログインレスポンスを更新し、JWTペイロードにroleを含める
3. src/hooks/useAuth.ts に `isAdmin` 計算値を追加
4. Navbar.tsxを更新し、isAdminがtrueのときに「Admin」リンクを条件付きで表示
5. src/components/AdminPanel.tsx を作成し、プレースホルダーの管理者ダッシュボードを配置
6. src/middleware/auth.ts を作成し、JWTのroleをチェックするrequireAdminミドルウェアを記述
コードベースの既存のパターンを使用してください。他のAPIファイルと同じエラーハンドリングスタイルに従ってください。
ステップ3： Composerが複数ファイルのdiffを生成します。各ファイルを確認します。
ステップ4： 新しい AdminPanel.tsx が間違っている場合は、それを拒否し、残りは保持します。Composerの編集は粒度が細かいです。
Composerにコーディングさせる前に、計画の概要を尋ねてください。「編集を行う前に、変更するファイルとその理由をリストしてください」と追加します。これにより、誤解を早期に捉えられ、コストはかかりません。
実際のワークフロー3：API呼び出しの一括更新
フロントエンドに散らばった生の fetch 呼び出しから始めました。今では、認証ヘッダー、エラーハンドリング、base URL設定済みのカスタム apiClient があります。すべてを移行する必要があります。
ファイル：数十ものAPI呼び出し箇所の可能性があります。
ステップ1： apiClient が存在し、1つのファイルで正しくインポートされていることを先に確認してください。Composerは、参照実装があるときに機能が向上します。
ステップ2： Composerを開き、タスクの範囲を限定します：
src/ 内のすべての生の `fetch` 呼び出しを、src/lib/apiClient.ts の `apiClient` に置き換えてください。
ルール：
- 既存の `apiClient.get`、`.post`、`.put`、`.delete` メソッドを使用
- 手動のJSON.stringifyとresponse.json()処理を削除 — apiClientがこれを行う
- 同じエンドポイントパスを保持
- apiClientにまだないカスタムヘッダーは保持
src/api/ ディレクトリから始め、必要に応じて src/hooks/ も処理してください。
ステップ3： バッチごとに確認します。20ファイルを一度に見ずに承認しないでください。Composerは優れていますが、完璧ではありません。
ステップ4： 承認後にテストスイートを実行します。diffがきれいに見えても、型エラーやランタイム動作が分岐する可能性があります。
50ファイル以上ある場合は、チャンクに分割します。「まず src/api/ を移行する」。次に「src/hooks/ を移行する」。大きなバッチはレビューが難しく、ミスも起きやすくなります。
Composer + Agentモード：強力なコンボ
ComposerとAgentモードは、異なる問題を解決します。Composerは、やりたいことが分かっている対象を絞った複数ファイル編集向けです。Agentモードは、AIが探索し、コマンドを実行し、自分で把握する必要があるオープンエンドのタスク向けです。
しかし、両者は連携できます。
パターン：Agentが計画し、Composerが実行する
Agentモードを使って変更の範囲を把握します：
React ContextからZustandに状態管理を移行したいです。AuthContextを使用しているすべてのファイルをリストし、各ファイルにどのような変更が必要か教えてください。
Agentモードはコードベースを検索し、内訳を提供します。次にComposerを開いて、完全なdiffレビューとともにファイルごとに変更を実行します。
パターン：Composerでリファクタリングし、Agentで検証する
大規模なComposerリファクタリングの後、Agentモードに切り替えます：
テストスイートを実行し、最近のリファクタリングによって生じた壊れたインポートや型エラーを修正してください。
Agentモードがクリーンアップを処理している間、あなたはComposerの変更を確認できます。
Agentモードでは、Cursorが複数ファイル編集のために内部的にComposerを開くことがあります。これを直接制御することはできませんが、Agentセッション中にComposerスタイルのdiffが表示されることがあります。同じように確認してください。
よくあるミスとその回避方法
1. 曖昧なプロンプト
悪い例：「認証を良くしてください。」
良い例：「User型に role フィールドを追加し、ログインAPIを更新してJWTに含め、管理者ユーザーにはNavbarにadminリンクを表示してください。」
具体性は驚きを減らします。
2. 確認せずに承認する
Composerのdiffはきれいに見えますが、以下の可能性があります：
- 残しておきたいコメントを削除する
- 無関係な行のフォーマットを変更する
- 1つのファイルでエッジケースを見落とす
必ずdiffを確認してください。30秒かかりますが、やり直しを省けます。
3. 一度に多すぎるファイル
Composerは10〜15ファイル程度なら問題なく処理できます。それを超えると、コンテキストウィンドウが圧迫され品質が低下します。大きなタスクを論理的なチャンクに分割してください。
4. チェックポイントを使わない
大きなComposerセッションを始める前に、チェックポイントボタンを押してください。1クリックです。セッションがうまくいかなくなった場合、ロールバックも1クリックです。これをスキップする言い訳はありません。
ComposerのチェックポイントはCursor内部に存在します。Gitの代わりにはなりません。大きなComposer作業の前に、gitにもコミットしてください。両方の安全網を使いましょう。
5. 変更後の型エラーを無視する
Composerの編集はおおよそ90%の確率でコンパイルを通ります。残りの10%は、特にリネームやインターフェース変更時に、微妙な型の不一致を引き起こします。変更を承認した後は tsc またはリンターを実行してください。
クイックリファレンス
| アクション | ショートカット |
|---|---|
| Composerを開く | Cmd/Ctrl + I |
| 変更を承認 | Cmd/Ctrl + Y |
| 変更を拒否 | Cmd/Ctrl + N |
| チェックポイントを作成 | Composerパネルのチェックポイントアイコンをクリック |
| チェックポイントに戻る | チェックポイント横の復元アイコンをクリック |
まとめ
- 複数ファイルの編集にはComposerを、質問には通常のチャットを使いましょう。
- 正確にやりたいことを説明してください。ファイルパスと制約条件を含めます。
- 承認する前にすべてのdiffを確認してください。
- 大きなセッションの前にチェックポイントを作成してください。
- 大きなタスクはチャンクに分割してください。
- ComposerとAgentモードを組み合わせましょう：Agentが探索し、Composerが実行します。
Composerは魔法ではありません。複数ファイルの作業からコピーアンドペーストの手間を取り除くツールです。正しく使えば、時間を節約できます。不注意に使えば、クリーンアップ作業を生み出します。違いは確認のステップにあります — スキップしないでください。