Cursor Composer 完全ガイド：複数ファイル編集テクニックと実践事例

正直なところ、私は Cursor を3ヶ月使ってようやく、自分がそれを「無駄遣い」していたことに気づきました。

以前は機能を修正する際、コンポーネント、API、型定義、テスト、設定の5つのファイルを修正する必要がありました。私は Chat で一つずつ質問し、コードを一つずつコピー＆ペーストしていました。マウスでファイルを行き来し、指は Cmd+C と Cmd+V の間で反復横跳び。疲れました。

ある日、通りかかった同僚が私の操作を見て、画面を3秒見つめて言いました。「なんで Composer を使わないの？」

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

「え？」

「Cmd+I のあのフローティングウィンドウだよ。一言で要件を伝えれば、AI が修正すべきファイルを自動識別して、全部直してくれるよ。」

私は呆然としました。

彼は実演してくれました。Composer を開き、関連ファイルをいくつか @ で引用し、「このユーザーログインロジックをメール認証対応に変更して」と入力して Enter。AI は数秒考え、コンポーネント、API、型定義を一気に修正しました。10分で完了です。

私は以前、1時間かけていました。

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

Composer とは？なぜ必要なのか

Composer vs Chat の本質的な違い

例え話をしましょう。

Chat は隣に座って質問に答えてくれる AI アドバイザーのようなものです。「このコードをどう最適化する？」と聞けば提案をくれますが、実際に修正するのはあなたです。

Composer は AI 施工業者です。「このビルの窓をすべて掃き出し窓に変えて」と言えば、直接作業を行い、終わったら「完了しました、確認してください」と言います。

これが本質的な違いです。一方はアドバイザー、もう一方は施工業者です。

具体的な比較は以下の表をご覧ください：

「対話履歴が保存されない」のを見ましたか？これは私が踏んだ最大の落とし穴です。後ほど回避方法を詳しく解説します。

Composer の3つの核心能力

能力 1：ファイル間の理解

Chat は現在開いているファイルしか見えませんが、Composer はプロジェクト全体を見ることができます。

例えば、「ユーザーログイン機能を追加して」と言うと、Chat は「具体的にどのファイルを修正しますか？」と聞きますが、Composer は直接「以下の5つのファイルを修正する必要があります：Login.tsx, auth.ts, user.types.ts, api/auth.ts, App.tsx」と教えてくれます。

コンポーネント、型定義、API、ルーティングがどこにあるかを知っており、すべて修正してくれます。

能力 2：プロジェクトレベルの修正

Chat でコードを修正する場合、手動でコピー＆ペーストする必要があります。Composer は修正後、直接ファイルに適用し、あなたは Accept または Reject をクリックするだけです。

この違いは、Chat がリフォームの図面を渡すだけなのに対し、Composer はリフォームを完了させて検収を求めるようなものです。

能力 3：インテリジェントな推論（Agent モード）

Agent モードを有効にすると、Composer は以下のことができます：

• シェルコマンドの実行（例：npm install, git status）
• コードベース全体の検索（特定の関数を使用している箇所をすべて洗い出す）
• 依存関係の自律分析
• ファイルの作成または削除

Agent モードは施工業者に現場監督をつけるようなもので、自分で判断し、道具を探せます。しかし、「過剰な施工」もしやすいため、制御方法を後述します。

Composer を使うべき3つのシーン

シーン 1：新機能開発（複数ファイルに関わる）

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

Chat のやり方：

1. Chat に修正すべきファイルを聞く
2. Chat が5つのファイルをリストアップ
3. ファイルを一つずつ開く
4. Chat で「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 モードをオンにすれば、AI が依存関係を分析し、ファイルを修正し、動作テストまで行います。20分で完了です。

シーン 3：一括修正

要件：エラー処理方法を統一し、すべての API 呼び出しに try-catch を追加する。

Chat のやり方：一つずつファイルを修正しますが、見落としやすく、どこまで修正したか覚えておく必要があります。

Composer のやり方：

@src/api

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

一度に15ファイルを処理できます。

Composer vs Chat：5秒意思決定法

