Cursor Codebase インデックス完全ガイド：仕組み、設定、@シンボル活用術

深夜1時、Cursor が提示した5つ目の的外れな提案を見て、ついに心が折れそうになりました。

「このログインバグを直して」——私の要求は明確でした。しかし Cursor が出したコードは、プロジェクトにある既存の認証ユーティリティを完全に無視し、検証ロジックをゼロから書き直すよう提案してきました。さらに酷いことに、プロジェクトに存在しない utils ディレクトリにコードを置くよう勧めてきたのです。

その時、私は悟りました。どんなに賢い AI でも、プロジェクトの全貌が見えていなければ、単なるコード生成ロボットに過ぎず、そのアドバイスは常に的を外すのだと。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

その後、私は20分かけて Codebase インデックスと .cursorignore ファイルを設定しました。もう一度試してみると、Cursor は即座に理解しました。私の認証ユーティリティを見つけ出し、さらに3箇所のコード重複を指摘し、統一的にカプセル化することを提案してくれました。「AI がついに私のプロジェクトを理解した」という感覚は、本当に爽快でした。

Cursor インデックスの基礎原理

Codebase インデックスとは？

「インデックス」と聞くと難しそうに聞こえますが、理屈は簡単です。

図書館で本を探す場面を想像してください。目録システムがなければ、端から順に棚を探すしかなく、丸一日かかるかもしれません。しかし目録カード（検索システム）があれば、書名やキーワードを入力するだけで数秒で場所を特定できます。

Cursor の Codebase インデックスも同じ理屈です。プロジェクト全体に「スマート目録」を作成し、AI が勘に頼らずに関連コードを素早く見つけられるようにします。

具体的には、コードファイルをスキャンし、各関数、クラス、変数の役割を分析して、数学的な方法（ベクトル化）で「タグ」を付けます。これにより、AI に質問した際、最も関連性の高いコード部分を瞬時にマッチングできるのです。

インデックス作成の6ステップ

技術的な詳細は省きますが、このフローを理解しておけば、なぜインデックスが遅いのか、なぜ .cursorignore が重要なのかが分かります。

ステップ1：ファイルスキャンと前処理

プロジェクトを開くと、Cursor はまず全ファイルをスキャンします。この時、.gitignore と .cursorignore に記載されたファイルをスキップします。もし .cursorignore を設定していなければ、node_modules 内の数万ファイルを真面目にインデックスしようとしてしまいます。

ステップ2：コードのチャンク化（分割）

スキャン完了後、Cursor はファイルをひとまとめにはしません。関数、クラス、論理ブロックごとに賢く分割（チャンク化）します。例えば1000行のユーティリティファイルは、30個の小さなブロックに分割され、個別にインデックスされます。これにより検索精度が上がります。

ステップ3：ベクトル埋め込み（ここが核心）

少し抽象的ですが、平たく言えば「ベクトル化」とはコードを数列に変換することです。この数列はコードの「指紋」のようなものです。機能が似ているコードは、指紋も似ています。書き方が違う2つのログイン関数でも、ベクトル化されると数学的空間での距離は近くなります。

ステップ4：ベクトルデータベースの構築

全コードブロックの「指紋」はローカルデータベース（Cursor は FAISS 等の技術を使用）に保存されます。これがインデックスの正体です。このデータはあなたの PC 内に保存され、設定しない限りクラウドには上がりません。

ステップ5：クエリマッチング

あなたが「ログインロジックを最適化して」と入力すると、Cursor はその言葉もベクトル化し、データベース内で「指紋」が最も近いコードブロックを検索します。この処理はミリ秒単位で完了します。

ステップ6：コンテキスト注入

関連コードが見つかると、Cursor はそれらを AI へのプロンプト（コンテキスト）に挿入します。AI は実際のコードを見た上で回答するため、的確な答えが返ってきます。

なぜインデックスが重要なのか？

比較実験を行いました。同じ要望に対し、インデックスなしの場合、Cursor は現在開いているファイルしか見えず、的外れな提案をしました。インデックス有効化後は、関連する3〜5ファイルを自動で関連付け、そのまま使える解決策を提示しました。

