Cursor Composer 完全ガイド：複数ファイル編集のコツと実践事例

Cursor を 3 ヶ月使い続けて、ようやく自分がその真価を「無駄にしていた」ことに気づいた。

以前は機能修正のたびに、コンポーネント、API、型定義、テスト、設定——5 ファイルも触る。Chat で 1 つずつ質問し、コードをコピー＆ペースト。ファイルを行き来し、Cmd+C と Cmd+V の間を往復する。本当に疲れる。

ある日、同僚が画面を 3 秒見て言った。「なんで Composer 使わないの？」

「え？」

「Cmd+I のフローティングウィンドウ。要件を一言伝えるだけで、AI が直すべきファイルを判断して、まとめて書き換えてくれるんだよ」

呆然とした。

デモは衝撃的だった。Composer を開き、関連ファイルを @ 参照。「ユーザーログインをメール認証対応に変えて」と Enter。数秒でコンポーネント、API、型定義まで一気に直された。10 分で終わり。

同じ作業に、以前は 1 時間かかっていた。

その瞬間、3 ヶ月間 Cursor の能力を 20% しか使っていなかったと分かった。フェラーリに乗って 1 速だけで走っていたようなものだ。

Composer とは？なぜ必要なのか

Composer vs Chat の本質的な違い

例え話をしよう。

Chat は隣に座る AI アドバイザー。「このコード、どう最適化する？」と聞けば助言はくれる。手を動かすのは自分。

Composer は AI 実装チーム。「このビルの窓を全部掃き出し窓に変えて」と言えば、直接作業して「完了しました、確認してください」と返す。

本質はここ。一方はアドバイザー、もう一方は実装チーム。

比較表：

「会話履歴が保存されない」——これが最大の落とし穴。後半で回避策を詳しく書く。

Composer の 3 つの核心能力

能力 1：ファイル横断の理解

Chat は今開いているファイルしか見えない。Composer はプロジェクト全体を見る。

「ユーザーログイン機能を追加して」と言うと、Chat は「どのファイル？」と聞く。Composer は「Login.tsx、auth.ts、user.types.ts、api/auth.ts、App.tsx の 5 ファイルを直します」と返し、実際に直す。

能力 2：プロジェクト単位の修正

Chat ならコピー＆ペースト。Composer は修正をファイルに直接適用し、Accept / Reject を選ぶだけ。

Chat が設計図を渡すだけなら、Composer は工事を終えて検収を求めるイメージ。

能力 3：推論（Agent モード）

Agent を有効にすると Composer は次もできる：

• シェルコマンド実行（npm install、git status など）
• コードベース全体の検索
• 依存関係の自律分析
• ファイルの作成・削除

現場監督がついた実装チーム——自分で判断し、道具も探す。反面「やりすぎ」もしやすい。制御方法は後述。

Composer を使うべき 3 つの場面

場面 1：新機能開発（複数ファイル）

要件：コメント機能を追加。

Chat のやり方：

1. 直すファイルを Chat に聞く
2. 5 ファイルのリストが返る
3. 1 つずつ開く
4. 「Comments コンポーネントを書いて」と頼む
5. コピーして貼る
6. 「コメント API を書いて」
7. コピー、貼り付け
8. 5 回繰り返す

地獄。

Composer のやり方：

1. Composer を開く（Cmd+I）
2. 「コメント機能を追加。投稿・削除・閲覧ができるように」と入力
3. Enter
4. AI が対象ファイルを特定して一括修正
5. diff を確認して Accept

10 分。

場面 2：コードリファクタリング

要件：Redux から Zustand へ移行。

Chat：20 ファイル超——ほぼ不可能。手動だと漏れとミスが出やすい。

Composer：

@src/store
@src/components

Redux store を Zustand に移行：
1. 既存の state 構造を維持
2. API は変えない
3. redux 依存を削除

Agent モードで依存を分析し、ファイルを修正し、動くか確認まで。20 分程度。

場面 3：一括修正

要件：すべての API 呼び出しに try-catch を統一。

Chat：1 ファイルずつ。漏れやすい。

Composer：

@src/api

すべての API 呼び出しに統一エラー処理を追加：
- try-catch でラップ
- エラーメッセージ形式を統一
- エラーログを記録

15 ファイルを一発。

Composer vs Chat：5 秒判断法

違いは分かった。でも実際の開発では「Cmd+L か Cmd+I か？」と迷う。

