Cursor .cursorignore 設定完全ガイド：大規模プロジェクトのインデックスを最適化する3つの重要戦略

先週の火曜日の午後、私は会社の50万行以上ある Monorepo プロジェクトを開きました。Cursor の右下にある Syncing アイコンが回転し始めました。5分経っても、まだ回っています。10分経っても、インデックス作成は続いています。コーヒーを一杯入れて戻ってきても、まだのんびりと回り続けていました。

さらに絶望的なことが起きました。ようやくインデックス作成が終わったと思い、AI に React コンポーネントの最適化を頼んだところ、こんな提案が返ってきたのです。「node_modules/react-dom/cjs/react-dom.development.js ファイルを直接修正することをお勧めします」。私は画面を見つめて3秒間沈黙しました——AI は依存パッケージの中身を私のプロジェクトコードだと勘違いしていたのです。

正直なところ、その瞬間は「Cursor は大規模プロジェクトには向いていないのでは？」と疑いました。しかし、.cursorignore という設定ファイルの存在を知ってから、世界が変わりました。インデックス作成時間は12分から3分に短縮され、AI が node_modules 内のコード修正を勧めてくることもなくなりました。

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

価格を見る →広告

もしあなたも Cursor のインデックスが遅い、AI の理解が的外れだという問題に直面しているなら、この記事が完全に解決します。即効性のある3つの最適化戦略と、そのままコピーして使える設定テンプレートを共有します。

なぜあなたの Cursor インデックスはこんなに遅いのか

まず Cursor のインデックスメカニズムについて説明します。プロジェクトを開くたびに、Cursor はコードファイルを embedding ベクトルに変換します——簡単に言えば、コードを AI が理解できる数値表現に変えるのです。このプロセスは各ファイルを走査し、ベクトルを計算し、保存する必要があります。ファイルが多ければ多いほど、この処理は遅くなります。

ここで問題です：あなたのプロジェクト内のすべてのファイルが、本当に AI に理解される必要がありますか？

ほとんどのプロジェクトには、サイズが大きく数も多いが、AI 支援プログラミングにはほぼ無意味なファイルが存在します：

node_modules - 依存関係のブラックホール
中規模のフロントエンドプロジェクトでも、node_modules には数万ファイルが含まれていることがあります。React プロジェクトでいくつか依存関係を入れるだけで、ファイル数は軽く1万を超えます。Cursor は毎回これらのサードパーティコードをインデックスしますが、本当に lodash の内部実装を AI に理解させる必要がありますか？

dist/build - コンパイルの残骸
これらはビルドツールが生成した圧縮・難読化されたコードです。1行に圧縮された JavaScript ファイルを AI にインデックスさせるのは、解読不能な古文書を読ませるようなもので、全く無意味です。

.git - 歴史の重荷
Git リポジトリにはプロジェクトの全履歴が隠されています。大規模プロジェクトの場合、.git フォルダは数百MBから数GBにもなります。これらの履歴データをインデックスするのは時間の無駄です。

巨大な静的リソース
動画、画像、フォントファイル……これらは AI には読めません。インデックスするのは全くの無駄骨です。

私はテストを行いました：完全な node_modules と .next ビルドディレクトリを含む10万行の Next.js プロジェクトで、インデックス作成に8分かかりました。.cursorignore を設定してこれらを除外したところ、時間は2分に短縮されました。4倍の差です。

さらに重要なのは精度です。AI のコンテキストが node_modules のコードで埋め尽くされていると、どれがあなたのコードで、どれが依存ライブラリなのか混同しやすくなります。その結果、依存パッケージの修正を提案したり、サードパーティライブラリの API を自作関数と勘違いしたりするのです。

.cursorignore 完全設定ガイド

良いニュースがあります。.cursorignore の構文は .gitignore と全く同じです。もし .gitignore が書けるなら、この設定ファイルも朝飯前です。

基本構文クイックルック

プロジェクトルートに .cursorignore ファイルを作成し（先頭のドットを忘れずに）、以下のルールで記述します：

# これはコメントです。# で始めます

# 特定のファイルを除外
config.json

# ディレクトリ全体を除外（末尾にスラッシュ）
node_modules/
dist/

