【実務・中級編】Cursorの「Codebase Indexing」を理解する：AIにコード全体を理解させる設定術 – 軽量・高機能テキストエディタ生産性向上バイブル

Cursorの「Codebase Indexing」を極限まで使い倒す：AIにコードベース全体の文脈を完全同期させる設定術

テックリードとしてチームの開発生産性を最大化するうえで、今やAIエディタの選定と使いこなしは避けて通れないテーマだ。その中でも「Cursor」は、単なるコード補完の枠を超え、プロジェクト全体の文脈を理解した上でリファクタリングやアーキテクチャの提案まで行う「真のペアプログラマー」としての地位を確立しつつある。

しかし、現場のエンジニアから「CursorのAIがいまいちプロジェクトの意図を汲み取ってくれない」「存在しない関数を勝手に生成してハルシネーションを起こす」という相談をよく受ける。

その原因のほとんどは、Cursorの心臓部である「Codebase Indexing（コードベースインデックス）」の仕組みを理解し、適切に調律できていないことにある。

今回は、Cursorがローカルおよびリモートでコードをどのように解釈しているのかという内部挙動に踏み込み、AIの回答精度を極限まで引き上げるための `.cursorignore` の設計思想、そしてチーム開発全体に知見をスケールさせるためのベストプラクティスを解説する。

—

1. Codebase Indexingの内部メカニズム：AIはあなたのコードをどう理解しているのか？

Cursorの「Chat (Cmd/Ctrl + L)」や「Composer (Cmd/Ctrl + I)」で質問を投げた際、なぜAIは数万行あるプロジェクトの中からピンポイントで該当ファイルを特定し、依存関係まで考慮したコードを生成できるのか。

その裏側では、以下のようなパイプラインが高速で実行されている。

1. AST（抽象構文木）解析とチャンキング:
Cursorはプロジェクト内のファイルをスキャンし、言語ごとのASTパーサーを用いてコードを意味のある単位（関数、クラス、モジュール）に分割（チャンキング）する。単なるテキストの切り出しではなく、「どの関数がどこから呼ばれているか」という構造を保持する。
2. ローカル埋め込みベクトル（Embedding）の生成:
分割されたコード片は、ローカル環境で動作する軽量な埋め込みモデルによって高次元のベクトル空間に変換される。これにより、「認証処理」「非同期エラーハンドリング」といった意味的な近接性を数学的に計算できるようになる。
3. Vector DB（Vector Database）へのインデクシング:
生成されたベクトルデータは、プロジェクト内の `.cursor` ディレクトリ（またはユーザー領域）にキャッシュされる。
4. ハイブリッド検索（RAG）の実行:
ユーザーがプロンプトを入力すると、Cursorは「キーワード検索（BM25など）」と「ベクトル類似度検索」を組み合わせたハイブリッド検索を実行し、現在の文脈に最も関連性の高いコードスニペットをコンテキスト（Context）としてLLMへ送信する。

なぜインデックスが狂うのか？

この仕組みの最大の弱点は、「ゴミを入力すれば、ゴミが出る（Garbage In, Garbage Out）」という点だ。ビルド成果物、巨大なJSONスキーマ、自動生成されたモックファイル、サードパーティのトランスパイル済みコードなどがインデックスに含まれていると、ベクトル空間がノイズで汚染され、AIが本当に重要なビジネスロジックを見失ってしまう。

ここを制御するための要塞が、`.cursorignore` である。

—

2. 精度を劇的に高める `.cursorignore` の設計思想とベストプラクティス

`.gitignore` が「Gitの管理から外す」ためのものであるならば、`.cursorignore` は「AIの認知負荷（Cognitive Load）を下げ、フォーカスを研ぎ澄ます」ための設定だ。

無駄なファイルをインデックス対象から外すことで、ベクトル検索の精度が跳ね上がり、トークンの無駄消費（APIコストやコンテキストウィンドウの圧迫）を防ぐことができる。

以下に、実プロダクト（TypeScript / Node.js / React / Docker環境を想定）で即座に採用できる `.cursorignore` の実用的な構成例を示す。

==========================================
1. ビルド成果物・コンパイル済みファイル
(ソースコードの「結果」であり、AIが参照する必要はない)
==========================================
dist/
build/
out/
.next/
.tsbuildinfo

==========================================
2. 依存関係・パッケージマネージャーのキャッシュ
(膨大なサードパーティコードによるベクトル空間の汚染を防ぐ)
==========================================
node_modules/
vendor/
.pnp/
.pnp.js

==========================================
3. 自動生成された型定義・クライアントSDK
(OpenAPIやGraphQLから自動生成された数万行のコードはノイズになる)
==========================================
src/generated/
src/types/api-schema.ts
.gen.ts
.swagger.json

==========================================
4. テストカバレッジ・ログ・一時ファイル
==========================================
coverage/
logs/
.log
tmp/
.temp/

==========================================
5. 環境変数・機密情報
(セキュリティリスクの排除：万が一プロンプトに漏れ出すのを防ぐ)
==========================================
.env
.env.
!.env.example

