言語を切り替える
テーマを切り替える

Cursor Codebase インデックス完全ガイド:仕組み、設定、@ シンボル実践

2026-06-08 更新:Cursor 公式ドキュメントで仕組みと privacy を再確認——インデックス設定は Cursor Settings → Indexing & Docs に移動(「View included files」で対象を確認可)。コードチャンクは暗号化のうえ Cursor のサーバーへ送られて埋め込みを生成し、リモートのベクトル DB に保存されます(純粋なローカル FAISS ではありません)。ただしソースコードは平文保存されず、6 週間アクセスがないと削除、同期は約 5 分ごと。以下はこれに合わせて修正済みです。

画面に表示された、Cursor による 5 回目の的外れな提案。

「ログインバグを修正して」——要件は明確だった。それなのに Cursor が返したコードは、プロジェクト内に既にある auth ユーティリティ関数を知らず、検証ロジックを一から書き直させようとした。さらに、プロジェクトに存在しない utils ディレクトリへコードを置くよう提案してきた。

そのとき気づいた。AI がどれだけ賢くても、プロジェクト全体が見えなければ、ただのコード生成マシンに過ぎない。提案はいつも的外れになる。

20 分かけて Codebase インデックスと .cursorignore を設定した。もう一度試すと、Cursor は即座に auth ユーティリティを見つけ、3 箇所の重複した検証コードを統合する提案までしてくれた。「AI がやっと自分のプロジェクトを理解してくれた」——その感覚は本当に気持ちいい。

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

Codebase インデックスとは?

「インデックス」と聞くと難しそうに感じるかもしれません。実際は、仕組みを理解すればシンプルです。

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

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

具体的には、コードファイルをスキャンし、各関数・クラス・変数の役割を分析して、数学的手法(ベクトル化)で「タグ」を付けます。質問すると、最も関連性の高いコード断片を瞬時にマッチングできるのです。

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

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

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

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

ステップ 2:コードのチャンク化

スキャン後、Cursor はファイルを丸ごと扱いません。関数、クラス、論理ブロックごとに分割します。1000 行のユーティリティファイルなら 30 個程度の小ブロックに分かれ、個別にインデックスされます。クエリ精度が上がります。

ステップ 3:ベクトル埋め込み(ここが核心)

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

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

多くのガイドがここを誤解しています。実際には、コードチャンクは暗号化のうえ Cursor のサーバーへアップロードされて埋め込みが生成され、そのベクトルは難読化されたファイルパスや行番号とともにリモートのベクトルデータベース(Cursor は Turbopuffer のようなサービスを使用)に保存され、Merkle ツリーで差分同期されます。つまりインデックスは純粋なローカルではありません。ただし Cursor はソースコードを平文保存せず(リクエスト後に破棄)、ファイル名は難読化・暗号化、インデックスは 6 週間アクセスがないと削除されるとしています。

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

「ログインロジックを最適化して」と入力すると、Cursor はその文もベクトル化し、DB 内で「指紋」が最も近いコードブロックを検索します。ミリ秒単位で完了します。

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

関連コードが見つかると、Cursor はそれらを AI へのコンテキストに挿入します。AI は実際のコードを見た上で回答するため、提案が的確になります。

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

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

現在のファイル + 手動 @ の 1〜3 ファイル
未インデックス時の AI 理解範囲
プロジェクト全体 + 自動関連付け 10+ ファイル
インデックス時の AI 理解範囲
2 時間から 15 分に短縮
ファイル間バグの修正時間
3 倍
コード提案の精度向上

差は歴然です。API 層・データ層・UI 層の 3 ファイルが絡むバグに遭遇したことがあります。インデックスなしでは、3 ファイルを手動で @ し、関係性を説明する必要がありました。インデックスがあれば「なぜユーザーデータが更新されない?」と聞くだけで、Cursor が 3 ファイルを見つけ、さらに見落としていた 4 つ目(ミドルウェアのデータ検証)まで発見してくれました。

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

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

