ソフトウェアエンジニアがCursor Composerを使ってリポジトリ全体にわたる複数ファイルのコード変更を計画・生成・レビューする方法

Cursor Composerは、AIによるコーディング支援を単一ファイルの局所的なコード補完から、リポジトリ全体を俯瞰して自律的に協調動作する「エージェント型エンジニアリング」へと引き上げる強力な機能です。開発者は個別のファイルでコードを生成して手作業でコピー＆ペーストする代わりに、Composerを活用してレイヤーをまたぐ新機能実装やアーキテクチャの大規模リファクタリングを統括して実行できます。

しかし、プロジェクト全体に波及する変更には相応のアーキテクチャ破壊リスクが伴います。経験豊富なソフトウェアエンジニアは、Composer（ショートカット：Cmd + I または Ctrl + I）を利用する際、やみくもにコードを書かせるのではなく、「**計画（Plan）**によるコンテキストと制約の明確化」「**生成（Generate）**における自己修復を伴うアトミックな編集」「**レビュー（Review）**での詳細な差分確認とロールバック管理」という規律ある3段階のプロセスを実践しています。

準備段階：アーキテクチャの境界線とコンテキストの最適化

プロジェクト全体のアーキテクチャや命名規則をAIが把握していなければ、複数ファイルにまたがるコード生成は破綻します。エンジニアはComposerを起動する前に、ルール設定と参照シンボルを適切に構成します。

1. Cursor Rules（.cursor/rules）による開発標準の固定化

毎回プロンプトで同じコーディング標準や制約を指示する手間を省くため、チームは .cursor/rules/*.mdc（またはルートの .cursorrules）にプロジェクト規則を定義します。

• 常時適用ルール（Always-on）：TypeScriptの厳格モード、Python 3.12+ の文法仕様、統一エラーハンドリング規約、ユニットテストの命名基準などの基本方針を規定します。
• パス適合ルール（Glob-scoped）：対象ファイルのパスに応じて自動適用されるルールです。例えば src/api/**/*.ts にはZodを用いたリクエスト検証と構造化ログ出力を義務付け、src/components/**/*.tsx にはデザインシステムとアクセシビリティ（a11y）対応を必須化します。

これにより、Composerが新しいファイルを作成したり既存のモジュールを修正したりする際、プロジェクト本来の設計規約から逸脱するのを防ぎます。

2. @ シンボルによる精密なコンテキスト注入

AIに無関係なファイルまで過剰に読み込ませると、「コンテキストの肥大化（Context Bloat）」が起き、トークンの浪費だけでなく幻覚（ハルシネーション）を招きます。実践的なエンジニアは以下のシンボルを使い分けます。

• @codebase：リポジトリ全体に対してセマンティック検索を実行します。影響範囲が不確かな呼び出し元や、依存関係ツリーの調査に効果的です。
• @file および @folders：中核となる定義ファイル（例：@schema.prisma、@userService.ts、共通型定義ディレクトリ）を直接指定し、モデルに最も確実なコンテキストを付与します。
• @docs：利用している外部ライブラリやフレームワークの公式最新ドキュメントを参照させ、過去のバージョンに基づいた廃止済みAPIの使用を防ぎます。
• @git：最近のブランチ差分やコミット履歴を読み込ませ、現在進行中のPRの文脈を把握させます。

第1フェーズ：Plan Mode（Shift + Tab）による事前計画

データベースのスキーマ変更やAPI全体のリファクタリングなど、複数ファイルに波及するタスクでは、すぐにコードを生成させてはいけません。最初にPlan Modeを起動し、実装方針を固めます。

Plan Modeの起動と挙動

Composerの入力欄で Shift + Tab を押すと、Plan Modeに切り替わります。

1. コードベースの自動調査：エージェントが変更対象となるファイル群、依存関係、設定ファイルを巡回し、変更の影響範囲を洗い出します。
2. 仕様の明確化（質問機能）：エッジケースの挙動、後方互換性の維持方針、例外処理の基準に曖昧な点がある場合、Composerは勝手な推測をせず、エンジニアに質問を投げかけて確認します。
3. Markdown実装計画の生成：調査完了後、構造化された計画書が出力されます。
   • 新規作成・変更・削除が必要な具体的なファイルパス一覧
   • 実装手順（例：マイグレーションと型定義の作成 → サービス層の実装 → APIルーターの変更 → クライアントコンポーネントの更新）
   • 想定される破壊的変更と自動テストの検証方針

エンジニアによる計画の査定と修正

エンジニアは主設計者として出力されたMarkdown計画を確認し、不要なファイル変更を削ったり、命名方針を正したり、中間検証ステップ（例：「ステップ2完了時に型チェックを実行する」など）を追加します。双方が合意した段階で、初めて実装フェーズへ進みます。

第2フェーズ：協調的な複数ファイル編集と自己修復

