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

2026-06-08 更新：2026 年 6 月の Cursor 公式ドキュメントで再確認しました。Cursor は .gitignore と組み込みのデフォルト無視リストを最初から尊重します（node_modules、ロックファイル、ビルド成果物、バイナリ/メディアの多くはすでにインデックス対象外）。そのため .cursorignore は主に「アクセスの完全遮断＋追加除外」用です。.cursorindexingignore はインデックスのみを除外し、@ 参照では読み取れます。また、ルート直下の単一 .cursorrules は現在 legacy 扱い（Agent モードでは無視）で、プロジェクトルールは .cursor/rules/ 配下の .mdc を使ってください。

先週の火曜日の午後、50 万行を超える Monorepo プロジェクトを Cursor で開きました。右下の Syncing アイコンが回り始め、5 分経っても止まりません。10 分経っても、まだインデックス中。コーヒーを淹れて戻ってきても、ゆっくりと回り続けていました。

さらに厄介なのがその後です。ようやくインデックスが終わり、React コンポーネントの最適化を AI に頼むと、こんな提案が返ってきました。「node_modules/react-dom/cjs/react-dom.development.js を直接編集できます」。画面を 3 秒見つめました——AI が依存パッケージ内のコードを、自分のプロジェクトコードだと勘違いしていたのです。

そのときは、Cursor が大規模プロジェクト向きではないのでは、と本気で疑いました。.cursorignore という設定ファイルを見つけてから、状況は一変しました。インデックス時間は 12 分から 3 分へ、AI も node_modules 内のファイルを書き換えるよう提案しなくなりました。

Cursor のインデックスが遅い、AI の理解がズレる——そんな悩みを抱えているなら、すぐ効果が出る最適化戦略 3 つと、そのまま使える設定テンプレートで解決していきましょう。

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

まず Cursor のインデックスの仕組みから。プロジェクトを開くたび、Cursor はコードファイルを埋め込みベクトルに変換します——簡単に言えば、コードを 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 が書けるなら、この設定も問題ありません。

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

今すぐ始める →広告

基本構文クイックリファレンス

プロジェクトルートに .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 と構文が同じなので、設定のデバッグに使えます。

.cursorignore vs .cursorindexingignore — 正しいツールの選び方

最初にこの 2 つの設定ファイルに出会ったとき、私も混乱しました。名前が似ている——どちらを使えばいいのか？

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

本質的な違い

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

.cursorindexingignore：コードベース検索結果には出ませんが、AI は必要に応じて（@ 参照やドラッグ＆ドロップで）読み取れます。パフォーマンス最適化のために後から追加された機能です。

例：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 つのパッケージは実行環境がまったく異なります。

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

15%割引を入手 →広告

その後、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 を用意し、作業内容に応じて .cursorignore にコピーするとよいでしょう。

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

Monorepo 最大の問題は、AI が各ディレクトリの関係を理解していないことです。Project Rules で AI にプロジェクトの地図を渡します。注意：ルート直下の単一 .cursorrules は現在 legacy 扱いで Agent モードでは無視されるため、新規プロジェクトでは .cursor/rules/ 配下の .mdc（.cursorignore ではありません）を使ってください。

.cursor/rules/ にルールファイル（例：project-structure.mdc）を作成し、先頭に YAML frontmatter（description、globs、alwaysApply）を置いてからプロジェクトの地図を書きます。

---
description: monorepo のプロジェクト構造とコード参照ルール
alwaysApply: true
---

# プロジェクト構造説明

これは 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 に読み込まれ、プロジェクト構造の理解を助けます。設定後、境界を越えたコード参照の提案はほとんど出なくなりました。

戦略 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 で質問し、回答に除外したファイルが含まれていないか確認します。node_modules を除外した後、「プロジェクトにどんな React コンポーネントがある？」と聞き、node_modules/react 以下が列挙されなければ OK です。

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

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

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

• .cursorignore を修正した
• 大幅に変更された Git ブランチに切り替えた
• 大量のファイルを一括削除・追加した
• AI の理解が不正確で、インデックスが古い可能性を感じた

更新方法：Settings > Features > Codebase Indexing > Refresh をクリック。プロジェクト全体が再インデックスされ、Syncing 完了を待ちます。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

設定の日常メンテナンス

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

月次チェックリスト：

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

チーム開発の提案：

チームプロジェクトで .cursorignore を Git にコミットすべきか？ケースバイケースです。

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

.gitignore に次の 1 行を追加する方法もあります。

.cursorignore.local

個人設定を .cursorignore.local に書き、.cursorignore から参照します（Cursor が include 構文をサポートしていれば）。

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

.cursorignore 内で、なぜそのディレクトリを除外したかコメントしておく習慣が役立ちます。

# 2025-01-15: 新規 AI 学習データディレクトリを除外。ファイルが大きすぎてインデックス不要
data/training/

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

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

関連記事

• Cursor コードベースインデックス完全ガイド：仕組み・設定・@ 記号の使い方
• Cursor 大規模プロジェクト実践：大きなリポジトリで Agent を迷子にさせない
• Cursor 無料枠完全ガイド

まとめ

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

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

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

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

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

一度に完璧を目指す必要はありません。基本テンプレートで 80% を解決し、残り 20% は実際の使用の中で少しずつ調整すれば十分です。

大規模プロジェクトで Cursor を使っているなら、ぜひこれらの戦略を試してみてください。コメント欄で設定の経験や困ったことを共有していただければ、同じ悩みを持つ開発者の助けになるかもしれません。