Composer と Chat の違いは分かりましたが、実際にコードを書くときに「Cmd+L を押すべきか、Cmd+I を押すべきか？」と迷うことがあります。

3ステップで判断し、5秒で決めるフローを紹介します。

意思決定フロー

ステップ 1：いくつのファイルが関わるか？

• 1ファイル → 判断継続
• 2ファイル以上 → Composer

これだけです。ファイル間なら Composer です。

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

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

Chat はアドバイザー、Composer は施工業者。覚えましたか？

ステップ 3：修正範囲は大きいか？

• 小規模修正（数行のコード）→ Chat + Cmd+K
• 大規模修正（モジュール全体）→ Composer

単なる変数名の変更やコメント追加なら、Cmd+K で十分です。Composer を動かすまでもありません。

Chat に適した4つのシーン

シーン 1：クイック Q&A

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

即答です。コード修正は不要で、確認したいだけ。Chat が最適です。

シーン 2：学習と理解

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

新しい知識を学ぶのは Chat の得意分野です。丁寧に説明し、例も挙げてくれます。

シーン 3：単一ファイルデバッグ

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

自分で修正すればいいので、Composer の全自動機能は不要です。

シーン 4：コードレビュー

あなた：「ここに潜在的な問題はある？」
Chat：「15行目で null を処理していません。28行目にメモリリークのリスクがあります...」

コードレビューにおいて、Chat は多くの問題を見つけてくれます。

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：ファイルごとの操作が必要で、見落としやすい。修正箇所を覚えておくのが大変。

Composer：一本の指令 @src/api すべての axios を fetch に変更 で、AI が一括修正し、diff を確認するだけ。

結論：Composer

事例 2：関数のデバッグ

タスク：合計価格計算関数のバグを見つける。
関与ファイル：1個。

Chat：コードを貼れば即答。「12行目の税率計算が間違っています。total * 0.1 にすべきです」。

Composer：Composer を開いて、分析を待って、修正を待って、適用を待って…重すぎます。時間の無駄。

結論：Chat

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

タスク：RBAC 権限管理の実装。
関与ファイル：10個以上（コンポーネント、ミドルウェア、データベース、API）。

Chat：ほぼ不可能。Chat で一つずつ聞き、一つずつ修正し、論理的一貫性を自分で保証しなければなりません。

Composer（Agent モード）：AI が全体アーキテクチャを理解した後、自動的にミドルウェアを作成し、API を修正し、コンポーネントを更新し、権限チェックを追加します。「ロールベースの権限システムを実装して。管理者は CRUD 可能、一般ユーザーは閲覧のみ」と伝えるだけです。

結論：Composer（Agent）

Composer の正しい始め方

初回設定（3ステップ）

Cursor をインストールしたら、すぐに Composer を使わず、まずは設定しましょう。

ステップ 1：モデルの選択

Composer では Claude 3.7 Sonnet の使用を推奨します。

理由は？

• 推論能力が高い：複雑な複数ファイルの関係を理解できる
• エラー率が低い：コードの修正ミスが少ない
• 複数ファイル理解が優秀：一緒に修正すべきファイルが分かる

決して o1 や o1-mini を使わないでください。Composer 機能をサポートしていません。Cursor が勝手に他のモデルに切り替えてしまい、期待通りの結果になりません。

ステップ 2：Agent モードの有効化（任意）

設定を開く：Cursor Settings → Beta → Agent。

有効にすると、Composer は以下のことができます：

• シェルコマンド実行（npm install, git status）
• コードベース検索（Cmd+Enter、特定関数の使用箇所を全検索）
• ファイル作成/削除
• プロジェクト構造の自律分析

Agent モードは AI に道具箱を持たせるようなもので、自分で作業できます。しかし「過剰施工」もしやすいため、後で制御方法を説明します。

ステップ 3：料金ルールの理解

• 無料版：Composer 機能に制限あり、1日数回のリクエスト
• Pro 版：月500回の premium リクエスト、十分使えます
• Business 版：無制限

ヘビーユーザーなら Pro 版を推奨します。私自身 Pro を使っていて、月300-400回程度利用します。

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

15%割引を入手 →広告

インターフェース構成の解説

