Cursor 大規模プロジェクトのインデックス管理：診断から再構築までの完全ガイド

先週、あるチームの Cursor エンジニアリング監査を支援しました。彼らの Monorepo は 200+ パッケージを含んでいました。プロジェクトを開くたび、ホバーツールチップに 4 秒、補完応答平均 6 秒——1 行コードをタイプし、コーヒーを一口飲み、思考が完了するまで待つ。チームは 2 日間試行錯誤：ハードウェアアップグレード、モデル変更、Cursor 再インストール。最終的に問題はモデルやネットワークではなく、Cursor がデフォルトで packages/ ディレクトリツリー全体をコンテキストとして扱っていたことが判明。本記事では診断ワークフロー、設定テンプレート、再構築ソリューションを提供し、10 分以内で Cursor をスムーズなパフォーマンスに戻します。

Cursor インデックスメカニズム概要 — 5 分で「遅い理由」を理解

Merkle Tree が舞台裏の主役。Cursor はこれを使用してファイル変更を追跡——各ファイルがハッシュ値を取得、フォルダは内部の全ファイルに基づいてハッシュを計算し、上層へ伝播し最終的にルートハッシュに到達。1 ファイルを変更？そのハッシュが変化、所属フォルダのハッシュも変化、ルートノードまで伝播。Cursor は変更されたファイルのみを再インデックスし、リポジトリ全体を対象としない。

問題が発生します。node_modules は 50,000 ファイルを含む可能性があり、各ファイルがハッシュ化され、ハッシュデータのみで 3.2 MB。さらに悪いことに、Cursor はこれらのファイルの埋め込みベクトルも計算必要——npm パッケージのコードはビジネスロジックとほぼ無関係ですが、インデックス作成者はそれを認識せず、すべてをコンテキストに詰め込みます。

Cursor 公式ブログデータによると、99 パーセンタイルの大規模リポジトリの初回クエリは 4.03 時間要します。しかしチーム協力には隠れた利点：同一コードベースのクローンは平均 92% の類似ファイルを持つ。Cursor はこれらのインデックスデータを再利用し、初回クエリ時間を 21 秒に圧縮。インデックスがクリーンであれば、チームメイトがプロジェクトを開く際、あなたの事前計算キャッシュを直接使用可能。

一言で：インデックスが遅いのは Cursor の計算が遅いからではなく、過度に多くをインデックスしている——多くは本来インデックス不应该。

診断ワークフロー — 3 ステップで「真犯人」を特定

設定変更前に、まず診断。

ステップ 1：インデックス状態確認。 プロジェクトを開き、右下ステータスバーの小アイコンを確認。「Indexing…」が継続表示または進捗バーが特定パーセントで停滞している場合、インデックス問題。「Cmd+Shift+P」（Windows は「Ctrl+Shift+P」）を押し、「Show Cursor Logs」を入力、最後の数行ログを確認。「Indexing 1,342 files…」のような出力——数字が 5000 を超過？基本的にそれが原因。

ステップ 2：嫌疑フォルダリストアップ。 ターミナルを開き、プロジェクトルートで find . -type d -name "node_modules" -o -name "dist" -o -name "build" -o -name ".git" | wc -l を実行。一般的「インデックス殺し」：

フォルダタイプ	ファイル数	インデックス影響
node_modules/	50,000+	大量のハッシュ計算と埋め込みベクトル空間を消費
dist/、build/	5,000+	バイナリ成果物、AI のコード理解に無意味
.git/	3,000+	バージョン管理データ、インデックス価値が低い
coverage/	2,000+	テストレポート HTML/JSON、ノイズデータ
.next/、.nuxt/	10,000+	フレームワークコンパイルキャッシュ、コンパイル成果物を含む

ステップ 3：CPU とメモリ監視。 Activity Monitor（macOS）または Task Manager（Windows）を開き、Cursor プロセスを監視。CPU が 80% 以上に急増、メモリ使用量が 4GB を超過？それはインデックスが猛烈にハッシュと埋め込みベクトルを計算中。

この決定木で迅速に特定：

