モノレポで Cursor を使うときの設定論点｜サブプロジェクト・パス除外・コンテキスト肥大の抑え方
目次 クリックで開く
モノレポ（Monorepo）構成は、複数のプロジェクトやマイクロサービスを単一のリポジトリで管理できるため、依存関係の整理やコード共有において非常に強力な手法です。しかし、AIエディタである Cursor をモノレポ環境でそのまま使用すると、コードベースの巨大さが原因で「AIの回答精度が低下する」「インデックス作成がいつまでも終わらない」といった特有の課題に直面します。
Cursorの真価を発揮させるには、AIが読み取る「コンテキスト（文脈）」をいかに絞り込み、純度の高い情報を与えるかが鍵となります。本記事では、モノレポ環境におけるCursorの最適な設定論点について、実務的なパス除外の手法からコンテキスト肥大の抑制術まで徹底的に解説します。
モノレポ環境でCursorを最適化する重要性
なぜモノレポはAIにとって「過酷」なのか
Cursorはリポジトリ内のファイルをスキャンし、ベクトルデータ化（Embeddings）することで、高度なコード補完やチャット回答を実現しています。しかし、モノレポでは以下の要素が積み重なり、AIにとっての「ノイズ」が指数関数的に増加します。
- 重複するファイル名： 複数のパッケージに存在する
package.jsonやindex.ts。 - 膨大な依存ライブラリ： 各サブプロジェクト配下の
node_modules。 - 異なるコンテキスト： フロントエンドの修正をしている最中に、AIがバックエンドの古いユーティリティ関数を参考にしてしまう。
コンテキスト肥大が引き起こす3つの実害
- 回答精度の低下： AIが「今どのプロジェクトのルールに従うべきか」を誤認し、文脈に合わないコードを提案します。
- トークン消費の無駄： 不要なファイルがコンテキストに含まれることで、一度のプロンプトで消費されるトークン量が増大します。
- インデックスの不整合： 大規模すぎるリポジトリでは、Cursorのローカルインデックスが制限に達し、重要な最新の変更が反映されなくなることがあります。
Cursorのインデックス（Embeddings）制御の基本
Cursorに「どのファイルを読み込み、どのファイルを無視させるか」を明確に伝えることが、最適化の第一歩です。
.cursorignore の書き方と優先順位
Cursorには、AIのインデックス対象から特定のファイルやディレクトリを除外するための .cursorignore ファイルが存在します。書き方は .gitignore と同様ですが、「ビルド成果物だけでなく、AIに見てほしくないもの」を基準に記述するのがポイントです。
# .cursorignore の記述例
node_modules/
dist/
build/
.next/
*.log
ドキュメントのみに集中させたい場合は、テストコードを除外する等の運用も
**/tests/
.gitignore との役割分担
Cursorはデフォルトで .gitignore に指定されているファイルを無視しようとしますが、開発実務においては「Git管理はしたいが、AIには無視してほしいファイル」が存在します。例えば、大規模なデータ定義ファイル（JSON/CSV）や、生成済みの巨大なクライアントコード（Prisma Client等）です。これらは .cursorignore に個別に記述することで、AIの脳内をクリーンに保つことができます。
インデックスステータスの確認方法
Cursorの「Settings」→「General」→「Features」にある Embeddings セクションを確認してください。ここで「Index Status」が正常か、無視されているファイル数が意図通りかを確認できます。もし意図しないファイルが読み込まれている場合は、この設定画面からインデックスの再構築を試みる必要があります。
サブプロジェクト別の最適化戦略
モノレポ内で複数の技術スタックが混在している場合、単一の設定では不十分です。
パス除外の具体例：フロント・バックエンド混在環境
例えば、Next.jsのフロントエンドとGoのバックエンドが同居している場合、フロントエンドの改修中にバックエンドの複雑な構造がコンテキストに入ると、AIが混乱します。これを防ぐには、Cursorの「コンテキストの制限（Context Limits）」を意識したパス管理が有効です。特定の作業に集中する際は、チャット欄で @folder を使い、対象のサブプロジェクトのみを指定する習慣をつけましょう。
.cursorrules による挙動の定義
プロジェクトのルートディレクトリに .cursorrules を配置することで、AIに対する「指示書」を固定できます。モノレポの場合、以下のようにサブプロジェクトごとの振る舞いを記述するのが有効です。
- 「apps/web 配下のコードを書くときは、Tailwind CSSを使用すること」
- 「packages/api 配下では、必ず依存性注入（DI）パターンに従うこと」
このように、ディレクトリ構造に応じたコーディング規約を明文化することで、AIの「迷い」を排除できます。こうしたデータ活用による業務効率化の視点は、エンジニアリングだけでなくバックオフィス部門のDXでも共通する考え方です。例えば、Excelと紙の限界を突破する「Google Workspace × AppSheet」業務DX完全ガイドで解説されているような、構造化されたデータ管理による自動化の重要性と通ずるものがあります。
実践：モノレポにおけるCursor設定ステップバイステップ
具体的にモノレポ環境を整える手順を解説します。
STEP 1：全体構成の把握と除外対象のリストアップ
まず、リポジトリ内のどのディレクトリが「AIにとって有益か」を仕分けます。
- 有益： ビジネスロジック、型定義、共有ライブラリのインターフェース。
- 不要： ビルド成果物（.next, dist）、キャッシュ（.turbo）、自動生成されたドキュメント、巨大なバイナリデータ。
STEP 2：.cursorignore の作成と配布
プロジェクトルートに .cursorignore を作成します。もし特定のサブプロジェクトだけ極端に巨大な場合は、そのサブディレクトリ内にも .cursorignore を配置できるか試行（※Cursorのバージョンにより挙動が異なるため、基本はルートでの一括管理を推奨）し、不要なパスを徹底的に削ります。
STEP 3：ディレクトリ階層に応じた .cursorrules の配置
モノレポの各パッケージ（apps/A, apps/B, packages/shared）に、それぞれの責務を記述した .cursorrules を置くか、ルートの .cursorrules 内でディレクトリ別のルールを詳述します。
STEP 4：インデックスの再構築（Resync）
設定を反映させた後、Cursorの「Embeddings」設定から「Resync Index」を実行します。これにより、古いキャッシュが破棄され、新しい除外ルールに基づいたクリーンなコンテキストが構築されます。
比較表：モノレポ運用における構成パターンのメリット・デメリット
モノレポをCursorで開く際、どのような単位でプロジェクトを開くべきか。運用パターンを比較しました。
| 構成パターン | メリット | デメリット | 適したケース |
|---|---|---|---|
| ルートディレクトリ開き | プロジェクト全体の依存関係や共通ライブラリをAIが完全に把握できる。 | コンテキストが肥大化しやすく、インデックス作成に時間がかかる。 | 小〜中規模のモノレポ。プロジェクト横断の修正が多い場合。 |
| サブプロジェクト単位開き | AIの視界が限定され、ノイズが最小限になる。動作が軽量。 | 共有パッケージ（packages/*）の型定義や変更をAIが追えなくなる。 | 特定アプリの集中開発。依存関係が疎結合な場合。 |
| マルチルートワークスペース | 必要なフォルダだけをピックアップしてAIに見せることができる。 | VS Codeのワークスペース設定（.code-workspace）の管理コスト。 | 大規模モノレポで、特定の数プロジェクトのみを同時並行で触る場合。 |
大規模な組織で、フロントエンドからバックエンド、さらにはデータ基盤まで一気通貫で管理している場合、この構成選択は開発効率に直結します。例えば、高額なCDPは不要？BigQuery・dbt・リバースETLで構築する「モダンデータスタック」ツール選定のような、複数の技術スタックが絡み合うプロジェクトでは、共通の型定義（dbtのモデル等）をAIに見せつつ、不要な中間テーブルの定義を隠すといった細やかな制御が求められます。
よくあるトラブルと解決策（FAQ）
「別のアプリのコードを参考に回答してしまう」
これはモノレポで最も多い悩みです。チャットを始める際、単に質問するのではなく 「@Files」や「@Folders」で明示的にスコープを絞る 癖をつけてください。また、.cursorrules に「apps/A の作業中は apps/B を参照しないこと」と一筆加えるだけでも効果があります。
「インデックス作成が終わらない・重い」
原因の大半は node_modules や、.git ディレクトリ内の巨大なオブジェクト、あるいは画像・動画などのバイナリデータです。.cursorignore に /.git や /node_modules が含まれているか再確認してください。また、Cursorの有料プラン（Pro等）であっても、インデックス可能なファイル数には実質的な上限（または処理時間の限界）があるため、情報の断捨離が不可欠です。
「.cursorignore が効いていない気がする」
Cursorのインデックスは、ファイルを保存した瞬間にバックグラウンドで更新されます。設定直後は反映が遅れることがあるため、一度手動で「Resync Index」を行うのが確実です。また、無視したいパスの記述が正しいか（VS CodeのGlobパターン準拠か）を確認してください。
まとめ：運用効率を最大化する継続的なメンテナンス
モノレポでのCursor運用は、「一度設定して終わり」ではありません。プロジェクトの成長とともにサブプロジェクトが増えれば、その分だけAIに与えるべき情報も変化します。定期的に .cursorignore を見直し、AIにとっての「集中しやすい環境」を整えることが、結果としてコード品質の向上と開発速度の最大化につながります。
こうしたツール設定の最適化は、エンジニアリングにおける「技術負債」の解消に近い作業です。バックオフィス業務においても、SaaSコストとオンプレ負債を断つ。バックオフィス＆インフラの「標的」と現実的剥がし方で述べられているように、不要なものを削ぎ落とし、コアとなる価値（本流のコード）に集中できる状態を作ることが、真の効率化への近道と言えるでしょう。
Cursorの仕様や詳細な料金体系については、Cursor公式サイトを適宜参照し、最新の機能を最大限に活用してください。