その差は歴然です。以前、API 層、データ層、UI 層の3ファイルが絡むバグに遭遇しました。インデックスがない時は、手動で3ファイルを @ メンションし、関係性を説明する必要がありました。インデックスがあれば、「なぜユーザーデータが更新されない？」と聞くだけで、Cursor が自ら3ファイルを見つけ出し、さらに私が忘れていた4つ目のファイル（ミドルウェアでのバリデーション）まで発見してくれました。

プライバシーとセキュリティ

「クラウドアップロード」「AI コード分析」と聞いて不安になる方もいるでしょう。私も最初はそうでした。

安心できる事実を挙げておきます：

1. コードは平文で保存されない——インデックスに保存されるのはベクトル（数列）であり、ソースコードそのものではありません。
2. ファイルパスは暗号化される——インデックスファイルを見られても、何のプロジェクトかは分かりません。
3. Privacy Mode——Cursor 設定でプライバシーモードをオンにすれば、ベクトルすらローカルから出しません。

正直なところ、金融や医療などの機密プロジェクトでは Privacy Mode を使いますが、一般的な Web プロジェクトや個人開発ならデフォルト設定で十分安全です。

@ シンボル完全ガイド

使い始めた当初は「@ はただの参照」だと思っていましたが、奥が深いです。間違った使い方をすると時間を無駄にするだけでなく、AI が変な提案をしてきます。

この章では、6種類の @ シンボルの使い方、適用シーン、メリット・デメリットを整理しました。

@Codebase - プロジェクト級コンテキスト

用途：AI にプロジェクト全体のコード構造とロジックを理解させる。

最も強力で、最も過小評価されている機能です。@Codebase を入力すると、Cursor はインデックスデータベースに基づいて、質問に最も関連するコード断片を自動で探し出します。

適用シーン：

Alibaba Cloud - 開発者向けクラウドの第一候補、ライトサーバー15%OFF、プロジェクトの迅速な立ち上げを支援

15%割引を入手 →広告

• 複数ファイルにまたがる問題調査：「なぜログイン後にデータが同期されない？」
• アーキテクチャに関する質問：「このプロジェクトの権限管理はどこでやってる？」
• 新規プロジェクトの学習：「このプロジェクトのルーティング構成はどうなってる？」

実体験：ドキュメントのない1000ファイル超のレガシー案件を引き継いだ時、@Codebase 支払いのフローはどうなってる？ と聞いたら、API 呼び出しからバリデーション、コールバック処理まで、5つの関連ファイルを秒速で特定し、フローを解説してくれました。手動なら半日はかかったでしょう。

制約：

• インデックス品質に依存する（設定が悪いと精度が落ちる）。
• 検索速度がやや遅い（通常1-3秒）。
• 超大規模プロジェクト（10万行超）では、一部のコードを見落とすことも。

@Files - 正確なファイル指定

用途：AI に特定のファイルだけを見るよう指示する。

最も直感的です。@Files と入力するとファイル選択画面が出ます。AI は選ばれたファイルだけを見て、余計な推測をしません。

適用シーン：

• 問題の箇所がどのファイルか分かっている時。
• 特定のファイルを修正したい時。
• 他のコードと混同されたくない時。

実例：コンポーネントのリファクタリングで、コンポーネント本体、スタイル、テストの3ファイルが対象の場合。@Files でこれら3つを選び、「関数コンポーネント書き換えて」と頼めば、余計な提案なしで的確に修正してくれます。

メリット：正確、高速、制御しやすい。
デメリット：関連ファイルを知っている必要がある、選び忘れのリスク。

@Folders - ディレクトリ指定

用途：特定のフォルダ全体のコードをコンテキストにする。

問題がどのモジュールにあるかは分かるが、具体的にどのファイルか不確かな場合に適しています。

適用シーン：

• 「/components/auth/ 配下の全コンポーネントを最適化して」
• 「/api/ ディレクトリのコードのセキュリティチェックをして」

注意：フォルダが大きすぎるとコンテキスト制限を超えます。通常、10ファイル以内が適切です。数十ファイルあると、AI は最初の一部しか見られない可能性があります。

@Code - 特定コード片