まず仕組みを正しく(多くのガイドが間違えています):インデックス時、コードチャンクは暗号化のうえ Cursor のサーバーへ送られて埋め込みを計算します。ただし保護はあります:

  1. ソースコードは平文保存されない——サーバーはリクエスト中のみ処理し、その後破棄。ベクトル DB に入るのはベクトルで、ソースコードではない
  2. ファイル名・パスは難読化・暗号化——ベクトルデータを得ても、プロジェクト構造は復元できない
  3. 6 週間で自動削除——長期間アクセスのないインデックスは削除され、再オープンで再インデックス
  4. Privacy Mode——Cursor 設定のプライバシーモードでデータ保持をさらに制限

金融・医療など強い機密性の案件では Privacy Mode を有効化し慎重に評価します。一般的な Web・個人開発はデフォルトで問題ありません。ただし「コードが一切ローカルから出ない」という説明は正確ではないので、認識しておきましょう。

@ シンボル完全ガイド

Cursor を使い始めた頃、@ は全部同じだと思っていました。実は奥が深く、使い方を間違えると時間を無駄にし、AI が的外れな提案をしてきます。

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

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

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

最も強力で、最も過小評価されている @ シンボルです。@Codebase 入力後、Cursor はインデックス DB に基づき、質問に最も関連するコード断片を自動で探します。

適用シーン

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

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

制約

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

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

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

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

適用シーン

  • 問題のあるファイルが特定できている
  • 特定ファイルのコードを修正したい
  • 無関係なコードで AI を混乱させたくない

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

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

@Folders - ディレクトリ指定

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

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

適用シーン

  • /components/auth/ 配下の全コンポーネントを最適化して」
  • /api/ ディレクトリのコードにセキュリティ問題がないか確認して」
  • 特定モジュールのコードを一括処理

注意:フォルダが大きすぎるとコンテキスト制限を超えます。10 ファイル以内が目安。数十ファイルあると、AI は先頭部分しか見られず、後半は切り捨てられることがあります。

@Code - 特定コード片

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

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

適用シーン

  • 「この validateUser 関数にバグがある。見てほしい」
  • 「このロジックをリファクタリングして見やすくして」
  • コードレビューで特定の断片を指定

お気に入りの使い方:1000 行のユーティリティファイルのうち、50 行の関数だけを見てほしいとき。@Code でその関数だけ渡せば、他のコードに気を取られず集中して解決してくれます。

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

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

2024 年末に Cursor に追加された機能で、まだ知らない人も多いです。

適用シーン

  • 「Next.js 公式ドキュメントを参考に、動的ルーティングを設定して」
  • 「この API ドキュメントに基づいて呼び出しコードを生成して」
  • 新技術を学ぶとき、ドキュメントと合わせて AI に提案させる

使い方@Docs と入力し、ドキュメント URL を入力するか、Cursor 内蔵の主要フレームワークドキュメントから選択。

制約

  • 一部の主要フレームワーク公式ドキュメントのみ対応
  • カスタム URL は失敗することも(ネットワークや形式非対応)

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

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

リリース直後のライブラリなど、AI の学習データにない情報が必要なときに使います。

適用シーン

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

注意:リアルタイム検索のためやや遅い。本当に最新情報が必要なときだけ使いましょう。

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

@ シンボル範囲速度適用シーン長所短所
@Codebaseプロジェクト全体遅(1〜3 秒)複数ファイル、学習、アーキテクチャ自動関連付け、網羅的インデックス依存、精度にムラ
@Files指定ファイル速(<1 秒)ファイル特定済み、正確な修正正確、制御可手動選択、漏れリスク
@Folders指定フォルダ中(1 秒)モジュール単位、一括処理範囲が適度サイズ制限あり
@Codeコード片速(<1 秒)関数単位、レビュー極めてフォーカス文脈不足のリスク
@Docs外部ドキュメント中(1〜2 秒)新技術学習、公式参照権威ある情報ドキュメント範囲に限界
@WebWeb 検索遅(2〜5 秒)最新情報、新ライブラリリアルタイム性遅い、不正確なことも