症状	潜在原因	第一アクション
タイピング遅延 3-5 秒	インデックスファイル過多	.cursorignore を追加して嫌疑フォルダを除外
検索ラグ、@codebase 応答遅延	バイナリ/生成成果物をスキャン	dist/、.nuxt/ などを除外
@ 記号が候補を表示しない	コンテキストウィンドウ超過	インデックス範囲を縮小、または Monorepo 分割
インデックスが 99% で停滞	symlink 循環またはファイル権限問題	.cursorignore が再帰フォルダを除外しているか確認

Zest の Troubleshooting Guide によると、90% の Cursor 不安定問題は拡張機能競合と不適切なインデックス設定に起因。あなたは大半が後者に該当。

.cursorignore 設定 — 3 テンプレートで主要シナリオをカバー

.cursorignore の構文は .gitignore と完全に同一、プロジェクトルートに配置。Cursor はこのファイルを読み取り、その内容をインデックスしない。

テンプレート 1：JavaScript/TypeScript プロジェクト

# 依存関係
node_modules/
.npm/
.yarn/

# ビルド成果物
dist/
build/
out/
.next/
.nuxt/

# テストとカバレッジ
coverage/
.nyc_output/

# ログと一時ファイル
*.log
*.tmp
.DS_Store

プロジェクトが Monorepo（pnpm workspace 等）を使用する場合、段階的インデックス可能：まず全パッケージを除外し、現在修正中のパッケージのみ許可リストに追加。