Composer の画面は以下のようになっています：

┌─────────────────────────────────┐
│  Composer  [Normal] [Agent]     │  ← モード切替
├─────────────────────────────────┤
│  📝 入力ボックス（要件記述）      │
│  @ ファイル/フォルダ/コード引用   │
├─────────────────────────────────┤
│  💬 対話履歴                     │
│  📄 ファイル diff プレビュー      │
│  ✅ Accept  ❌ Reject            │
└─────────────────────────────────┘

右上で Normal と Agent モードを切り替えられます。

下の diff プレビューは重要です。各ファイルがどう変わったか確認できます。絶対に直接 Accept All しないでください。この落とし穴については後述します。

@ 引用機能の活用

@ 記号は Composer の核心機能です。様々なものを引用できます。

@Files：特定ファイルの引用

@src/components/Header.tsx
このコンポーネントをレスポンシブデザインに変更して

AI はこの1ファイルだけを修正すべきと知り、他をいじりません。

@Folders：フォルダ全体の引用

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

AI はこのフォルダ以下の全ファイルを読み、全体構造を理解した上でリファクタリングします。

@Code：コードブロックの引用

コードを選択してから Cmd+I を押すと、自動的に引用されます：

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

局所的な最適化に最適です。

@Web：Web コンテンツの引用

@https://docs.react.dev/reference/react/useEffect
React 公式ドキュメントのベストプラクティスに従い、この effect をリファクタリングして

AI はウェブページを読み、ドキュメントに従って修正します。私はよくこの機能を使い、公式ドキュメント通りにコードを修正させることでミスを防いでいます。

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

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

プロジェクトに仕様書がある場合、@ で引用すれば AI は仕様に従います。

@Codebase：コードベース全体の検索

Cmd+Enter を押し、入力します：

localStorage を使用している箇所をすべて見つけ、IndexedDB に変更して

Agent モードでは、AI がプロジェクト全体を検索し、関連コードを見つけ出して一括修正します。

Normal vs Agent モード

2つのモードの違いは何でしょうか？

Normal モード：

• 明確なタスクに適している
• AI は指定されたファイルのみ修正する
• 制御しやすく、予期せぬファイル変更がない
• 速度が速い
• トークン消費が少ない

Agent モード：

• 複雑で推論が必要なタスクに適している
• AI が自律的にコード検索、コマンド実行、ファイル作成を行える
• スマートだが、予想外の変更をする可能性がある
• 速度が遅い
• トークン消費が多い

選択のアドバイス：

単純タスク → Normal。例：「コンポーネントのスタイル変更」「エラー処理の追加」。

複雑なリファクタリング → Agent。例：「Redux から Zustand への移行」「権限システムの実装」。

不確かな場合 → まず Normal を試し、ダメなら Agent。

私自身、時間の80%は Normal、20%は Agent を使います。Normal で十分なことが多く、Agent は重すぎます。

複数ファイル編集の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箇所だけ修正し、他は触らない」と理解します。

範囲を明確にしないと？AI が勝手に他のファイルを修正する可能性があります。例えば「API 呼び出し方法を統一して」と言うと、AI がサードパーティライブラリの API まで修正し、プロジェクトが壊れることがあります。

メリット：

• AI が他ファイルを誤修正しない
• 変更が制御可能
• 予期せぬ事態が減る

私は Composer を使う際、最初の一歩として必ず関連ファイルを @ 引用する習慣をつけています。

ルール 3：個別レビュー

Composer の修正後、絶対に直接 Accept All をクリックしないでください。

Accept All は魅力的です。AI が20ファイルを修正し、ワンクリックで適用完了するのは気持ちいいです。

しかし…

実際の失敗談：

一度、Composer に「すべての console.log をカスタム logger に置き換えて」と頼みました。

Composer は30ファイルを修正しました。

私は見もせずに Accept All しました。

結果：

• サードパーティライブラリの console.log まで削除された
• 重要なデバッグコードも誤って削除された
• プロジェクトが動かなくなった

ロールバック、調査、手動修正に1時間かかりました。

正しいフロー：