用途：特定の関数、クラス、コードブロックを引用する。

コードを選択して右クリック「Add to Chat」するか、@Code と入力して関数名を選びます。

適用シーン：

• 「この validateUser 関数のバグを見て」
• 「このロジックをリファクタリングして見やすくして」

お気に入り：1000行のファイルの中で、50行の関数だけを見てほしい時に使います。@Code でその関数だけ渡せば、AI は他のコードに気を取られず集中して解決してくれます。

@Docs - 外部ドキュメント参照

用途：公式ドキュメントや API リファレンスを AI に参照させる。

適用シーン：

• 「Next.js 公式ドキュメントを参考に動的ルーティングを設定して」
• 「この API ドキュメントに基づいて呼び出しコードを生成して」

使い方：@Docs と入力し、ドキュメントの URL を入力するか、プリセットから選択します。

制約：

• メジャーなフレームワーク以外はまだ対応が不十分な場合がある。
• カスタム URL は失敗することもある。

@Web - リアルタイム Web 検索

用途：最新情報をネット検索させる。

リリースされたばかりのライブラリなど、AI の学習データにない情報が必要な時に使います。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

適用シーン：

• 「React 19 の最新機能を探して」
• 「この npm パッケージの最新バージョンの使い方は？」
• 最新のバグやエラー解決策を探す。

注意：リアルタイム検索なので少し遅いです。必要な時だけ使いましょう。

比較表：6種 @ シンボルの選び方

私の使い分け

最初は @Files ばかり使っていましたが、今は @Codebase がメインです。自分で選ぶより AI に探させた方が早く、見落としも防げるからです。

現在の使用比率は：

• @Codebase：60%
• @Files：30%
• @Code：5%
• その他：5%

.cursorignore 設定実践

これについて話さないわけにはいきません。地味ですが、設定するだけでインデックス速度が50%向上し、CPU 使用率が半減します。

初めて Cursor を使った時、設定せずに node_modules 込みのプロジェクトを開いたら、PC のファンが爆音を上げ、Cursor がフリーズしかけました。数万個の無関係なファイルを必死にインデックスしていたのです。

なぜ .cursorignore が必要か？

理由は単純です。すべてのファイルに読む価値があるわけではないからです。

• 依存ファイル：node_modules, vendor 等。数万ファイルありますが、中身をいじることはありません。
• ビルド生成物：dist, build, .next 等。ソースコードではありません。
• 一時ファイル：.log, .cache 等。
• 巨大アセット：動画、画像、フォント。インデックスしても無意味です。

これらを除外すれば、インデックス時間は5分から30秒に短縮され、ノイズが減ることで AI の回答精度も上がります。

.cursorignore vs .gitignore

よく聞かれます。「.gitignore があるのに .cursorignore も要るの？」

答えはYES。両者は役割が違います。

.gitignore は「バージョン管理に含めないファイル」です。しかし、バージョン管理には含めないが AI には見てほしいファイルがあります。

• ローカル設定：.env.local（環境変数を教えたい）
• 個人メモ：TODO.md（AI に参照させたい）

逆に、コミットするがインデックス不要なファイルもあります。

• ロックファイル：package-lock.json（AI は見る必要なし）
• テストカバレッジ：coverage レポート

だから .cursorignore で個別に制御する必要があるのです。

汎用設定テンプレート（コピペ用）

多くのプロジェクトで使えるテンプレです。ルートディレクトリに .cursorignore を作り、貼り付けてください。

# 依存ディレクトリ
node_modules/
.pnp/
.pnp.js
vendor/
.venv/

# ビルド生成物
dist/
build/
.next/
out/
.cache/
.parcel-cache/

# ログと一時ファイル
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
Thumbs.db

# IDE・エディタ設定
.idea/
.vscode/
*.swp
*.swo

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

# 静的リソース（必要に応じて）
*.mp4
*.avi
*.mov
*.zip
*.tar.gz

# 巨大なJSON・ロックファイル
package-lock.json
yarn.lock
pnpm-lock.yaml

注意：プロジェクトに合わせて調整してください。Python なら __pycache__/ や *.pyc を追加します。

設定後の検証方法