# Monorepo 段階的インデックス
packages/*/
!packages/api/        # 現在開発中パッケージ、許可リスト追加
!packages/shared/     # 共有ライブラリ、参照可能性
node_modules/
dist/

テンプレート 2：Python プロジェクト

# 仮想環境
venv/
.venv/
env/
.env/

# コンパイルキャッシュ
__pycache__/
*.pyc
*.pyo
.pytest_cache/

# パッケージング成果物
*.egg-info/
build/
dist/

# Jupyter Notebook
.ipynb_checkpoints/

Python 仮想環境は数千ファイルを含むことが多く、大半がサードパーティライブラリのソースコード。venv/ を除外すると、インデックスサイズを 90% 縮小可能。

テンプレート 3：Go プロジェクト

# 依存関係キャッシュ
vendor/

# ビルド成果物
bin/
*.exe
*.exe~
*.dll
*.so
*.dylib

# テストキャッシュ
*.test
*.out
coverage.txt

Go の vendor/ ディレクトリは node_modules/ と類似、数千の依存関係ファイルを含む。

効果比較：Developer Toolkit データによると、デフォルトインデックス設定（.cursorignore なし）のコンテキスト精度はノイズ過多で 65%のみ；合理的除外ルール追加後、精度は 98% に到達。簡潔に言えば、20% のファイルを除外することで 50% の精度向上を獲得。

Monorepo マルチリポジトリワークスペース設定

Monorepo が数十サービスを含み、開くたびにインデックス完了を待機必要な場合、.code-workspace ファイルで現在修正中のパッケージのみ読み込むことを考慮。

プロジェクトルートに workspace.code-workspace ファイルを作成：

{
  "folders": [
    {"name": "payments", "path": "./services/payments"},
    {"name": "shared-libs", "path": "./libs"}
  ],
  "settings": {
    "cursor.indexing.maxFileSize": 512000,
    "cursor.chat.scopeSelection": "activeFolder"
  }
}

Cursor でこのファイルを開く（リポジトリ全体を開かない）。サイドバーは payments と shared-libs の 2 フォルダのみ表示、他サービスは視野外。インデックスはこれら 2 ディレクトリのみ実行、速度は 10 倍高速化可能。

主要設定説明：

• maxFileSize: 512000：512KB を超過するファイルをインデックスしない、大 JSON/CSV がコンテキストを爆発させることを回避
• scopeSelection: "activeFolder"：Agent モードは現在アクティブなフォルダからのみコンテキストを取得、パッケージ間検索を行わない

この設定は大規模 Monorepo で特に有用。iamraghuveer の記事では、10 サービス各 5000 ファイルのプロジェクトは 1-5GB のインデックスデータを持つ——全読み込みの場合、CPU とメモリが負荷過大。現在作業中のパッケージのみ読み込むことで、インデックスサイズを約 50MB に低下可能。

ワークスペース設定を使用するタイミング？

• Monorepo が 20 パッケージを超過、各パッケージが比較的独立
• あるパッケージで開発中、頻繁なパッケージ間参照を必要としない
• チームメンバーが明確に分担、各々が異なるサービスを担当

パッケージ間の依存関係が重度（マイクロサービス間で頻繁に共有ライブラリを呼び出す等）の場合、.cursorignore がより堅牢——不要なものを除外し、必要なものを保持、ワークスペースファイルの頻繁な切替不要。

キャッシュクリーンアップとインデックス再構築 — ラグからスムーズへ

設定変更後、インデックスが依然異常な場合——キャッシュに古いハッシュデータが保存されている可能性。クリーンアップが必要。

迅速クリーンアップ（優先試行）

Cmd+Shift+P を押し、「Reindex Codebase」を入力、選択。Cursor はプロジェクトを再スキャンし、インデックスを再構築。数十秒、大規模プロジェクトは 2-3 分を要する。完了後、ステータスバーのインデックス進捗は 0% から 100% に進行、水を一口飲んで待機可能。

深層クリーンアップ（迅速クリーンアップ無効の場合）

Cursor の設定ディレクトリを削除。各システムのパス：

オペレーティングシステム	設定ディレクトリパス
macOS	~/Library/Application Support/Cursor
Windows	%APPDATA%\Cursor
Linux	~/.config/Cursor

Cursor を閉じ、上記ディレクトリを見つけ、削除（または他の場所にバックアップ）。Cursor を再起動、設定とインデックスを再初期化。

⚠️ 注意：設定ディレクトリ削除はカスタム設定（settings.json）、キーボードショートカット、拡張機能設定を全てクリア。先に User/settings.json ファイルをバックアップすることを推奨。

完全リセットステップ

1. Cursor を閉じる
2. ~/Library/Application Support/Cursor/User/settings.json をバックアップ（存在する場合）
3. 設定ディレクトリ全体を削除
4. Cursor を再起動
5. プロジェクトの再インデックスを待機（数分実行）
6. settings.json をコピー復元（カスタム設定を回復）

Zest の Troubleshooting Guide によると、再起動 → キャッシュクリーン → ステータス確認、このワークフローは 5 分以内で 80% のインデックス問題を解決。大半のケースで迅速クリーンアップで十分；深層クリーンアップは .cursorignore 修正後にインデックスが依然異常な場合のみ使用。

インデックス再構築が必要なタイミング？

• ステータスバーが「Indexing…」を 10 分以上継続表示、無進捗
• 補完応答が正常 1-2 秒から 5 秒以上に低下、数日間継続
• .cursorignore 修正後、@codebase 検索結果が依然除外ファイルを含む

結論

Cursor インデックスが遅い根本原因：本来インデックス不应该ファイルを過度にインデックス。解決アプローチは直接的——診断、除外、再構築。

アクションチェックリスト：

1. 大規模プロジェクトを開き、Cmd+Shift+P で「Show Cursor Logs」を入力、インデックスファイル数を確認
2. 5000 ファイルを超過する場合、即座に .cursorignore を作成（本記事のテンプレートをコピー）
3. node_modules/、dist/、.git/ などの生成成果物ディレクトリを除外
4. 「Reindex Codebase」を実行、インデックス完了を待機
5. 依然遅い場合、CPU とメモリ使用量を確認し、.code-workspace で現在作業中のパッケージのみ読み込むことを考慮

長期保守推奨：

• 新依存関係またはビルド設定を追加するたび、.cursorignore の更新必要性を確認
• チームプロジェクトは .cursorignore をリポジトリルートに追加、全員の設定を一致保証
• 大規模 Monorepo は定期的に旧サービスインデックスをクリーン、アクティブ開発パッケージのみ保持

今すぐ試行。10 分以内で、Cursor がスムーズに回復——補完応答が 1-2 秒に戻り、@codebase 検索がラグなし、ホバーツールチップが即時表示。開発効率が回復します。

---

参考資料

本記事のデータ引用ソース：

• Securely indexing large codebases - Cursor — Cursor 公式ブログ、2026-01-27
• Performance Optimization for Cursor - Developer Toolkit — 技術ブログ、2026-05-28
• Cursor Codebase Indexing for Multi-Repo Workspaces - iamraghuveer — 個人ブログ、2026-04-25
• A Practical Guide to Cursor Troubleshooting - Zest — 技術ブログ、2025-12-24
• How to setup Cursor for Large Scale Repositories - NOVA AI — 技術ブログ、2026-04-07