Alibaba Cloud - 開発者向けクラウドの第一候補、Lighthouse サーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

3 ステップ、5 秒で決める。

判断フロー

ステップ 1：何ファイル触る？

• 1 ファイル → 次へ
• 2 ファイル以上 → Composer

ファイルをまたぐなら Composer。シンプル。

ステップ 2：質問か、修正か？

• 質問（学習・理解・デバッグ）→ Chat
• 修正（生成・変更・リファクタ）→ Composer

アドバイザーか、実装チームか。

ステップ 3：変更規模は？

• 小さく（数行）→ Chat + Cmd+K
• 大きく（モジュール全体）→ Composer

変数名やコメント程度なら Cmd+K で十分。Composer まで要らない。

Chat が向く 4 つの場面

場面 1：サッと質問

あなた：「このコード、バグある？」
Chat：「12 行目で配列外参照です」

修正不要、確認だけ。Chat が最適。

場面 2：学習・理解

あなた：「このアルゴリズムの原理を説明して」
Chat：「クイックソートです。核心は…」

場面 3：単一ファイルのデバッグ

あなた：「この関数を最適化して」
Chat：「memoization で結果をキャッシュできます…」

自分で直せばいい。Composer の全自動は不要。

場面 4：コードレビュー

あなた：「潜在的な問題は？」
Chat：「15 行目で null 未処理。28 行目にメモリリークのリスク…」

Composer が向く 4 つの場面

場面 1：新機能開発 — 前述の通り。

場面 2：コードリファクタリング — 大規模な構造変更：

• 大ファイルの分割
• 小ファイルの統合
• ディレクトリ再編
• 命名規則の統一

Chat では無理。

場面 3：依存関係の移行 — 例：

• axios → fetch
• moment.js → dayjs
• styled-components → Tailwind CSS
• Redux → Zustand

数十ファイル——Composer の独壇場。

場面 4：一括修正 — 例：

• console.log → logger
• var → const
• クラスコンポーネント → 関数コンポーネント

3 つの比較事例

事例 1：API 呼び出し方式の変更

タスク：axios をすべて fetch に。
ファイル：15 個。

Chat：1 ファイルずつ。漏れやすい。

Composer：@src/api すべての axios を fetch に変更 の 1 指示で一括修正。diff を確認するだけ。

結論：Composer

事例 2：関数のデバッグ

タスク：合計価格計算のバグ特定。
ファイル：1 個。

Chat：コードを貼れば即答。「12 行目の税率が間違い。total * 0.1 です」

Composer：分析待ち、修正待ち、適用待ち——重すぎる。

結論：Chat

事例 3：ユーザー権限システム

タスク：RBAC 実装。
ファイル：10 個以上。

Chat：ほぼ不可能。

Composer（Agent）：「ロールベースの権限を実装。管理者は CRUD、一般ユーザーは閲覧のみ」と伝えるだけ。

結論：Composer（Agent）

Composer の正しい始め方

初回設定（3 ステップ）

Cursor を入れたら、Composer を触る前に設定から。

ステップ 1：モデル選択

Composer には Claude 3.7 Sonnet を推奨。

理由：

• 推論力が高い——複数ファイルの関係を理解できる
• エラー率が低い
• 一緒に直すべきファイルを把握しやすい

o1 / o1-mini は Composer 非対応。勝手に別モデルに切り替わり、期待外れになりやすい。

ステップ 2：Agent モード（任意）

Cursor Settings → Beta → Agent。

有効にすると：

• シェルコマンド（npm install、git status）
• コードベース検索（Cmd+Enter）
• ファイル作成・削除
• プロジェクト構造の分析

道具箱を持たせた状態——「やりすぎ」もしやすい。制御は後述。

ステップ 3：料金

• 無料版：Composer 制限あり（1 日数回）
• Pro 版：月 500 回 premium リクエスト——十分
• Business 版：無制限

ヘビーユーザーは Pro がおすすめ。私は月 300〜400 回程度。

UI の見方

┌─────────────────────────────────┐
│  Composer  [Normal] [Agent]     │  ← モード切替
├─────────────────────────────────┤
│  📝 入力（要件を書く）            │
│  @ ファイル/フォルダ/コード参照   │
├─────────────────────────────────┤
│  💬 会話履歴                     │
│  📄 ファイル diff プレビュー      │
│  ✅ Accept  ❌ Reject            │
└─────────────────────────────────┘