私の使い分け

最初は @Files ばかり使っていました。確実だと思ったからです。後から分かったのは、8 割は @Codebase の方が効率的だということ。AI に探させた方が、手動選択より速く、見落としも防げます。

現在の使用頻度:

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

そのまま真似する必要はありません。各 @ シンボルの特性を理解し、シーンに合わせて使い分けることが大切です。

.cursorignore 設定実践

ここまで来たら .cursorignore の話は欠かせません。地味ですが、設定するだけでインデックス速度が 50% 以上向上し、CPU 使用率が半減します。

初めて Cursor を使ったとき、.cursorignore を設定せず node_modules 込みのプロジェクトを開いたら、PC のファンがうるさく、Cursor がフリーズしかけました。3 万個の不要なサードパーティライブラリを必死にインデックスしていたのです。

なぜ .cursorignore が必要か?

理由はシンプル。すべてのファイルにインデックスする価値があるわけではないからです。

プロジェクトには次のようなファイルがあります:

  • 依存ファイル:node_modules、vendor、.venv 等。数万ファイルあるが、中身を触ることはほぼない
  • ビルド生成物:dist、build、.next 等。コンパイル生成物で、ソースコードではない
  • 一時ファイル:.log、.cache、.DS_Store 等。完全に無関係
  • 大型静的アセット:動画、画像、フォント。インデックスしても意味がない

これらを除外すれば、インデックス時間は 5 分から 30 秒に短縮され、無関係なコードに邪魔されず AI クエリもより正確になります。

.cursorignore vs .gitignore

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

答えは必要。両者のロジックは異なります

.gitignore は「バージョン管理に含めないファイル」を制御します。しかし、コミットしたくないが AI には見せたいファイルもあります:

  • ローカル設定.env.local(コミットしないが、AI には環境変数設定を知ってほしい)
  • 個人メモTODO.md(コミットしないが、AI に参照させたい)

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

  • package-lock.json:コミットするが、AI に見せる必要はない
  • テストカバレッジレポート:CI にコミットするが、インデックス不要

.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. 大型 monorepo の段階的インデックス

monorepo で数十のサブパッケージがある場合、全部インデックスすると遅くなります:

# 現在作業中のパッケージのみインデックス
packages/*/node_modules/
packages/package-a/  # 今は触らないパッケージ
packages/package-b/

必要になったらコメントを外します。

2. ホワイトリストモード

ファイルが乱雑なプロジェクトでは、除外リストより「これだけインデックス」の方が楽な場合も:

# すべて除外
*

# src ディレクトリのみ含める
!src/
!src/**/*

# 設定ファイルのみ含める
!*.config.js
!tsconfig.json

大型レガシープロジェクトで、AI にコアコードだけ見せたいときに有効です。

3. ファイルサイズでフィルタ

Cursor は超大ファイル(通常 >1MB)を自動スキップしますが、手動で除外することもできます:

# 大型データファイルを除外
*.sql
*.csv
*.json  # 数十 MB の JSON データがある場合

設定後の検証方法

.cursorignore を変更したら、効いているか確認しましょう。

方法 1:インデックス速度を見る

プロジェクトを閉じて開き直し、右下の「Indexing…」プログレスバーを観察。設定前は 3〜5 分かかっていたのが、30 秒〜1 分で終わるはずです。

方法 2:インデックスファイル数を確認

Cursor Settings → Indexing & Docs を開き、「View included files」で実際にインデックスされたファイルを一覧表示。3 万から数百に減っていれば成功です。

方法 3:@Codebase でテスト

@Codebase プロジェクトにはどんなファイルがある? と聞き、返ってきたファイル一覧を確認。node_modules 内のファイルが出てこなければ .cursorignore は有効です。

パフォーマンス最適化の効果比較

実際の Next.js プロジェクトで計測したデータ:

指標設定前設定後改善
インデックスファイル数28,634487-98%
インデックス時間4 分 23 秒41 秒-84%
CPU ピーク使用率95%42%-56%
@Codebase クエリ速度2.8 秒1.1 秒-61%

