cursor-codebase-indexing

Cursor Codebase Indexing

概要

コードベースのインデックス作成を設定し、関連するソースコードやドキュメントを利用できるようにしながら、機密ファイル、生成ファイル、サイズの大きいファイル、無関係なファイルが AI のコンテキストに含まれないようにします。

前提条件

• リポジトリの所有権、想定されるソースコードやドキュメントのパス、確認済みの .cursorignore／インデックス作成の除外設定。
• 機密情報を含まない検証用フィクスチャと、設定変更のレビュー経路。

手順

1. 対象とするワークスペースの範囲を定め、最初のインデックス作成の前に除外設定を追加します。
2. 必要なファイルを検索でき、除外したパスを添付したり検出したりできないことを確認します。
3. レビュー済みの設定またはワークスペースの変更後に限ってインデックスを再作成し、機密情報を除いた結果を記録します。
4. インデックスのサイズとパフォーマンスを監視し、データ管理を緩めるのではなく対象範囲を絞ります。

出力

• 明示的な対象パスと除外パス、および保守担当者が定められた、検証済みのインデックス範囲。

例

サービスの src/ と docs/ をインデックス対象とし、.env*、ビルド出力、ベンダーディレクトリ、顧客データのエクスポートを除外します。リポジトリでの AI 作業を許可する前に、サニタイズ済みのソースファイルを利用でき、除外対象のプレースホルダーは利用できないことを確認します。

Cursor のコードベースインデックス作成システムを設定し、最適化します。インデックス作成ではコードの埋め込み表現が生成されるため、@Codebase によるセマンティック検索が可能になり、Chat、Composer、Agent モード全体で AI のコンテキスト把握が向上します。

インデックス作成の仕組み

Your Code Files
      │
      ▼
  Syntax Chunking ─── splits files into meaningful code blocks
      │
      ▼
  Embedding Generation ─── converts chunks to vector representations
      │
      ▼
  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
      │
      ▼
  @Codebase Query ─── your question → embedding → similarity search → relevant chunks

アーキテクチャの主な詳細

• 変更検出には Merkle tree を使用します。変更されたファイルのみを再インデックスします（10 分ごと）。
• 平文は保存されません。コードはサーバー側に保存されず、埋め込み表現と難読化されたメタデータのみが保存されます。
• Privacy Mode に対応しています。Privacy Mode が有効な場合、ソースコードを保持せずに埋め込み表現が計算されます。
• インデックス作成はバックグラウンドで実行されます。小規模なプロジェクトは数秒で完了し、大規模なプロジェクト（50K+ ファイル）では初回に数時間かかることがあります。

初期設定

1. Cursor でプロジェクトを開きます
2. 初めて開いたときに、インデックス作成が自動的に始まります
3. ステータスを確認します。画面下部のステータスバーに「Indexing...」と表示されているか確認します
4. インデックス対象のファイルを表示します：Cursor Settings > Features > Codebase Indexing > View included files

インデックス作成の状態を確認する

ステータスバーには次のように表示されます。

• 進捗インジケーター付きの 「Indexing...」 — 初回のインデックス作成中です
• 「Indexed」 — インデックス作成が完了し、@Codebase クエリを利用できます
• インジケーターがない — インデックス作成が無効か、開始されていない可能性があります

設定

.cursorignore

インデックス作成と AI 機能からファイルを除外します。プロジェクトのルートに配置します。.gitignore の構文を使用します。

# .cursorignore

# Build artifacts (large, not useful for AI context)
dist/
build/
out/
.next/
target/

# Dependencies
node_modules/
vendor/
venv/
.venv/

# Generated files
*.min.js
*.min.css
*.bundle.js
*.map
*.lock

# Large data files
*.csv
*.sql
*.sqlite
*.parquet
fixtures/
seed-data/

# Secrets (defense in depth -- also use .gitignore)
.env*
**/secrets/
**/credentials/

.cursorindexingignore

インデックス作成のみからファイルを除外し、明示的に指定した場合は AI 機能から引き続きアクセスできるようにします。

# .cursorindexingignore

# Large test fixtures -- don't index, but allow @Files reference
tests/fixtures/
e2e/recordings/

# Documentation build output
docs/.vitepress/dist/