1. 各ファイルの diff プレビューをクリック
2. 変更内容を一行ずつチェック
3. 問題なければ個別に Accept
4. 問題があれば即座に Reject し、要件を再記述

はい、時間はかかります。20ファイルの修正なら20回の diff 確認が必要です。しかし、これで90%の事故を防げます。

現在の私の習慣：Composer 完了後、コーヒーを淹れて、座ってゆっくりレビューします。焦りは禁物です。

ルール 4：こまめなコミット

小さなタスクを完了するたびに、即座に git commit します。

# Composer での修正完了後
git add .
git commit -m "feat: ユーザー API を GraphQL に移行"

なぜ重要か？

Composer の対話履歴は保存されません。ページをリロードすると消えます。

もし10ファイルを修正して commit せず、ページが固まって対話が消えたら…何を修正したか、どこまで進んだか分からなくなります。最初からやり直しです。

しかし各ステップで commit していれば：

• 問題が起きても簡単にロールバック可能（git reset --hard HEAD）
• 各変更を追跡可能（git log で変更履歴が見える）
• Composer の対話が消えても怖くない（コードは保存済み）

私のリズム：Composer 完了 → diff レビュー → Accept → git commit。これを筋肉反射レベルで定着させましょう。

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

問題：

Composer は対話履歴を保存しません。ページをリロードすると以前の対話は消えます。

「さっきのリファクタリングの続きをして」と言っても、AI は「何のリファクタリング？何の話か分かりません」と答えます。

解決策：

案 1：重要な対話はスクショ保存

複雑なタスクの開始前に、Composer の指令をスクショしておきます。途中で回線が切れても、スクショを見て何をしようとしていたか思い出せます。

案 2：複雑なタスクは Chat で計画し、Composer で実行

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

Chat の対話履歴は保存されます。Chat で AI と案を議論し、確定してから Composer で実行します。

例えば：

Chat 対話：
あなた：「axios を fetch に移行したい、注意点は？」
AI：「エラー処理、インターセプト、型定義に注意が必要です...」
あなた：「よし、移行計画を書いて」
AI：「ステップ1... ステップ2... ステップ3...」

そして計画に従い、一歩ずつ Composer で実行します。Chat の計画は残っているので、Composer が消えても大丈夫です。

案 3：プロジェクトの README に変更意図を記録

README に「リファクタリング記録」セクションを設けます：