数字は嘘をつきません。.cursorignore の設定は、Cursor を使いこなす第一歩です。

よくある問題と解決策

Cursor を 1 年以上使って、インデックス失敗、クエリ遅延、CPU 暴走など、さまざまな坑に落ちてきました。90% の人が同じ問題に遭遇します。

この章では最も多い 4 つの問題と解決策を整理します。問題が起きたら、このチェックリストに沿って切り分ければ、ほとんど解決します。

問題 1:インデックス失敗、または「Indexing…」から進まない

症状

  • 右下がずっと「Indexing…」のまま、数十分経っても完了しない
  • 「Indexing failed」と表示される
  • @Codebase が全く反応しない

原因と解決策

原因 1:プロジェクトファイルが多すぎてタイムアウト

  • 解決:.cursorignore で node_modules 等を除外
  • 確認:プロジェクトを閉じて開き直し、2 分以内にインデックスが完了するか確認

原因 2:非対応または破損したファイル形式

  • 解決:超大ファイル(>10MB)やバイナリファイルを .cursorignore に追加
  • よくある例:動画、大型 SQL dump、コンパイル済みバイナリ

原因 3:ディスク容量不足

  • 解決:インデックスデータはローカル保存。5GB 以上の空きを確保
  • Mac:~/Library/Application Support/Cursor/
  • Windows:%APPDATA%\Cursor\

原因 4:ネットワーク問題(クラウド同期有効時)

  • 解決:Privacy Mode をオフにして試す、またはネットワークを変更
  • 一時対策:Privacy Mode 設定を確認するか、Cursor サーバーへ接続できるかネットワークを確認

クイックチェックリスト

☐ .cursorignore が設定されているか
☐ プロジェクトファイル数(1000 超なら最適化が必要)
☐ ディスク容量(5GB 以上)
☐ Cursor を再起動
☐ 古いインデックスキャッシュを削除して再インデックス

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

症状

  • プロジェクトに関連コードがあるのに @Codebase が見つけない
  • 返ってきたコードが全く関係ない

原因と解決策

原因 1:インデックスが不完全または古い

  • 解決:手動で再インデックス
  • 操作:Cmd+Shift+P(Mac)/ Ctrl+Shift+P(Windows)→「Reindex Codebase」→ Enter

原因 2:書き立てのコードがまだインデックスされていない

  • 解決:Cursor は自動で差分同期します(公式で約 5 分ごと)。少し待つか手動で Reindex

原因 3:質問が曖昧すぎる

  • 解決:「バグがある」ではなく「なぜログイン後に token が localStorage に保存されない?」のように具体化
  • 比較:
    • ❌「性能を最適化して」
    • ✅「リストコンポーネントの描画が遅い。再レンダリングの原因を特定して」

原因 4:関連コードが誤って除外されている

  • 解決:.cursorignore でコアコード(src 全体など)を誤って除外していないか確認

精度向上のコツ

  • 具体的な関数名、変数名、ファイル名を使う
  • 具体的なビジネスシーンを説明し、漠然とした質問を避ける
  • @Codebase が不正確なら @Files でファイルを指定

問題 3:Cursor の CPU / メモリ使用率が高い

症状

  • PC のファンがうるさい
  • Cursor の CPU 使用率が 80% 超
  • メモリが数 GB 消費
  • システム全体が重い

原因と解決策

原因 1:大量ファイルのインデックス中

  • 解決:正常な現象。完了を待つ
  • 持続する場合:.cursorignore でインデックスファイル数を減らす

原因 2:リアルタイムインデックス更新が頻繁すぎる

  • 解決:コードを頻繁に編集すると Cursor はインデックスを更新し続ける
  • 緩和策:Cursor はデフォルトで約 5 分ごとに自動差分同期。頻繁に変わる大型ディレクトリを .cursorignore に入れると再インデックス負荷を減らせる