違い： .cursorignore はインデックス作成と AI 機能の両方からファイルを隠します。.cursorindexingignore はインデックスからのみ除外するため、@Files 経由でファイルを参照できます。

デフォルトの除外設定

Cursor は .gitignore に記載されたすべての項目を自動的に除外します。Git で追跡されているファイルを AI から除外したい場合にのみ、.cursorignore が必要です。

インデックスの使用

@Codebase クエリ

コードベース全体について、意味に基づく質問をします。

@Codebase where is user authentication handled?

@Codebase show me all API endpoints that accept file uploads

@Codebase how does the payment processing flow work?

@Codebase find all places where we connect to Redis

@Codebase は、質問の埋め込み表現を使って最近傍検索を実行します。入力したキーワードが正確に含まれていなくても、意味的に最も類似したコードチャンクを返します。

@Codebase と @Files とテキスト検索の比較

方法	使用する場面	コンテキストのコスト
@Codebase	ファイルが分からない場合の検索	高（多数のチャンク）
@Files	対象のファイルが分かっている場合	低（1 ファイル）
@Folders	対象のディレクトリが分かっている場合	中〜高
Ctrl+Shift+F	テキスト／正規表現の完全一致	該当なし（エディター内検索）

検索には @Codebase を使い、コードの場所が分かったら @Files に切り替えます。

大規模プロジェクト向けの最適化

モノレポの戦略

多数のパッケージを含むモノレポでは、ルートではなく特定のパッケージディレクトリを開いてください。

# Instead of opening the entire monorepo:
cursor /path/to/monorepo           # Indexes everything -- slow

# Open the specific package:
cursor /path/to/monorepo/packages/api   # Indexes only this package -- fast

または、ルートに .cursorignore を設定し、現在作業していないパッケージを除外できます。

# .cursorignore -- monorepo, focus on api and shared
packages/web/
packages/mobile/
packages/admin/
# packages/api/    ← not listed, so it IS indexed
# packages/shared/ ← not listed, so it IS indexed

再インデックス

検索結果が古い場合や、インデックス作成が停止しているように見える場合は、次の手順を実行してください。

1. Cmd+Shift+P > Cursor: Resync Index
2. ステータスバーにインデックス作成の進行状況が表示されるまで待ちます
3. 解決しない場合は、ローカルキャッシュを削除します。
   • macOS：~/Library/Application Support/Cursor/Cache/
   • Linux：~/.config/Cursor/Cache/
   • Windows：%APPDATA%\Cursor\Cache\
4. Cursor を再起動し、インデックスがすべて再作成されるまで待ちます

ファイルウォッチャーの上限（Linux）

Linux では、大規模なプロジェクトでファイルウォッチャーの上限に達する場合があります。

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

# Increase (temporary)
sudo sysctl fs.inotify.max_user_watches=524288

# Increase (permanent)
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

エンタープライズに関する考慮事項

• データの保存場所：埋め込みベクトルは Turbopuffer（クラウド）に保存されます。ファイル名は難読化され、コードの平文は保存されませんが、メタデータは存在します
• プライバシーモード：プライバシーモードを有効にすると、プロバイダーでデータを保持せずに埋め込みベクトルが計算されます
• エアギャップ環境：インデックス作成には Cursor の埋め込み API へのネットワークアクセスが必要です。オフラインでは利用できません
• インデックス作成の対象範囲：現在開いているワークスペース内のファイルのみがインデックス化されます。プロジェクトを閉じると、そのインデックスはアクティブなクエリの対象から削除されます

トラブルシューティング

症状	原因	対処方法
@Codebase で結果が返されない	インデックスが作成されていない	ステータスバーに「Indexed」と表示されるまで待ちます
既知のファイルが検索結果に表示されない	ファイルが .gitignore または .cursorignore に含まれている	ignore ファイルを確認します
インデックス作成が N% で停止している	大規模なプロジェクト、またはネットワークの問題	コマンドパレットからインデックスを再同期します
リファクタリング後も古い結果が表示される	インデックスがまだ更新されていない	10 分待つか、手動で再同期します
インデックス作成中に CPU 使用率が高い	初回の埋め込み計算	初回実行時は正常です。処理が進むと低下します

リソース

• コードベースのインデックス作成に関するドキュメント
• ignore ファイル
• 安全なコードベースのインデックス作成