右上で Normal / Agent を切り替え。

下の diff プレビューが重要。Accept All は絶対にしない。後で詳述。

@ 参照の使い方

@ は Composer の核心。

@Files：特定ファイル

@src/components/Header.tsx
このコンポーネントをレスポンシブ対応に

@Folders：フォルダ全体

@src/utils
このユーティリティを機能別にファイル分割してリファクタ

@Code：コードブロック

コードを選択して Cmd+I：

@[選択した関数]
この関数のパフォーマンスを最適化

@Web：Web コンテンツ

@https://docs.react.dev/reference/react/useEffect
React 公式のベストプラクティスに従ってこの effect をリファクタ

公式ドキュメントに沿わせるとミスが減る。よく使う。

@Docs：プロジェクトドキュメント

@README.md
ドキュメントに従ってこの機能を実装

@Codebase：コードベース検索

Cmd+Enter：

localStorage を使っている箇所をすべて IndexedDB に変更

Agent モードならプロジェクト全体を検索して一括修正。

Normal vs Agent

Normal モード：

• 明確なタスク向き
• 指定ファイルだけ修正
• 制御しやすい
• 速い
• トークン消費が少ない

Agent モード：

• 推論が必要な複雑タスク向き
• 自律的に検索・コマンド実行・ファイル作成
• 賢い反面、想定外の変更も
• 遅い
• トークン消費が多い

選び方：

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

単純 → Normal（スタイル変更、エラー処理追加など）。

複雑なリファクタ → Agent（Redux → Zustand、権限システムなど）。

迷ったら Normal から。ダメなら Agent。

私は 80% Normal、20% Agent。Normal で足りることが多い。

複数ファイル編集の 5 つの黄金律

ここが本題。踏んできた落とし穴からまとめた 5 ルール。守れば 90% の事故を防げる。

ルール 1：タスク分割

❌ 悪い例：

「プロジェクト全体を TypeScript 化し、パフォーマンス最適化とテスト追加も全部やって」

Composer が混乱する。2 時間ロールバックの始まり。

✅ 正しい例——4 回に分ける：

1 回目：「src/utils 配下をすべて TypeScript に」
2 回目：「utils にユニットテストを追加」
3 回目：「Header コンポーネントのパフォーマンス最適化」
4 回目：「API 呼び出しをリファクタし、エラー処理を統一」

小さなゴールごとに git commit。明確で、戻しやすい。

なぜ分割？

• AI の理解ズレを防ぐ
• diff が小さく、レビューしやすい
• ロールバックが楽
• トークン節約

経験則：1 回の Composer 会話は 10 ファイル以内。超えたら分割。

ルール 2：範囲を明示

@ 参照でファイル範囲を指定。

@src/components/User
@src/types/user.ts
@src/api/user.ts

ユーザー関連 API を RESTful から GraphQL に変更

AI は「この 3 箇所だけ」と理解する。

範囲を曖昧にすると、サードパーティまで触ってプロジェクトが壊れる。

メリット：

• 誤修正を防ぐ
• 変更が制御可能
• 想定外が減る

Composer を開いたら、最初に @ 参照——習慣にする。

ルール 3：1 ファイルずつレビュー

Composer 完了後、Accept All は絶対禁止。

20 ファイルをワンクリックで適用——気持ちいい。でも危険。

失敗談：

「すべての console.log をカスタム logger に置換して」と Composer に頼んだ。30 ファイル修正。見もせず Accept All。

結果：

• サードパーティの console.log まで消えた
• デバッグコードも誤削除
• プロジェクトが起動しなくなった

ロールバックと手動修復に 1 時間。

正しい手順：

1. 各ファイルの diff を開く
2. 1 行ずつ確認
3. 問題なければ個別 Accept
4. 問題があれば Reject して要件を書き直す

20 ファイルなら 20 回。遅い。でも 90% の事故を防げる。

今の習慣：Composer 完了 → コーヒーを淹れる → 座ってゆっくりレビュー。

ルール 4：こまめに commit

小タスクが終わったら即 git commit。

git add .
git commit -m "feat: ユーザー API を GraphQL に移行"

なぜ重要？

Composer の会話は保存されない。10 ファイル直して commit なしでページが固まったら——何をどこまで直したか分からない。

各ステップで commit すれば：