原因 3:複数の大型プロジェクトを同時に開いている

  • 解決:各プロジェクトがリソースを消費。不要なウィンドウを閉じる

原因 4:インデックス DB の破損

  • 解決:インデックスキャッシュを削除して再インデックス
  • Mac:~/Library/Application Support/Cursor/Index/ を削除
  • Windows:%APPDATA%\Cursor\Index\ を削除

パフォーマンス最適化の提案

☐ .cursorignore でインデックスファイル数を減らす(目標:1000 ファイル未満)
☐ 不要なプロジェクトウィンドウを閉じる
☐ 頻繁に変わる大型ディレクトリを .cursorignore で除外し再インデックスを減らす
☐ プロジェクトが特大なら @Codebase の代わりに @Files を使う
☐ ハードウェアをアップグレード(16GB メモリ以上、32GB 推奨)

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

症状

  • 質問入力後、5〜10 秒待たないと応答がない
  • タイムアウトすることも

原因と解決策

原因 1:インデックス DB が肥大化

  • 解決:.cursorignore でインデックスファイル数を減らす
  • 理想:500〜2000 ファイルでクエリ速度が最も速い

原因 2:ネットワークが遅い(クラウドモデル使用時)

  • 解決:接続を確認するか、遅延の少ないモデルに切り替え
  • 設定 → Models → 低遅延モデルを選択

原因 3:マッチするコード量が多すぎる

  • 解決:@Codebase は関連コードを広く含めようとする。数十ファイルに及ぶと遅くなる
  • 最適化:質問を具体化するか、@Files で範囲を限定

原因 4:PC 性能不足

  • 解決:ベクトル検索には計算リソースが必要
  • 推奨:16GB メモリ以上、SSD

高速化のコツ

  • @Files@Folders を優先(@Codebase より速い)
  • 古いインデックスキャッシュを定期的にクリーンアップ
  • プロジェクトをモジュール化し、必要な部分だけ読み込む

私の切り分けの心得

問題が起きても慌てないで。インデックス問題の 9 割は、.cursorignore 未設定で無関係なファイルを大量にインデックスしていることが原因です。

私の切り分け順序:

  1. .cursorignore の設定を確認
  2. 手動で再インデックス
  3. CPU / メモリ使用率を確認し、性能問題か設定問題か判断
  4. それでもダメならインデックスキャッシュを削除して最初から

この順序で、ほとんどの問題は解決します。それでも解決しない場合は Cursor 自体のバグの可能性があり、公式 GitHub に issue を報告しましょう。

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

理論はここまで。実際の Next.js プロジェクトで、.cursorignore 作成から効果検証まで、一連の流れをデモします。

ついてきてください。10 分で完了します。

Next.js プロジェクトの Cursor インデックスをゼロから設定

.cursorignore の設定、インデックス状態の検証、@ シンボル機能のテストまでの実践フロー

Estimated time: PT10M

  1. 1

    Step 1: .cursorignore ファイルの作成

    プロジェクトルート(package.json と同階層)に .cursorignore を作成。
  2. 2

    Step 2: インデックス状態の検証

    設定が有効か確認する 3 つの方法:
  3. 3

    Step 3: @ シンボル機能のテスト

    各 @ シンボルが正常に動作するか確認。
  4. 4

    Step 4: 設定の最適化(任意)

    実際のニーズに合わせて .cursorignore をさらに調整。

実戦まとめ:設定前後の比較

コンポーネントライブラリ、API ルート、DB 連携を含む実際の Next.js プロジェクトでフルテストしました:

指標設定前設定後改善
初回インデックス時間4 分 23 秒41 秒84% 短縮
インデックスファイル数28,63448798% 削減
CPU ピーク使用率95%42%56% 低下
@Codebase クエリ速度2.8 秒1.1 秒61% 高速化
AI 提案精度(主観)60%92%53% 向上

最後の「AI 提案精度」は、20 個の実際の開発質問で AI の提案が使えるかを手動評価したものです。インデックス設定後、60% から 92% へと劇的に向上しました。

重要ポイント

