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

先週、あるチームの Cursor エンジニアリング監査を手伝いました。Monorepo には 200 以上のパッケージがあります。プロジェクトを開くたび、ホバー表示まで 4 秒、補完応答は平均 6 秒——1 行打って、コーヒーを一口飲み、返答を待つ日々でした。チームは 2 日間、ハードウェアのアップグレード、モデル変更、Cursor の再インストールを試しました。結局、問題はモデルでもネットワークでもなく、Cursor がデフォルトで packages/ ディレクトリツリー全体をコンテキストとして扱っていたことだと判明しました。本文では診断フロー、設定テンプレート、再構築手順を紹介します。10 分以内に Cursor を快適な状態に戻せます。

Cursor インデックスの仕組み — 5 分で「なぜ遅いのか」を理解する

Merkle Tree が裏方の主役です。Cursor はこれでファイル変更を追跡します。各ファイルのハッシュを計算し、フォルダは中身のハッシュからさらにハッシュを算出。階層を上にたどり、最終的にルートハッシュが得られます。1 ファイルでも変更があれば、そのハッシュが変わり、所属フォルダのハッシュも変わり、ルートまで伝播します。Cursor は変更されたファイルだけを再インデックスすればよく、リポジトリ全体をやり直す必要はありません。

問題はここからです。node_modules には 5 万ファイル以上あることも珍しく、それぞれにハッシュを計算すると、ハッシュデータだけで 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% 以上、メモリが 4 GB 超なら、インデックスがハッシュと埋め込みベクトルを猛計算しているサインです。

次の判断表で、素早く原因を絞り込めます。

症状	想定される原因	最初に試す操作
入力遅延 3〜5 秒	インデックスファイルが多すぎる	.cursorignore で疑わしいフォルダを除外
検索が重い、@codebase の応答が遅い	バイナリ/生成物をスキャンしている	dist/、.nuxt/ などを除外
@ 記号で候補が出ない	コンテキストウィンドウ超過	インデックス範囲を縮小、または Monorepo を分割
インデックスが 99% で止まる	symlink ループまたはファイル権限の問題	.cursorignore で再帰フォルダを除外しているか確認

Zest の Troubleshooting Guide によると、Cursor の不安定問題の 90% は拡張機能の競合とインデックス設定の不備が原因です。あなたは後者に該当する可能性が高いでしょう。

.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：512 KB を超えるファイルはインデックスしない。大きな JSON/CSV でコンテキストを膨らませない
• scopeSelection: "activeFolder"：Agent モードはアクティブなフォルダからだけコンテキストを取得。パッケージをまたいだ検索はしない

大規模 Monorepo 向けの設定です。iamraghuveer の記事によると、5000 ファイルずつの 10 サービスで、インデックスデータは 1〜5 GB になることもあります。全部読み込めば CPU とメモリは厳しくなります。現在作業中のパッケージだけ読み込めば、インデックスサイズは 50 MB 前後に抑えられます。

ワークスペース設定を使うタイミング

• Monorepo が 20 パッケージ超で、各パッケージが比較的独立している
• 特定パッケージで開発しており、頻繁にパッケージをまたぐ必要がない
• チームメンバーが担当サービスで分担している

パッケージ間の依存が重い場合（マイクロサービス間で共有ライブラリを頻繁に呼ぶなど）は、.cursorignore の方が安全です。不要なものを除外し、必要なものは残す。ワークスペースファイルの切り替えは不要です。

キャッシュクリーンアップとインデックス再構築 — カクつきから快適さへ

設定を変えてもインデックスがおかしいとき、キャッシュに古いハッシュが残っている可能性があります。その場合はクリーンアップが必要です。

クイッククリーンアップ（まず試す）

Cmd+Shift+P を押し、「Reindex Codebase」と入力して実行します。Cursor がプロジェクトを再スキャンし、インデックスを再構築します。数十秒程度、大規模プロジェクトでは 2〜3 分かかることもあります。完了後、ステータスバーの進捗が 0% から 100% まで走ります。一息ついて待ちましょう。

ディープクリーンアップ（クイックで効かない場合）

Cursor の設定ディレクトリを削除します。OS ごとのパス：

OS	設定ディレクトリのパス
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 を変更してもインデックスが異常なときだけ使いましょう。

いつインデックスを再構築すべき？

• ステータスバーが 10 分以上「Indexing…」のまま動かない
• 補完応答が通常の 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