なぜプロジェクトが巨大化するとCursorの知能は劣化するのか？
大規模リポジトリでCursorを使っていて、こんな違和感を覚えたことはないでしょうか。
- 「ChatやComposerが、数世代前のビルドキャッシュや型定義（`.d.ts`）を参照して幻覚（ハルシネーション）を起こす」
- 「`@Codebase` でクエリを投げた際、期待したビジネスロジックではなく、モックデータやトランスパイル後のJavaScriptがコンテキストに混入する」
- 「コードベースのインデックス生成（Indexing）がいつまでも終わらず、CPUとメモリを異常消費する」
これらの問題の本質は、CursorのLLM自体の推論能力不足ではありません。AIコンテキスト（Vector Store / Embeddings）がノイズによって「汚染」されていることが原因です。
AIエディタにおける「コンテキストウィンドウ」および「ベクトル検索のTop-K」は有限のリソースです。LLMは与えられた入力空間（トークン）の中から確率論的に最適な解を導き出します。そこにビルド成果物、ミニファイされたバンドル、巨大なテスト用ダミーJSON、トランスパイルキャッシュなどの「人間が読まないファイル」が紛れ込むと、検索類似度スコアの上位をノイズが占有してしまいます。
本記事では、テックリードとしてチームの生産性を底上げするために不可欠な、Cursorのインデックスを極限まで研ぎ澄ます「三層防御アーキテクチャ」と、その具体的な構成例を徹底解説します。
—
1. Cursorインデックスの解剖学：ノイズ混入のメカニズム
Cursorは裏側でコードベース全体をチャンク（小さな意味単位のコード片）に分割し、Embeddingモデルを介して高次元ベクトル空間にマッピングしています。
[ワークスペース全体]
│
├─ 純粋なソースコード (.ts, .py, .go) ──> 【良質なコンテキスト】 ──> [高精度な回答]
│
└─ ノイズ群 (dist, .next, fixture.json, .map)
│
▼ (除外設定がない場合)
【ベクトルの汚染 (Embedding Pollution)】 ──> Top-K検索の乗っ取り ──> [ハルシネーション]
なぜ `.gitignore` だけでは不十分なのか？
Cursorはデフォルトで `.gitignore` を参照しますが、それだけでは以下のケースを防げません。
1. Git管理下にある巨大な静的アセット・テストデータ: モック用の巨大なJSON、フィクスチャ、スナップショット（Jest / Vitest）
2. ローカル解析用に一時的に追跡しているログやプロファイルデータ
3. 自動生成されたコード（Prisma Client、GraphQL Code Generator、OpenAPIクライアント等）: これらは型定義として存在すれば十分であり、AIが推論するコードロジックの参照先としては重複やノイズになりやすい
これらを排除し、「純粋なドメインロジック」と「最新のインターフェース」のみをAIに見せる必要があります。
—
2. 鉄壁の三層防御：除外設定のベストプラクティス
コンテキスト汚染を完全に遮断するには、3つのレイヤーで除外を設定します。
1. レイヤー1（Vector Indexingの除外）: `.cursorignore`
2. レイヤー2（エディタ監視・検索インデックスの除外）: `.vscode/settings.json` の `files.watcherExclude` / `search.exclude`
3. レイヤー3（プロンプト注入時の制御）: `.cursorrules`
【レイヤー1】本番運用のための `.cursorignore` 決定版
リポジトリルートに配置する `.cursorignore` です。モノレポ（Turborepo / Nx）やモダンフルスタック（Next.js, FastAPI, Go等）を想定し、過不足なくノイズを切り落とす設計にしています。
==========================================
Cursor AI Indexing Exclusion Rules
==========================================
— 1. ビルド成果物・トランスパイルコード —
JS/TSのビルド結果やマップファイルはAIにとって重複ノイズでしかない
dist/
build/
out/
.next/
.nuxt/
.svelte-kit/
.tsbuildinfo
.js.map
.css.map
— 2. パッケージマネージャ・依存関係 —
node_modules等はCursor内部でも一部ハンドリングされるが、明示的に遮断する
node_modules/
.pnpm-store/
vendor/
.venv/
venv/
__pypackages__/
— 3. 自動生成コード・スキーマクライアント —
※型定義としてAIが読む必要がない、純粋な機械生成の重複コード
プロジェクト特性に応じてコメントアウトを調整
src/generated/
api/client/
— 4. テスト成果物・スナップショット・フィクスチャ —
巨大なスナップショットやモック用JSONはEmbeddingのTop-Kを破壊する最たる原因
coverage/
.nyc_output/
__snapshots__/
cypress/screenshots/
cypress/videos/
test/fixtures/large-payload/
.test.ts.snap
.spec.tsx.snap
— 5. ログ・キャッシュ・プロファイリング —
.log
npm-debug.log
yarn-debug.log
pnpm-debug.log
.turbo/
.cache/
.parcel-cache/
.pytest_cache/
.ruff_cache/
.mypy_cache/
— 6. ドキュメント・メディアアセット・DBダンプ —
画像、バイナリ、巨大なシードデータはAIの思考を完全に狂わせる
public/assets/
.svg
.png
.jpg
.jpeg
.ico
.pdf
.wasm
.sql
.dump
.seed.json
— 7. ドキュメント生成ツール・環境設定 —
.docusaurus/
storybook-static/
.env
!.env.example
—
【レイヤー2】`.vscode/settings.json` によるエディタ負荷と検索ノイズの同時排除
`.cursorignore` でAIのベクトル空間を保護したら、次はエディタ内部のファイルウォッチャーと全体検索から不要ファイルを排除します。チームで共有するために `.vscode/settings.json` をリポジトリにコミットします。
{
// ==========================================
// ファイルウォッチャーの最適化 (CPU/メモリ負荷軽減)
// ==========================================
“files.watcherExclude”: {
“/.git/objects/“: true,
“/.git/subtree-cache/“: true,
“/node_modules//“: true,
“/.next/“: true,
“/dist/“: true,
“/build/“: true,
“/.turbo/“: true,
“/coverage/“: true
},
// ==========================================
// 検索・クイックオープンからの除外 (コンテキスト汚染防止)
// ==========================================
“search.exclude”: {
“/node_modules”: true,
“/bower_components”: true,
“/.code-search”: true,
“/dist”: true,
“/build”: true,
“/.next”: true,
“/.turbo”: true,
“/coverage”: true,
“/.min.js”: true,
“/.map”: true
},
// ==========================================
// Cursor固有のAIコンテキストチューニング
// ==========================================
// @Codebase インデックス生成時にGitignoreを厳密に尊重する
“cursor.general.useGitignore”: true
}
—
3. コンテキストをピンポイントで操る「神ショートカット」と作法
不要なファイルを削ぎ落とした後は、「必要なファイルだけを正確にLLMの視界へ送り込む」テクニックが不可欠です。
┌─────────────────────────────────────────────────────────────┐
│ 推奨コンテキスト注入フロー │
│ │
│ 1. [Cmd + I] でComposer起動 │
│ 2. @Files で直接関連するファイルのみを2〜4個指定 │
│ 3