## 2026-01-10 リファクタリング記録
- タスク：axios から fetch への移行
- Composer 指令："すべての axios 呼び出しをネイティブ fetch API に変更し、同じエラー処理ロジックを維持する"
- 関与ファイル：src/api/*.ts
- 結果：15ファイルの移行完了

後でプロジェクトを見返したとき、なぜそう修正したかが分かります。

Composer の7つのよくある落とし穴と回避ガイド

私が踏んだすべての落とし穴をリストアップします。これを避ければ大丈夫です。

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

問題：

Composer の対話はリロードで消えます。

修正途中でページが固まったり、タブを誤って閉じたり、Cursor がクラッシュしたら…以前の対話は全滅です。

回避策：

✅ 重要指令はスクショ保存（スマホ撮影でも可）
✅ Chat で先に計画し、思考を記録
✅ git commit message で毎回修正意図を記録
✅ 複雑なタスクは複数回の小さな対話に分割（1回10ファイル以内）

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

問題：

Composer が修正途中で固まる。

ネットワークの揺らぎ、AI サービスの不調、PC ファンの騒音（冗談です）などが原因です。

結果：一部のファイルは修正され、一部は未修正。プロジェクトは半端な状態になります。

回避策：

✅ 修正前に git commit（問題あれば即ロールバック）
✅ ネットワーク安定性の確認（Composer は回線要求が高い、VPN 不安定なら使わない）
✅ タスクを小さく分割（ファイル数が少なければ更新も速く、中断しにくい）
✅ git diff で実際の変更を確認（どのファイルが本当に変わったか見る）

私は更新中断に2回遭遇しました。1回目は commit しておらず、手動修復に2時間。2回目は commit 済みで、git reset 一秒で解決しました。

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

問題：

一部のモデル（o1 など）は Composer をサポートしていません。

o1 を選んだつもりが、Cursor が自動的に他モデルに切り替えていることがあります。o1 を使っていると思っていても、実際は GPT-4o だったりして、結果が期待外れになります。

回避策：

✅ Claude 3.7 Sonnet 固定で使用（Composer のベストパートナー）
✅ 右上のモデル名を確認（選んだつもりにならない）
✅ Cursor Settings でデフォルトモデルを設定

私は今 Claude 3.7 Sonnet しか使いません。安定していて信頼でき、エラー率が低いです。

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

問題：

Composer で連続対話する場合：

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

結果、AI が「ユーザー API って何？何の話？」となることがあります。

コンテキストが失われています。

回避策：

✅ 毎回関連ファイルを再度 @ 引用する
✅ 「前回の変更に基づいて、続けて…」と明確に記述する
✅ 必要なら新規対話を開始し、再度背景を説明する

現在の私の習慣：毎回が初対面だと思って、背景をしっかり説明します。

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

問題：

Cmd+Enter で引用し、「@Codebase axios を使っている箇所をすべて見つけて」と入力。

AI が「見つかりませんでした」と言う。

しかし実際には15個のファイルで使われている。

回避策：

✅ @Files でファイルを明確に指定（検索に頼らない）
✅ .cursorrules と .gitignore を確認（特定ファイルが無視されていないか）
✅ 大規模プロジェクトではモジュールごとにタスク分割（AI に全プロジェクトを検索させない）

@Codebase 検索は大規模プロジェクトではあまり当てになりません。私は @Files で明確に指定するようにしています。

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

問題：

Agent モードをオンにしたら、AI が勝手に：

• 不要なファイルを作成した
• 重要だと思っていたコードを削除した
• 予想以上に改変した

例えば「ユーザーモジュールをリファクタリングして」と言ったら、AI が src/user ディレクトリごと削除して作り直した、など。

回避策：

✅ 複雑なタスクはまず Normal モードで試す
✅ Agent モードは明確なリファクタリングタスク（依存関係移行など）に適している
✅ diff を逐一確認し、不合理な変更は即座に Reject

Agent モードは強力ですが危険も伴います。私は（依存関係移行のような）非常に明確なタスクでのみ使用します。

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

問題：

Composer は一時ファイルを作成します。

ディスク容量不足だと更新に失敗します。修正途中で「ディスク容量不足」エラーが出ます。

回避策：

✅ node_modules, dist 等の一時ディレクトリを定期的にクリーンアップ
✅ 5GB以上の空き容量を確保
✅ df -h でディスク使用率を確認

この罠は1回しか踏んでいませんが、非常に隠蔽されていました。エラーメッセージが不明瞭で、原因判明まで半日かかりました。

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

理論は十分です。実戦事例を見てみましょう。

事例背景：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

• プロジェクト：Next.js ブログシステム
• タスク：すべての axios 呼び出しをネイティブ fetch API に変更
• 関与ファイル：15個の API ファイル
• 予想時間：手動なら2時間、Composer なら20分

Composer を使ってこのタスクを完遂するステップを実演します。

ステップ 1：Chat で計画

Composer を開く前に、Chat で AI と議論します。

私：プロジェクトの axios をすべて fetch API に置き換えたいです。注意点は？

Chat：
1. fetch のエラー処理は axios と異なり、response.ok を手動チェックする必要があります
2. fetch はデフォルトで 4xx/5xx を reject しないため、追加処理が必要です
3. Content-Type を手動設定する必要があります
4. リクエストインターセプターはカスタム関数で実装する必要があります

まず fetchWrapper ユーティリティ関数を作成することを推奨します。

なるほど。Chat が方針をくれました。まずユーティリティ関数を書き、それから一括置換します。

ステップ 2：fetchWrapper ツールの作成

Cmd+I で Composer を開きます：

@src/utils

fetchWrapper.ts ファイルを作成し、axios に似た API ラッパーを実装してください：
- JSON の自動処理
- 統一されたエラー処理
- インターセプター対応
- 既存の axios 呼び出し方法との互換性

Enter。

Composer が数秒考え、fetchWrapper.ts を作成しました。コードはなかなか良いです。

チェックしました：

• ✅ 型定義が完全
• ✅ エラー処理ロジックが正しい
• ✅ API 設計が合理的

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 に変更してください。関数シグネチャとエラー処理ロジックは維持してください。

Enter。

Composer が作業を開始。3つのファイルを修正しました。

ステップ 4：diff のレビュー

これが最も重要なステップです。

ファイルを一つずつチェックします：

posts.ts：

• import axios が import { fetchWrapper } に変更 ✅
• axios.get() が fetchWrapper.get() に変更 ✅
• エラー処理ロジックは維持 ✅
• 関数シグネチャ不変 ✅

Accept。

comments.ts：

• 同様の変更、問題なし ✅

Accept。

fetchWrapper.ts：

• 適切にインポートされている ✅

ステップ 5：テスト

npm run dev

ブラウザを開き、posts と comments 機能をテスト：

• 記事リストのロード ✅
• 記事詳細の表示 ✅
• コメント投稿 ✅
• コメント削除 ✅

すべて正常。

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

ステップ 6：他モジュールの継続移行

ステップ3-5の手順で、残りを移行します：

• users モジュール
• auth モジュール
• settings モジュール

各モジュール修正完了ごとに、レビュー、テスト、commit。

25分ですべての15ファイルの移行が完了しました。

失敗体験

罠 1：Composer がサードパーティの axios も修正してしまった

最初は @Files で範囲を指定しなかったため、node_modules 内のコードまで修正されました。

解決：再度「src ディレクトリ下のコードのみ修正し、node_modules は変更しない」と記述。

罠 2：エラー処理ロジックの喪失

fetch のエラー処理が axios と違うため、単純置換で一部エラーが捕捉されなくなりました。

解決：指令で「同じエラー処理ロジックを維持し、手動で response.ok をチェックする」と明確化。

罠 3：型定義の欠如

TypeScript エラー発生。fetchWrapper の型定義が不完全でした。

解決：Chat で型定義を単独生成させ、Cmd+K で fetchWrapper.ts に適用。

最終成果

✅ 15ファイルすべての移行完了
✅ 全 API 機能正常
✅ 総所要時間：25分（デバッグ含む）
✅ コード review：問題なし
✅ パッケージサイズ削減：axios 30KB 分削除、原生 API 使用

手動なら2時間かかるところが、Composer なら25分。効率は5倍です。

経験のまとめ

1. 複雑なタスクはまず Chat で計画する
2. 段階的に実行し、各ステップ完了ごとに git commit する
3. ファイル範囲を明確に指定する（@ 引用使用）
4. diff を個別レビューし、意図しない変更を防ぐ
5. テストしてから次に進む

この5つの経験はすべての Composer タスクに適用できます。覚えておいてください。

結論

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

以前は複数ファイルにまたがる機能を修正する際、複数のファイルを行き来し、コピー＆ペーストし、ミスや見落としが多発していました。疲れました。

今は Composer の一指令で、AI が修正すべきファイルを自動識別し、すべて処理してくれます。私は diff をレビューして Accept するだけ。10分で終わります。

5つの核心原則を覚えてください：

1. 多ファイルに関わる → Composer
   ファイル間操作なら Chat は使わず、時間の無駄です。

2. タスクは小さく → 一度に変えすぎない
   1回の対話で10ファイル以内に。

3. 個別レビュー → 直接 Accept All しない
   遅くても事故るよりマシです。

4. こまめな提出 → 各ステップ完了で git commit
   Composer の対話は保存されませんが、コードは保存すべきです。

5. コンテキスト維持 → 重要対話はスクショ保存
   スクショ、Chat 計画、README 記録の三段階防御。

覚えるべきショートカットは2つ：

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

5秒意思決定法：

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

Composer を恐れないでください。

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

しかし何度か使えば、上記の法則に従う限り、Composer は非常に制御しやすく、使いやすいことが分かります。

行動提案：

今すぐ試してください：

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

Chat ばかり使わないでください。

Composer こそが Cursor の核心能力です。

使えばその強力さが分かります。

12 min read · 公開日: 2026年1月10日 · 更新日: 2026年2月4日

Easton

技術開発