この実践事例で押さえるべきこと:

  1. ✅ Next.js プロジェクト向け .cursorignore の作成方法
  2. ✅ インデックス設定が有効かどうかの検証方法
  3. ✅ @ シンボル機能のテスト方法
  4. ✅ 実際のニーズに合わせた設定の最適化

このフローは Next.js だけでなく、React、Vue、Angular、バックエンドプロジェクトにも応用できます。考え方は同じ——無関係なファイルを除外し、AI をコアコードに集中させる

関連記事

結論

ここまで来たら、そろそろ締めくくりましょう。

記事冒頭のシーン——深夜 1 時、Cursor の 5 回目の的外れな提案を見つめていたあの瞬間。あの挫折感、多くの人が経験しているはずです。AI がどれだけ強力でも、プロジェクト全体が見えなければ、ただの推測に過ぎません。

インデックス設定こそ、この問題を解く鍵です。

3 つの核心ポイント

  1. 原理を理解するのは見栄のためではなく、坑を避けるため。インデックスの仕組みが分かれば、なぜ node_modules を除外すべきか、なぜクエリが遅くなるか、なぜ AI がコードを見つけられないかが理解できます。

  2. .cursorignore は最優先。他は後回しでも、これだけは必須。インデックス速度 50% 向上、CPU 使用率半減、AI 精度 60% 向上——すべて実測データです。

  3. @ シンボルは暗記不要、シーンを理解すれば十分。8 割は @Codebase、2 割は @Files で正確に制御。使っていくうちに感覚が身につきます。

今すぐやる 3 ステップ

  1. プロジェクトルートに .cursorignore を作成し、本文のテンプレートをコピーして保存
  2. Cursor を再起動し、インデックス速度の変化を体感
  3. @Codebase でテスト——以前 AI が答えられなかった質問を試してみる

たった 10 分の投資で、これからの数百時間の開発効率が変わります。

この記事が役に立ったら、Cursor インデックスで苦しんでいる仲間にもシェアしてください。坑はみんな同じ道を通ります。1 つでも減らせれば十分です。

Cursor のインデックス機能は日々進化しています。本記事は 2026 年中頃の公式ドキュメントで再確認済みですが、今後新機能や新たな問題が出る可能性があります。本文で触れていない状況は、公式ドキュメントで最新情報を確認してください。

さあ、読むだけで終わらせず、設定を始めましょう。

FAQ

.cursorignore を設定したのに node_modules がインデックスされるのはなぜ?
考えられる原因は 3 つです。

1. 構文エラー:.cursorignore が UTF-8 で保存されているか、パスがスラッシュ付き(node_modules/)になっているか確認
2. 再インデックスが必要:設定後はプロジェクトを閉じて開き直すか、手動で再インデックス(Cmd+Shift+P → Reindex Codebase)
3. ファイル位置:.cursorignore はプロジェクトルート(package.json と同階層)に置く。サブディレクトリ不可

確認方法:Cursor Settings → Indexing & Docs を開き、「View included files」で実際にインデックスされたファイルと件数を確認。まだ数万件なら上記 3 点をチェック。
@Codebase と @Files はどちらが良い?いつどちらを使う?
どちらも用途が異なり、優劣はありません。

@Codebase が向く場面:
• 複数ファイルにまたがる問題調査(どのファイルか不明)
• 新規プロジェクトのコード構造の学習
• アーキテクチャレベルの質問(例:「プロジェクトの権限検証はどこで処理している?」)

@Files が向く場面:
• 問題のあるファイルが特定できている
• 特定ファイルを正確に修正したい
• 無関係なコードで AI を混乱させたくない

使い方の目安:8 割はまず @Codebase を試し、結果が不正確または遅い場合に @Files で指定。私の使用頻度は @Codebase 60%、@Files 30%、その他 10%。
インデックスが遅い、または失敗し続ける。素早く切り分けるには?
次の順で確認すれば、9 割は解決します。