計画が確定すると、Composerはコード生成に移行します。最新のCursorでは、Composerがエージェントとして動作し、複数レイヤーの同期編集とターミナルツールの連携を自律的に行います。

1. レイヤーをまたぐ同時生成

単一ファイルのエディタとは異なり、Composerは複数のシステム階層を整合性を保ちながら一括で変更できます。

• データ層：マイグレーションスクリプトを作成し、ORMモデルを更新
• サービス・ドメイン層：ビジネスロジックを実装し、公開インターフェースやメソッドシグネチャを整合
• APIルーティング層：新規エンドポイントの定義、認証ガードやミドルウェアの適用
• フロントエンド層：UIコンポーネント、データ取得カスタムフック、状態管理コードの更新
• テストスイート：連動するユニットテストやインテグレーションテストコードの追加

変更予定のファイル群はアクティブなキューにまとめられ、フローティング表示、サイドパネル、またはフルスクリーンエディタの画面で進行状況をリアルタイムに確認できます。

2. ターミナル実行による自己修復ループ（Self-Healing）

Composer Agentの特筆すべき強みは、ローカルターミナルコマンドを実行して結果を分析できる点です。

• 静的型チェックの実行：tsc --noEmit、mypy、cargo checkなどを自動実行し、インターフェース不一致によるコンパイルエラーを検出します。
• テストとLintの実行：npm test や pytest などのテストスイートを自律的に実行します。
• エラーログに基づく自動修復：テスト失敗やコンパイルエラーが発生すると、Composerはターミナルのスタックトレースを読み取り、原因となったファイルを特定して自律的に修正を施します。すべての検証をパスするまでこのループを反復します。

3. アトミックな作業単位への分割

熟練したエンジニアは、1つのプロンプトで数十ファイルもの変更を一気に要求しません。計画に沿ってマイルストーン単位で指示を出します。

• ステップ1：「新しいデータモデルを定義し、TypeScriptの型をエクスポートしてください」（型チェックで検証）
• ステップ2：「データベース操作のサービス層メソッドを実装し、単体テストを通してください」（テスト通過を検証）
• ステップ3：「APIルーターを改修し、フロントエンドの呼び出し箇所を同期してください」（全体ビルドで検証）

作業を細かく分けることで、コンテキストの精度を最高水準に保ち、その後の差分確認も容易になります。

第3フェーズ：差分レビュー・チェックポイント復元・検証

AI生成コードにおける最大のリスクは、例外処理の欠落やパラメータの誤認など、表面上は見えにくいリグレッション（機能退行）です。厳密なレビュー手順が不可欠となります。

1. 粒度の細かい差分（Diff）レビュー

Composerが生成を完了すると、マルチファイルの差分ビューが表示されます。

• ファイルごとの個別確認：左右に並べて表示されるSide-by-sideビューで、各ファイルの変更箇所を順に精査します。
• 個別採用（Accept）と却下（Reject）：「Keep All（すべて保持）」で一括確定するのではなく、ファイル単位またはコードブロック単位で個別に受け入れや拒否を選択します。
• 対話による追従修正：一部のコードに違和感がある場合、チャット内で直接指示を出します（例：「OrderService.ts では汎用のエラーではなく、共通の AppError を使ってください」）。Composerはそのファイルだけを即座に書き直します。

2. チェックポイント（Checkpoints）による安全なロールバック

Composerはコード生成を開始する直前に、ワークスペースの自動スナップショットである**チェックポイント（Checkpoint）**を作成します。

• 自己修復の過程でコードが混乱したり、技術的な選択を誤った場合は、いつでも Restore Checkpoint をクリックして前の状態へ戻せます。
• 会話履歴を保持したままファイルだけを生成前のクリーンな状態に復元できるため、プロンプトを練り直して即座に再試行できます。

3. Agent Reviewツールの活用

Gitでコミットする前に、Cursorに統合されている Agent Review 機能を実行します。

• Quick Review（簡易レビュー）：構文ミス、未使用のインポート、明らかなロジックの抜け漏れを素早くスキャンします。
• Deep Review（詳細レビュー）：変更セット全体を対象に深いセマンティック解析を実施し、複数ファイル間の契約整合性、潜在的なリグレッションリスク、セキュリティ上の欠陥を検出します。

4. Gitによる最終確認とアトミックコミット

AIはコードを記述する作業を代替しますが、成果物の品質責任はエンジニア自身にあります。

• ターミナルで git status や git diff を実行し、不要な一時ファイルや設定ファイルの紛れ込みがないか確認します。
• マイルストーンごとに小さく意味のあるアトミックコミットを作成し、クリーンなGit履歴を残します。

ベストプラクティス一覧表

参考文献

• Plan Mode | Cursor Docs
• Overview | Cursor Docs
• Agent Review | Cursor Docs
• Rules | Cursor Docs
• Cursor Docs — Agent, Rules, MCP, Skills & CLI