設定したら、本当に効いているか確認しましょう。

方法1：インデックス速度を見る
プロジェクトを閉じて開き直します。右下の “Indexing…” プログレスバーを見ます。設定前は数分かかっていたのが、30秒〜1分で終わるはずです。

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

方法2：インデックスファイル数を確認
設定画面（Settings）で “Codebase Index” を検索。現在のインデックス済みファイル数が表示されます。数万から数百に減っていれば成功です。

方法3：@Codebase テスト
@Codebase プロジェクトにはどんなファイルがある？ と聞いてみます。node_modules 内のファイルが出てこなければ設定成功です。

よくある問題と解決策

インデックス失敗、検索が遅い、CPU 暴走……90%の人が通る道です。よくある4つの問題の解決策をまとめました。

問題1：インデックス失敗 / “Indexing…” から進まない

症状：いつまで経っても終わらない、失敗する、@Codebase が反応しない。

原因と対策：

1. ファイル多すぎ：.cursorignore で node_modules 等を除外する。
2. 巨大/破損ファイル：10MB超のファイルやバイナリを .cursorignore に追加。
3. ディスク容量不足：インデックスはローカル保存です。5GB程度の空きが必要です。
4. ネットワーク：クラウド同期（Privacy Mode オフ）の場合、ネットワークを変えてみる。

問題2：@Codebase の検索結果が不正確

症状：あるはずのコードが見つからない、無関係なコードが出る。

原因と対策：

1. インデックス古い：コマンドパレット（Cmd/Ctrl+Shift+P）→ “Reindex Codebase” を実行。
2. 書き立てのコード：反映に1-2分のラグがあります。少し待つか手動インデックス。
3. 質問が曖昧：「バグ直して」ではなく「ログイン後のトークン保存失敗を直して」と具体的に。
4. 誤って除外：.cursorignore で src などを間違って消していないか確認。

問題3：CPU/メモリ使用率が高すぎる

症状：ファンがうるさい、PCが重い。

原因と対策：

1. 大量インデックス中：初回は仕方ありません。完了を待つか、無関係なファイルを除外して減らします。
2. 頻繁な更新：設定 → “Codebase Index” → “Update frequency” を “On save only” に変更。
3. インデックス破損：インデックスキャッシュフォルダを削除して再生成。

問題4：@Codebase の応答が遅い

原因と対策：

1. インデックス肥大化：ファイル数を500〜2000程度に抑えるのが理想。
2. クエリ範囲が広すぎ：より具体的な質問にするか、@Files を使う。
3. スペック不足：メモリ16GB以上推奨。

実戦事例：Next.js プロジェクトのゼロから設定

論より証拠。実際の Next.js プロジェクトでの設定フローです。10分で終わります。

実戦結果：Before / After

実際の Next.js プロジェクトでの計測結果です：

AI 提案精度は、実際に20個の開発上の質問をして、回答が使えるかどうかで判断しました。設定後の精度向上は劇的でした。

結論

AI がいくら進化しても、コンテキスト（文脈）がなければただのブラックボックスです。インデックス設定は、AI にあなたのプロジェクトという文脈を与えるための架け橋です。

3つの重要ポイント：

1. 仕組みを知る：なぜ node_modules を除外すべきか、なぜ検索が遅れるか、仕組みが分かれば対策できます。
2. .cursorignore は最優先：これだけで速度も精度も劇的に変わります。必須です。
3. @シンボルを使い分ける：8割は @Codebase、細かい制御は @Files。これで迷いません。

今すぐやるべき3ステップ：

1. プロジェクトルートに .cursorignore を作り、テンプレートを貼る。
2. Cursor を再起動し、インデックス速度の違いを体感する。
3. @Codebase で、これまで AI が苦手だった質問をしてみる。

たった10分の投資で、今後の開発時間の何百時間を節約できます。
Cursor のインデックス機能は日々進化しています。この記事は2026年1月時点のものです。最新情報は公式ドキュメントも併せて確認してください。さあ、設定して快適な AI 開発を始めましょう。

8 min read · 公開日: 2026年1月15日 · 更新日: 2026年2月4日

Easton

技術開発