# ワイルドカード一致
*.log          # 全てのログファイル
**/*.test.js   # 任意の階層のテストファイル

# 否定ルール（再包含）
!important.log # 全ての .log を除外するが、これは残す

そのまま使える設定テンプレート

多くのプロジェクトに適した基本設定をまとめました。これをコピーして .cursorignore ファイルに貼り付けてください：

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

# ビルド生成物
dist/
build/
out/
.next/
.nuxt/
.cache/
.vite/
.turbo/

# テストとカバレッジ
coverage/
.nyc_output/
*.spec.js
*.test.js
__tests__/

# ログと一時ファイル
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
.DS_Store
*.swp
*.swo
*~

# 環境設定（セキュリティ考慮）
.env
.env.local
.env.*.local
credentials.json
*.key
*.pem

# バージョン管理
.git/
.svn/
.hg/

# IDE設定（任意）
.vscode/
.idea/
*.sublime-*

# 巨大リソースファイル（必要に応じて調整）
*.mp4
*.mov
*.avi
*.zip
*.tar.gz
*.pdf
public/videos/

この設定で一般的なシナリオの90%をカバーできます。保存後、Cursor の Settings > Features > Codebase Indexing を開き、リフレッシュボタンをクリックして設定を適用してください。

シーン別・応用設定

プロジェクトタイプに応じて、基本テンプレートに調整を加えることができます：

React/Vue プロジェクト：public ディレクトリの大ファイルを除外

# 基本設定に追加
public/assets/
public/images/*.png
public/fonts/

Monorepo プロジェクト：無関係なサブパッケージを除外（これ重要）

# フロントエンドチームの場合、apps/web だけ関心があるなら
apps/mobile/
apps/admin/
packages/backend-utils/

フルスタックプロジェクト：前後分離インデックス

# フロントエンド中心なら
server/
api/
database/
migrations/

# バックエンド中心なら
client/
public/
src/components/

ちょっとしたコツ：あるファイルが除外されているか不確かな場合、ターミナルで以下を実行してください：

git check-ignore -v [ファイルパス]

これは git のコマンドですが、.cursorignore は構文が同じなので、設定のデバッグに使えます（ただしファイル名は .gitignore として読む必要があるので、一時的にリネームするか脳内変換してください）。※訳注: 正確には git コマンドは .gitignore を読むため、.cursorignore の確認には使えませんが、構文チェックの代用として記載されています。

.cursorignore vs .cursorindexingignore - 正しいツールの選択

最初にこの2つの設定ファイルに出会った時、私も混乱しました。名前が似ていますが、一体何が違うのでしょうか？どちらを使うべきでしょうか？

簡単に言えば：.cursorignore は完全遮断、.cursorindexingignore は半遮断です。

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

15%割引を入手 →広告

本質的な違い

.cursorignore：AI はこれらのファイルに一切アクセスできません。インデックスもせず、読み取らず、参考にしません。Cursor にとってこれらのファイルは存在しないも同然です。これは2つのケースで使います——セキュリティ機密ファイル（.env、キーファイル）か、AI が触れる必要が全くないもの（node_modules、ビルド生成物）。

.cursorindexingignore：ファイルはコードベース検索結果には出ませんが、AI は必要に応じてそれらを読み取ることができます。Cursor 0.46 バージョンで追加された機能で、特にパフォーマンス最適化のために使われます。

例を挙げましょう：古いプロジェクトの legacy/ ディレクトリに、3年前の遺産コードがあるとします。検索結果を汚したくはありませんが、たまに AI が古い実装ロジックを参照する必要があるかもしれません。そんな時こそ .cursorindexingignore の出番です。

使用シーン対照表

設定の優先順位

Cursor は以下の順序で設定を処理します：

1. まずプロジェクト内の .gitignore を読む（自動準拠）
2. 次に .cursorignore を読む（! 構文で gitignore を上書き可能）
3. 最後に .cursorindexingignore を適用する

これはどういうことかというと、例えば .gitignore で logs/ ディレクトリを除外していても、特定のログファイルを AI に読ませたい場合は、.cursorignore にこう書けば良いのです：

!logs/important-debug.log

また、“Hierarchical Cursor Ignore”（階層的無視）という機能もあります（Settings で設定可能）。オンにすると、Cursor は親ディレクトリの .cursorignore ファイルを再帰的に探します。大規模 Monorepo のルートにグローバル設定を置き、サブプロジェクトで追加設定を行うのに適しています。

私の使用戦略

正直なところ、ほとんどの場合 .cursorignore だけで十分です。.cursorindexingignore は、極めて高いパフォーマンスが求められる場合や、プロジェクト構造が特に複雑な場合の「微調整ツール」のようなものです。

設定の始め方として、以下をお勧めします：

• ステップ1：まず .cursorignore だけを使い、明確に不要なものを除外する。
• ステップ2：1週間様子を見て、AI の挙動を確認する。
• ステップ3：まだ問題がある場合のみ、.cursorindexingignore で詳細調整を行う。
  最初から複雑にしすぎず、段階的に進めるのが効果的です。

Monorepo プロジェクトの3つの最適化戦略

Monorepo は Cursor が最も「崩壊」しやすいプロジェクトタイプです。1つのリポジトリにフロントエンド、バックエンド、モバイル、管理画面などが混在しており、AI はこれほど多くのコードを前にして理解にズレが生じやすくなります。

私は12個のサブアプリを含む Monorepo プロジェクトで痛い目に遭いました。AI にフロントエンドコンポーネントの最適化を頼んだところ、バックエンド API ディレクトリにあるユーティリティ関数をインポートするよう提案されました。理にかなっているように聞こえますが、問題はフロントエンドからバックエンドのコードにはアクセスできないことです。これら2つのパッケージは実行環境が全く異なります。

その後、3つの非常に実用的な最適化戦略をまとめました：

戦略1：作業領域ごとのインデックス分割

最もシンプルで直接的な方法——関心のないサブプロジェクトを除外することです。

あなたがフロントエンドチームの一員で、主に apps/web ディレクトリで作業しているなら、他のサブアプリはすべて除外してしまいます：

# .cursorignore
apps/mobile/
apps/admin/
apps/api/
packages/backend-utils/
packages/database/
services/

これには2つの利点があります：一つはインデックスが速くなること、もう一つは AI が他のサブプロジェクトのコードに邪魔されないことです。ある Monorepo で自分の担当の2パッケージだけを残したところ、インデックス時間は15分から4分に短縮されました。

もしフルスタック開発者で、前後頻繁に切り替える必要があるなら、.cursorignore.frontend と .cursorignore.backend という2つのファイルを用意し、現在の作業内容に応じて .cursorignore に内容をコピーすると良いでしょう。

戦略2：Project Rules で AI にプロジェクト構造を教える

Monorepo 最大の問題は、AI が各ディレクトリ間の関係を理解していないことです。そこで .cursorrules ファイル（.cursorignore ではありません）を使って、AI にプロジェクトの地図を渡します。

プロジェクトルートに .cursorrules ファイルを作成します：

# プロジェクト構造説明

これは Monorepo プロジェクトで、以下のサブアプリを含みます：

- apps/web: フロントエンドアプリ (Next.js), ポート3000
- apps/api: バックエンドAPI (Node.js + Express), ポート8000
- apps/admin: 管理画面 (React), ポート3001
- packages/ui: 共有UIコンポーネントライブラリ
- packages/utils: 汎用ユーティリティ関数

## コード参照ルール

- フロントエンドアプリ (web/admin) は packages/ui と packages/utils のみ参照可能
- フロントエンドから apps/api のコードを直接参照禁止
- 共有パッケージ (packages/*) は具体的アプリ (apps/*) に依存してはならない

## 現在の作業重点

現在は主に apps/web を開発中です。最適化の提案はフロントエンドコードに集中してください。

このファイルは AI に読み込まれ、プロジェクト構造の理解を助けます。効果はてきめんで、設定後は境界を超えたコード参照を推奨してくることがほとんどなくなりました。

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

今すぐ始める →広告

戦略3：ウィンドウ分割ワークスタイル

超大規模 Monorepo（例えば20以上のサブアプリを含む）の場合、.cursorignore を設定しても、単一ウィンドウのコンテキストは大きすぎます。

この場合、私のやり方はこうです：各サブアプリごとに独立した Cursor ウィンドウを開きます。

• ウィンドウ1：apps/web ディレクトリを開く
• ウィンドウ2：apps/api ディレクトリを開く
• ウィンドウ3：packages/ui ディレクトリを開く

各ウィンドウは独自のインデックスとコンテキストを持つため、AI の理解がより正確になります。欠点はウィンドウ間の切り替えが必要なことですが、大規模プロジェクトにおいてはこの手間で得られる精度向上には価値があります。

小技：サブアプリ間に依存関係がある場合（例：web が ui コンポーネントに依存）、web のウィンドウで @folder を使って明示的に参照させることができます：

@folder packages/ui Buttonコンポーネントのprops定義を確認して

これでウィンドウを軽量に保ちつつ、必要な時に依存パッケージのコードにアクセスできます。

Monorepo の核心思想

まとめると、Monorepo 最適化の核心は：AI に必要なものだけを見せることです。

プロジェクトが大きければ大きいほど、引き算が必要です。AI があなたと同じようにプロジェクト全体のアーキテクチャを理解できると期待せず、能動的に境界線を引いてあげることで、より的確なアドバイスが得られます。

設定の検証とメンテナンス

.cursorignore の設定は、一度やれば終わりではありません。設定が効いているか検証し、定期的にメンテナンスする必要があります。

設定が有効か確認する

最も直感的な方法はインデックス時間を見ることです。設定前後の Syncing 時間を比較し、明らかに速くなっていれば設定は効いています。

より正確な検証方法：

1. インデックス状態の確認
   Settings > Features > Codebase Indexing を開くと、インデックスされたファイル数が表示されます。.cursorignore 設定後、この数字は大幅に減っているはずです。

2. AI コンテキスト範囲のテスト
   @codebase を使って AI に質問し、回答に除外したファイルが含まれていないか確認します。例えば node_modules を除外した後、「プロジェクトにはどんな React コンポーネントがある？」と聞き、node_modules/react 以下のコンポーネントが列挙されなければOKです。

3. 検索機能の検証
   Cursor のコード検索（Cmd/Ctrl + P）で、明確に除外したディレクトリ内のファイル名を検索してみます。もしヒットしなければ、設定は成功しています。

手動でインデックスを更新すべき時

Cursor はファイルの変更を自動検知して差分更新を行いますが、以下の場合は手動更新が必要です：

• .cursorignore 設定ファイルを修正した
• Git ブランチを大幅に変更した
• 大量のファイルを一括削除/追加した
• AI の理解が不正確で、インデックスが古い可能性があると感じた時

更新方法：Settings > Features > Codebase Indexing > Refresh ボタンをクリックするだけです。リフレッシュするとプロジェクト全体が再インデックスされます。Syncing 完了を待ちましょう。

設定の日常メンテナンス

.cursorignore は書き捨てではありません。プロジェクトの進行に伴い、調整が必要です：

月次チェックリスト：

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

価格を見る →広告

• 新しいビルドディレクトリが除外されているか（例：フレームワーク更新で .output/ が増えた等）
• 新たに巨大ファイルディレクトリが増えていないか
• 以前除外したディレクトリがまだ存在するか（無効な設定の掃除）

チームコラボレーションの提案：

チームプロジェクトの場合、.cursorignore を Git にコミットすべきでしょうか？私の提案はケースバイケースです：

• 汎用除外ルール（node_modules、dist 等）：Git にコミットし、チーム全員で恩恵を受ける。
• 個人の作業設定（特定のサブプロジェクト除外）：コミットしない、または .git/info/exclude に追加する。

.gitignore に以下の一行を追加するのも手です：

.cursorignore.local

そして個人設定を .cursorignore.local に書き、.cursorignore からそれを参照する（もし Cursor が include 構文をサポートしていればですが、現状は手動管理が無難です）。

除外理由をコメントに残す

この習慣は非常に役立ちます。.cursorignore 内に、なぜそのディレクトリを除外したかコメントしておきましょう：

# 2025-01-15: 新規AI学習データディレクトリを除外、ファイルサイズ過大のため
data/training/

# 2025-01-10: パフォーマンステスト用ディレクトリを一時除外、大量のログを含むため
perf-tests/

3ヶ月後に設定を見返した時、当時の自分に感謝することになるでしょう。

まとめ

冒頭の問いに戻ります：Cursor のインデックスが遅い、AI の理解がズレている、これはツールが悪いのでしょうか？

いいえ。多くの場合、私たちが AI に「何を見るべきか、何を無視すべきか」を教えていないことが原因です。

.cursorignore はシンプルですが強力なツールです。5分かけて設定するだけで、今後の開発で数時間の待ち時間を節約でき、何より AI からより正確なアドバイスが得られます。

3ステップ・アクションリスト：

1. 即実行：この記事の基本テンプレートをコピーし、プロジェクトルートに .cursorignore ファイルを作成する。
2. カスタム最適化：プロジェクトタイプ（React/Vue/Monorepo）に合わせて、除外ルールを追加する。
3. 継続的改善：一週間 AI の挙動を観察し、問題を記録し、設定を微調整する。

一度に完璧な設定を目指す必要はありません。まずは基本テンプレートで80%の問題を解決し、残りの20%は実際の使用過程で少しずつ調整していけば良いのです。

もしあなたも大規模プロジェクトで Cursor を使っているなら、ぜひこれらの戦略を試してみてください。

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

Easton

技術開発