• git reset --hard HEAD で戻せる
• git log で追跡できる
• 会話が消えてもコードは残る

私のリズム：Composer → diff レビュー → Accept → commit。筋肉記憶レベル。

ルール 5：コンテキストを維持

問題：

Composer は会話を保存しない。「さっきのリファクタの続きを」と言っても「何の話？」と返される。

対策：

対策 1：重要な指示はスクショ

複雑タスクの前に Composer への指示をスクショ。回線が切れても思い出せる。

対策 2：Chat で計画 → Composer で実行

Chat：
あなた：「axios を fetch に移行したい。注意点は？」
AI：「エラー処理、インターセプター、型定義に注意…」
あなた：「移行計画を書いて」
AI：「ステップ 1… 2… 3…」

計画に沿って Composer で実行。Chat の計画は残る。

対策 3：README に記録

## 2026-01-10 リファクタ記録
- タスク：axios → fetch 移行
- Composer 指示：「axios 呼び出しをネイティブ fetch に。エラー処理ロジックは維持」
- 対象：src/api/*.ts
- 結果：15 ファイル移行完了

Composer の 7 つの落とし穴と回避策

踏んだ穴を全部書く。これを避ければ大丈夫。

落とし穴 1：会話履歴が保存されない

リロードで消える。タブを閉じた、Cursor が落ちた——全部消える。

回避策：
✅ 重要指示はスクショ
✅ Chat で先に計画
✅ commit message に意図を書く
✅ 1 会話 10 ファイル以内に分割

落とし穴 2：ファイル更新の中断

途中でフリーズ。ネットワーク、AI サービス、PC の問題など。

一部だけ直った中途半端な状態に。

回避策：
✅ 修正前に git commit
✅ ネットワークを安定させる（VPN 不安定なら避ける）
✅ タスクを小さく
✅ git diff で実際の変更を確認

2 回経験。1 回目は commit なしで 2 時間。2 回目は git reset 一発。

落とし穴 3：モデルの自動切り替え

o1 などは Composer 非対応。選んだつもりが別モデル——結果が期待外れ。

回避策：
✅ Claude 3.7 Sonnet 固定
✅ 右上のモデル名を確認
✅ Settings でデフォルト設定

落とし穴 4：コンテキスト消失

1 回目：「ユーザー API を GraphQL に」
2 回目：「続けて、コメント API も」

→「ユーザー API って何？」

回避策：
✅ 毎回 @ 参照をやり直す
✅「前回の変更に基づいて、続けて…」と明記
✅ 必要なら新規会話で背景から説明

毎回「初対面」だと思って背景を書く——今の習慣。

落とし穴 5：ファイル検索の失敗

Cmd+Enter で「axios を使っている箇所を全部見つけて」→「見つかりません」。

実際は 15 ファイルで使っている。

回避策：
✅ @Files で明示指定
✅ .cursorrules / .gitignore を確認
✅ 大規模プロジェクトはモジュール単位に分割

@Codebase 検索は大規模だと当てにならない。@Files が確実。

落とし穴 6：Agent モードの暴走

Agent オンで AI が勝手に：

• 不要ファイルを作成
• 重要コードを削除
• 想定以上に変更

「ユーザーモジュールをリファクタ」→ src/user ごと削除再構築、など。

回避策：
✅ まず Normal で試す
✅ 依存移行など明確なタスクだけ Agent
✅ diff を 1 ファイルずつ確認

🔥 需要のない製品に3ヶ月も無駄にするな！少額の予算で Adsterra を使い、SaaS の訴求を今すぐ検証 ➡️

今すぐ検証 →広告

落とし穴 7：ディスク容量不足

Composer は一時ファイルを作る。容量不足で「ディスク容量不足」——修正が中途半端に。

回避策：
✅ node_modules、dist を定期クリーンアップ
✅ 5 GB 以上の空きを確保
✅ df -h で確認

1 回だけ踏んだ。エラーメッセージが分かりにくく、半日かかった。

実践事例：axios から fetch API への移行

理論はここまで。実践を見よう。

背景：

• プロジェクト：Next.js ブログ
• タスク：axios をネイティブ fetch に
• ファイル：15 個の API ファイル
• 手動なら 2 時間、Composer なら 20 分

ステップ 1：Chat で計画

Composer の前に Chat で議論。

私：axios をすべて fetch に置き換えたい。注意点は？

Chat：
1. fetch は response.ok を手動チェックが必要
2. 4xx/5xx はデフォルト reject されない
3. Content-Type は手動設定
4. インターセプターはカスタム関数で

先に fetchWrapper を作るのがおすすめ。

方針が固まった。ユーティリティ → 一括置換。

ステップ 2：fetchWrapper 作成

Cmd+I：

@src/utils

fetchWrapper.ts を作成。axios 風 API ラッパー：
- JSON 自動処理
- 統一エラー処理
- インターセプター対応
- 既存 axios 呼び出しと互換

数秒で fetchWrapper.ts ができた。

• ✅ 型定義 OK
• ✅ エラー処理 OK
• ✅ API 設計 OK

Accept → git commit -m "feat: add fetchWrapper utility"

ステップ 3：モジュール単位で移行

15 ファイル一発はしない。posts と comments から：

@src/api/posts.ts
@src/api/comments.ts
@src/utils/fetchWrapper.ts

posts と comments の API を axios から fetchWrapper に。関数シグネチャとエラー処理は維持。

3 ファイル修正。

ステップ 4：diff レビュー

posts.ts：

• import axios → import { fetchWrapper } ✅
• axios.get() → fetchWrapper.get() ✅
• エラー処理維持 ✅
• シグネチャ不変 ✅

Accept。

comments.ts： 同様 ✅ Accept。

fetchWrapper.ts： 参照 OK ✅

ステップ 5：テスト

npm run dev

• 記事リスト ✅
• 記事詳細 ✅
• コメント投稿 ✅
• コメント削除 ✅

git commit -m "feat: migrate posts and comments API to fetch"

ステップ 6：残りモジュール

users、auth、settings を同じ手順で。各モジュールごとにレビュー・テスト・commit。

25 分で 15 ファイル完了。

つまずき

つまずき 1：node_modules の axios まで修正

@Files で範囲指定しなかった結果。

→「src 配下のみ。node_modules は触らない」と再指示。

つまずき 2：エラー処理の消失

fetch は axios とエラー処理が違う。

→「エラー処理ロジックを維持。response.ok を手動チェック」と明記。

つまずき 3：型定義不足

TypeScript エラー。

→ Chat で型定義を生成し、Cmd+K で fetchWrapper.ts に適用。

成果

✅ 15 ファイル移行完了
✅ 全 API 正常
✅ 所要 25 分（デバッグ含む）
✅ コードレビュー問題なし
✅ パッケージサイズ削減（axios 30 KB 分）

手動 2 時間 → Composer 25 分。5 倍。

まとめ

1. 複雑タスクは Chat で計画
2. 段階実行、各ステップで commit
3. @ 参照で範囲明示
4. diff を 1 ファイルずつ確認
5. テストしてから次へ

すべての Composer タスクに使える。

結論

Composer を使いこなしてから、開発効率は少なくとも 3 倍になった。

以前は複数ファイルの修正でコピー＆ペースト、ミス、漏れ——疲れた。

今は Composer に 1 指示。AI が対象ファイルを特定して一括修正。diff を確認して Accept。10 分。

5 つの原則：

1. 複数ファイル → Composer — Chat は時間の無駄
2. タスクは小さく — 1 会話 10 ファイル以内
3. 1 ファイルずつレビュー — Accept All 禁止
4. こまめに commit — 会話は消えてもコードは残す
5. コンテキスト維持 — スクショ、Chat 計画、README 記録

ショートカット 2 つ：

• Cmd/Ctrl + L → Chat（質問）
• Cmd/Ctrl + I → Composer（修正）

5 秒判断法：

何ファイル？
 → 1 個 → 質問？修正？
    → 質問 → Chat
    → 修正 → 規模は？
       → 小 → Chat + Cmd+K
       → 大 → Composer
 → 2 個以上 → Composer

Composer を恐れない。

最初は「賢すぎて制御できない」と感じるかもしれない。

でも上のルールを守れば、非常に制御しやすく、使いやすい。

今すぐ試す：

1. Cursor を開き Cmd+I
2. 小さなタスクで練習（変数の一括リネーム、コードスタイル統一など）
3. この記事の 5 ルールと 7 つの落とし穴を保存
4. 複数ファイルの修正が必要になったら、真っ先に Composer を思い出す

Chat ばかり使わない。

Composer こそ Cursor の核心。

使えば、その強さが分かる。