1. .cursorignore の確認:node_modules、dist、.next 等の大型ディレクトリを除外しているか
2. プロジェクトファイル数:1000 を超えているなら設定をさらに厳格化
3. ディスク容量:5GB 以上の空きがあるか(Mac:~/Library/Application Support/Cursor/)
4. 手動再インデックス:Cmd+Shift+P → Reindex Codebase
5. 古いインデックスキャッシュ削除:Cursor を終了し、キャッシュディレクトリを削除してプロジェクトを開き直す

上記でも解決しない場合、破損または超大ファイル(>10MB)がないか確認し、手動で除外。
Cursor の CPU 使用率が高く、PC のファンがうるさい
CPU 高負荷はインデックス中によく起きます。

即効対策:
• インデックス完了を待つ(初回はリソースを多く使うが、完了後は正常化)
• 不要なプロジェクトウィンドウを閉じる(各プロジェクトがリソースを消費)

長期的な最適化:
• .cursorignore でインデックスファイル数を減らす(目標:1000 ファイル未満)
• 頻繁な大改変による再インデックスを減らす:Cursor は自動で差分同期(約 5 分ごと)。頻繁に変わる大型ディレクトリを除外すると負荷を最も減らせる
• ホワイトリストモード:src、app 等のコアディレクトリのみインデックス
• ハードウェア:メモリ 16GB 以上、32GB 推奨

設定後も高負荷が続く場合、インデックスキャッシュを削除して再インデックス。Mac:~/Library/Application Support/Cursor/Index/
.cursorignore と .gitignore の違いは?統合できる?
目的が異なるため、統合は非推奨です。

.gitignore:バージョン管理に含めないファイルを制御
.cursorignore:AI がインデックスしないファイルを制御

典型的な差異:
• .env.local:コミットしたくない(.gitignore)が、AI には環境変数設定を知ってほしい(.cursorignore には入れない)
• package-lock.json:コミットする(.gitignore 外)が、AI に見せる必要はない(.cursorignore に入れる)
• TODO.md:コミットしないが、AI に参照させたい

.cursorignore は「AI にこのファイルを見せる必要があるか」の原則で個別に管理し、.gitignore をそのままコピーしない。
インデックス設定後も @Codebase のクエリが遅い(5〜10 秒)。正常?
5〜10 秒は正常ではありません。通常は 1〜3 秒です。考えられる原因:

1. インデックスファイル数がまだ多い:設定のインデックスファイル数を確認。理想は 500〜2000、5000 超えると明らかに遅くなる
2. 質問が曖昧すぎる:@Codebase は関連コードを広くマッチする。「性能を最適化して」のような漠然とした質問は数十ファイルに及ぶ。具体例:「リストコンポーネントの描画が遅い。再レンダリングの原因を特定して」
3. ネットワーク遅延(クラウドモデル):接続を確認するか、遅延の少ないモデルに切り替え
4. PC 性能不足:ベクトル検索には計算リソースが必要。16GB メモリ + SSD 推奨

高速化のコツ:ファイルが特定できているなら @Files の方がはるかに速い(通常 1 秒未満)。
monorepo プロジェクトのインデックス設定は?全部インデックスすると遅すぎる
monorepo では段階的インデックス戦略を推奨します。

方法 1:現在作業中のパッケージのみインデックス
# .cursorignore
packages/*/node_modules/
packages/package-a/ # 今は触らないパッケージ
packages/package-b/
packages/package-c/

方法 2:ホワイトリストモードで特定パッケージのみ
*
!packages/my-working-package/
!packages/my-working-package/**/*
!packages/shared-utils/
!packages/shared-utils/**/*

方法 3:Cursor のマルチワークスペース機能
• monorepo ルート全体を開かない
• 作業中のサブパッケージディレクトリのみ開く
• パッケージ間の連携が必要なら @Files で個別参照

実測:50 パッケージの monorepo で全インデックスは 10 分、3 パッケージのみなら 1 分。

11分で読めます · 公開日: 2026年1月15日 · 更新日: 2026年6月15日

関連記事

コメント

GitHubアカウントでログインしてコメントできます