==========================================
6. IDE・エディタ固有の設定
==========================================
.vscode/
.idea/
.cursor/

チップス: `.cursorignore` 記述のポイント

自動生成コードの扱い: OpenAPI等から生成されたコードを無視すると、APIの型情報がAIに伝わらないジレンマが生じる場合がある。その場合は、自動生成ファイル全体ではなく、数千行に及ぶモックデータや巨大な定数定義のファイルだけをピンポイントで除外すると効果的だ。
設定後の再インデックス: `.cursorignore` を変更した後は、必ずコマンドパレット（`Cmd/Ctrl + Shift + P`）から `Cursor: Regenerate Index` を実行し、ベクトルDBをクリーンな状態に同期させること。

—

3. 開発スピードを極限まで高める隠れたキーボードショートカット

マウス操作を極力排除し、思考の速度のままコードを操作するためのキーバインドとショートカットを習得せよ。

—

4. チーム開発で知見を同期させる：設定ファイル共有化ルール

個人がローカルで好みの設定を使っているうちは、チーム全体の生産性は上がらない。Cursorの強みをチーム全員で均質に享受するためには、プロジェクトのルートに `.cursor/` ディレクトリを切って設定をコードとして管理（Infrastructure as Codeの思想）することが不可欠だ。

以下に、チーム全体で共通化すべきプロジェクト設定ファイルのベストプラクティスを提示する。

`.cursor/rules/default.mdc` (プロジェクト固有のAIルール定義)

Cursorでは、`.cursor/rules/` 配下にマークダウンファイルを配置することで、常にAIに読み込ませる「振る舞い・コーディング規約」を定義できる。

Project Architecture & Coding Rules

You are an expert Principal Engineer working on this high-performance TypeScript/React project.
Follow these rules strictly when generating or refactoring code:

1. Tech Stack & Versions

TypeScript (Strict mode enabled, no `any` types allowed).
React 18+ (Functional components with hooks, no class components).
State Management: Zustand for global state, React Query (TanStack Query) for server state.
Styling: Tailwind CSS.

2. Code Quality Standards

Always write explicit return types for exported functions and React components.
Handle all async errors gracefully using Result types or try/catch blocks with proper logging.
Avoid modifying legacy files in `src/legacy/` unless explicitly requested.

3. Testing Requirements

When creating a new component or utility function, always provide a corresponding unit test file using Vitest and Testing Library.

このファイルをリポジトリに含めておくだけで、新メンバーやジュニアエンジニアが参画した初日から、シニアエンジニアの知見が組み込まれたAIサポートを受けることができる。

—

5. 究極の環境構築：開発環境設定ファイル（JSON）

最後に、Cursor（VSCodeベース）の根幹を支える `settings.json` のベストプラクティスを公開する。AIとの協働をスムーズにするためのエディタ設定が網羅されている。

`.vscode/settings.json` (または Cursor の設定)

{
// ==========================================
// AI連携・フォーマット関連の最適化
// ==========================================

// 保存時に自動フォーマット（Prettier等）を走らせ、AIが生成したコードの乱れを即座に修正
“editor.formatOnSave”: true,
“editor.defaultFormatter”: “esbenp.prettier-vscode”,

// 補助的なインラインAI補完（Tabキーによる補完）の挙動調整
“cursor.cpp.enableAutoTrigger”: true,

// ==========================================
// ファイル検索・インデックスのパフォーマンス向上
// ==========================================

// 巨大なビルド成果物やログファイルを検索対象から除外（ファイルウォッチャーの負荷軽減）
“files.watcherExclude”: {
“/.git/objects/“: true,
“/.git/subtree-cache/“: true,
“/node_modules/“: true,
“/dist/“: true,
“/.next/“: true,
“/coverage/“: true
},

// 検索ペインから除外するパスの設定
“search.exclude”: {
“/node_modules”: true,
“/bower_components”: true,
“/.code-search”: true,
“/dist”: true,
“/.next”: true
},

// ==========================================
// TypeScript 開発の強靭化
// ==========================================

// ワークスペース内の確実なTypeScriptバージョンを使用（AIの型理解のズレを防ぐ）
“typescript.tsdk”: “node_modules/typescript/lib”,

// 未使用のインポートを保存時に自動整理
“editor.codeActionsOnSave”: {
“source.organizeImports”: “explicit”
}
}

—

テックリードとしてのまとめ

Cursorの「Codebase Indexing」は、単なる便利機能ではない。プロジェクトの構造を正しくメタデータ化し、AIという強力なエンジニアリソースをチームの文脈に完全に適応させるためのインフラストラクチャである。

1. `.cursorignore` でノイズを徹底的に排除し、ベクトル空間の精度を研ぎ澄ます。
2. `.cursor/rules/` を用いて、チーム全体のコーディング規約やアーキテクチャ方針をAIに学習させる。
3. キーボードショートカットを身体に叩き込み、思考を途切れさせずにコードを生成・修正する。

これらの環境構築を徹底することで、チームの開発スピードは文字通り「桁違い」の領域へとシフトする。今すぐあなたのプロジェクトの `.cursorignore` を見直し、真のAI駆動開発をチームにインストールしてほしい。