大規模リポジトリの「重い・フリーズする」を根絶する。Cursorのメモリ最適化とインデックス高速化の極意
テックリードの皆さん、日々の開発においてAIエディタ「Cursor」はもはや手放せない中核インフラとなっていることでしょう。しかし、数百万行規模のモノレポや、何十ものマイクロサービスが混在する巨大なコードベースを扱っていると、ある壁にぶつかります。
- 「Ctrl+K / Ctrl+Lの応答が突然数秒遅延する」
- 「コードベース全体をコンテキスト（@Codebase）に入れた途端、Macのファンが爆音を立て、RAM使用率が跳ね上がる」
- 「`.gitignore`に書いているはずのビルド成果物や巨大なログをAIが勝手に読み込み、コンテキストがゴミで汚染される」
VS CodeのフォークであるCursorは、ローカルで強力なベクトル検索インデックス（Embeddings）を構築し、セマンティック検索（意味的検索）を実現しています。しかし、デフォルト設定のまま大規模リポジトリを放り込むのは、エンジニアが手動で巨大なダンプファイルを全読み込みしているようなものです。
今回は、Cursorの内部メカニズム（なぜ重くなるのか）を紐解きつつ、インデックスの最適化、RAM消費の抑制、そしてチーム全体で開発スピードを極限まで高めるための「実践的設定アーキテクチャ」を完全解説します。
—
1. なぜ大規模リポジトリでCursorは重くなるのか？（内部メカニズム）
CursorのAI機能の肝は、ローカル環境で実行されるコードのベクトル化とインデックス作成にあります。
1. ファイルウォッチャーの負荷: リポジトリ内の全ファイル変更を監視（Chokidar等のライブラリを使用）。
2. AST（抽象構文木）解析とチャンキング: コードを論理的な単位に分割し、LLMが理解しやすい形に変換。
3. ローカルベクトルDBの肥大化: 変換されたデータがSQLiteや専用のベクトルストアに蓄積され、インメモリまたは高速I/Oで常時アクセスされる。
数万ファイルを超える環境では、このパイプラインが常にCPUとI/Oを圧迫します。特に「ビルド成果物」「依存関係ディレクトリ」「自動生成されたモックファイル」までインデックス化対象に含めてしまうことが、パフォーマンス劣化の最大の原因です。
—
2. インデックスを爆速化する「適切な除外設定」の科学
VS Code標準の `.gitignore` や `.vscode/settings.json` だけでは、Cursorの高度なAIインデックス（@Codebase）の暴走を防ぎきれない場合があります。Cursor専用の除外設定を網羅的に適用する必要があります。
絶対にインデックスから除外すべき対象
- ビルド成果物: `dist/`, `build/`, `.next/`, `out/`, `target/`
- 依存関係: `node_modules/`, `vendor/`, `.venv/`
- インフラ・環境データ: `.terraform/`, `.lock` (lockfileのインデックスは無意味), 巨大なCSVやJSONデータのサンプル
- 自動生成コード: OpenAPI等から自動生成された数万行のAPIクライアントコード（AIが読む必要がない、またはハルシネーションの原因になる）
最適化された `.cursorignore` のベストプラクティス
プロジェクトのルートに `.cursorignore` を配置します。これは `.gitignore` と同様の構文ですが、CursorのAIインデックス作成およびコンテキスト検索から完全に外すための強力なディレクティブです。
— 依存関係・パッケージマネージャー —
node_modules/
vendor/
.pnpm-store/
.venv/
env/
— ビルド成果物・キャッシュ —
dist/
build/
.next/
out/
target/
.tsbuildinfo
.turbo/
.parcel-cache/
— インフラ・Terraform・コンテナ —
.terraform/
.tfstate
.tfstate.backup
docker-data/
— 自動生成コード・モック・巨大データ —
自動生成されたAPIクライアントはAIのコンテキストを汚染するため除外
src/generated/
api-client/
.generated.ts
.min.js
.min.css
— ログ・一時ファイル・IDE固有 —
logs/
.log
tmp/
.DS_Store
.vscode/
.idea/
—
3. RAM消費を極限まで抑える `settings.json` アーキテクチャ
次に、エディタ自体のメモリフットプリントを最小化し、バックグラウンド処理の負荷を下げるための設定を施します。プロジェクトルートの `.vscode/settings.json`（またはグローバル設定）に以下の記述を行います。
実用的な設定ファイル構成例
{
// — ミニマップ・視覚エフェクトの削減（CPU/GPU負荷軽減） —
“editor.minimap.enabled”: false,
“editor.renderLineHighlight”: “line”,
“editor.smoothScrolling”: false,
“workbench.list.smoothScrolling”: false,
// — ファイル検索・ウォッチャーの最適化 —
// 大規模リポジトリでVS Codeが監視するファイル数を制限し、CPU使用率を急低下させる
“files.watcherExclude”: {
“/.git/objects/“: true,
“/.git/subtree-cache/“: true,
“/node_modules//“: true,
“/dist/“: true,
“/build/“: true,
“/.next/“: true,
“/target/“: true,
“/.venv/“: true,
“/vendor/“: true
},
// 検索対象から不要なディレクトリを完全除外
“search.exclude”: {
“/node_modules”: true,
“/bower_components”: true,
“/dist”: true,
“/build”: true,
“/.next”: true,
“/.git”: true,
“/target”: true,
“/vendor”: true
},
// — Cursor 固有のAIパフォーマンス最適化 —
// 自動インデックスの更新頻度を制御し、タイピング中のカクつきを防止
“cursor.cpp.enableAutoTrigger”: true,
// 巨大ファイル（5MB以上）の自動ハイライトや解析を無効化
“files.maxMemoryForLargeFilesMB”: 4096,
// ダーティファイルの自動保存を適切に管理し、I/O競合を防ぐ
“files.autoSave”: “afterDelay”,
“files.autoSaveDelay”: 2000
}
—
4. インデックス再構築のベストタイミングとメンテナンス手順
長期間開発を行っていると、インデックス（Vector DB）が断片化したり、削除されたファイルのゴミデータが残ることで、検索精度が落ちたりメモリリーク気味になります。
インデックスをクリア・再構築すべき「3つのタイミング」
1. 巨大なブランチのマージ（大規模なリファクタリング）後: 数百ファイルが一気に変更された直後は、インデックスの整合性が崩れやすい。
2. `.cursorignore` や `settings.json` を大幅に改修した直後: 除外設定が即座に反映されない場合があるため。
3. AIの回答精度が露骨に低下し、「関係ないファイル」をコンテキストに含め始めた時。
手動リセット手順（コマンドパレット）
1. `Ctrl + Shift + P` (macOSなら `Cmd + Shift + P`) でコマンドパレットを開く。
2. `Cursor: Regenerate Index` または `Developer: Reload Window` を実行。
3. 必要に応じて、Cursorのキャッシュディレクトリ（`~/.config/Cursor/Cache` や `~/Library/Application Support/Cursor/Code/User/globalStorage/cursor.cursor-settings` 周辺）の肥大化を確認する。
—
5. チーム開発で役立つ設定の共有化ルール
個人のローカル環境だけで最適化を行っても、チームメンバーの誰かが数GBの `node_modules` をインデックス対象にしていると、リポジトリ全体のDX（Developer Experience）は向上しません。
テックリードが主導すべき3つのルール
1. `.cursorignore` と `.vscode/settings.json` を Git 管理下に置く
- プロジェクトの標準設定としてリポジトリに含め、開発者全員が強制的に同じ最適化恩恵を受けられるようにします。
2. CI/CDパイプラインでのLintと併用する
- 自動生成コードがコミットされていないか、巨大なビルド成果物が混入していないかをチェックするフローを構築します。
3. 新規参入者向けのオンボーディングドキュメントの整備
- リポジトリクローン直後に「Cursorのインデックスが重いと感じたら、まずウィンドウのリロード（`Reload Window`）を行うこと」といったオペレーションを周知します。
—
プロフェッショナルとしてのまとめ
Cursorのメモリ最適化は、単に「PCのファンがうるさいのを黙らせる」ためのものではありません。AIが正確なコンテキストを瞬時に把握し、ハルシネーション（幻覚）を最小限に抑えつつ、極限までレイテンシーを削ぎ落とすためのエンジニアリングです。
今回紹介した `.cursorignore` の厳格な適用と、ファイルウォッチャー・検索の除外設定を投入すれば、数万ファイル規模のモノレポであっても、Cursorはあなたの思考スピードに完全に追従する最強のペアプログラマーへと生まれ変わります。
明日の開発から、いや、今すぐこの設定をあなたのリポジトリに導入し、チーム全体の開発パフォーマンスを次の次元へと引き上げてください。