Cursorのコードベースインデックス：より良く使う方法
Cursorのコードベースインデックスは、プロジェクトについて「賢く」感じさせるものです。うまく機能すると、関連性の高い提案、正確な@メンション、アーキテクチャを実際に理解した回答が得られます。うまくいかないと、Cursorは盲目のようになります。
このガイドでは、インデックスがどのように機能するか、そしてどう最適化するかを解説します。
Cursorがコードベースをどう理解するか
Cursorはバックグラウンドで2つのものを構築します：
-
埋め込み（Embeddings） — コードファイルのベクトル表現です。質問したり
@を使ったりすると、Cursorはこれらのベクトルを検索し、意味的に最も関連性の高いファイルを見つけます。 -
AST（抽象構文木）分析 — Cursorはコードを解析し、インポート、関数定義、クラス階層、ファイル間の関係を理解します。
この2つのシステムが協働します。埋め込みが「関連しそうなもの」を見つけ、AST分析が「実際にどう繋がっているか」を把握します。
インデックス化はプロジェクトを開いたときに自動的に行われます。大規模なコードベースでは、初回スキャンに数分かかることがあります。ステータスバーに進捗インジケーターが表示されます。
@シンボル：正しい使い方
@ シンボルは、Cursorのインデックスに直接アクセスするための回線です。チャットやインライン編集に特定のコンテキストを引き込むために使います。
@file — 特定のファイルを参照
@src/utils/auth.ts トークンの検証はどうなっていますか？
これは、Cursorが気にしている正確なファイルを見ることを保証する最も信頼できる方法です。埋め込み検索をバイパスし、ファイルの完全な内容を添付します（コンテキスト制限内）。
@folder — ディレクトリ全体を参照
@src/components ここのコンポーネント階層を説明してください
アーキテクチャの質問に便利ですが、注意が必要です — 大きなフォルダーはコンテキストウィンドウをすぐに食い潰します。
@code — 特定のシンボルを参照
@code:validateUser この関数はどのようなエッジケースを扱っていますか？
これはASTインデックスを使って、正確な関数、クラス、変数定義を見つけます。正確でコンテキスト効率が良いです。
1つの関数だけ必要な場合は、@file より @code: を優先してください。コンテキストスペースを節約し、ノイズを減らせます。
大規模プロジェクトの最適化
プロジェクトに数千のファイルがある場合、デフォルトのインデックス化では見落としや遅さを感じることがあります。
実際にインデックス化されているものを確認する
Cursor Settings > General > Codebase Indexing を開きます。以下が表示されます：
- インデックス化されたファイルの総数
- 最後にインデックス化した時刻
- 解析に失敗したファイル
コンテキストの関連性を高める
モノレポでは、Cursorが無関係なファイルを拾うことがあります。プロンプトで明示的に指定しましょう：
この質問には @packages/api/src のみを参照してください。フロントエンドのコードは無視してください。
巨大なファイルを分割する
数千行を超えるファイルは問題を引き起こすことがあります。Cursorは先頭だけをインデックス化したり、埋め込み処理に苦労したりする可能性があります。5000行のユーティリティファイルがある場合は、分割を検討してください。
.cursorignore でファイルを除外する
すべてのものをインデックス化すべきではありません。生成されたファイル、ビルド出力、サードパーティコードはコンテキストスペースを浪費し、検索結果を汚染します。
プロジェクトのルートに .cursorignore ファイルを作成します：
# ビルド出力
dist/
build/
.out/
# 依存関係
node_modules/
vendor/
# 生成されたファイル
*.generated.ts
*.min.js
coverage/
# 大きなデータファイル
*.csv
*.json
.cursorignore は .gitignore と同じ構文を使用しますが、別ファイルです。.gitignore で十分だと思わないでください — Cursorは自動的にそれを尊重しません。
.cursorignore を編集した後、Cursorを再起動するか、再インデックス化されるまで1分ほど待ちます。
インデックスが壊れたとき：トラブルシューティング
時々、Cursorが明らかにコードを「見ていない」ことがあります。チェックリストは以下の通りです：
1. ファイルがインデックス化されているか確認する
ファイルを開き、以下を尋ねます：
今見ているファイルは何ですか？
Cursorが答えられない場合、そのファイルはインデックスにない可能性があります。
2. 強制的に再インデックス化する
コマンドパレット（Ctrl+Shift+P）→ "Cursor: Reindex Codebase"
これはインデックス全体を最初から再構築します。時間はかかりますが、ほとんどの破損問題を修正します。
3. 解析エラーを確認する
Settings > General > Codebase Indexing で、赤いエラーインジケーターが付いたファイルを確認します。これらのファイルはAST関係の分析を受けていません。
一般的な原因：
- ファイルの構文エラー
- 未対応の言語（Cursorは約20の言語を十分にサポートしています）
- バイナリや圧縮ファイルがソースコードとして誤認識された
4. .cursorignore が過激すぎないか確認する
*.config.* を除外した場合、vite.config.ts に重要なパスエイリアスが含まれていると、Cursorはインポートを理解できなくなります。
コンテキスト品質の向上
正しいファイルをコンテキストに入れることは、戦いの半分に過ぎません。そのコンテキストをどう使うかも重要です。
質問を具体的にする
悪い例：
認証はどうなっていますか？
良い例：
@src/auth/middleware.ts において、JWTの検証は期限切れトークンをどう処理していますか？
コンテキストを連鎖させる
Cursorが部分的な回答をした場合、同じ質問を繰り返すのではなく、より具体的な @ 参照でフォローアップします。
レート制限について言及しましたね。@src/middleware/rateLimit.ts — 制限はどう計算されていますか？
最近開いたファイルを活用する
Cursorは埋め込み検索で最近開いたファイルにより高い重みを付けます。ファイルを開いたばかりの場合、@ で関連ファイルを参照しても、明示的に言及しなくても効果的です。
複雑なリファクタリングでは、変更予定のファイルをすべて先に開いてください。これによりインデックスが「準備」され、それらが関連ファイルとして扱われやすくなります。
まとめ
- Cursorは 埋め込み + AST を使ってコードを理解します
@file、@folder、@code:を使ってコンテキストを明示的に制御します- ノイズを除外するために
.cursorignoreを作成します - おかしいと感じたら再インデックス化します
- プロンプトは具体的に — インデックスがファイルを見つけても、使い方はあなたが導きます
コードベースインデックス設定パネルには、プロジェクトのインデックス化ステータスとエラーが表示されます。