目次を表示する

Cursor：AI統合エディタプラットフォーム

コンテキスト管理 ── AIに「見せるもの」を設計する

コンテキスト管理 ── AIに「見せるもの」を設計する

AIコードエディタを使いこなすうえで、最も見落とされがちなのが「コンテキスト管理」だ。Cursorに指示を出すとき、多くの開発者は「AIが賢いのだから、プロジェクト全体を理解しているはずだ」と期待する。しかし実際には、AIが「何を知っているか」はユーザーが意識的に設計しなければならない。このチャプターでは、Cursorのコンテキストの仕組みを深く理解し、精度の高い応答を引き出すための実践的な手法を解説する。

Section 1: Cursorのコンテキストの仕組み

Cursorを起動すると、バックグラウンドでプロジェクトのインデックス化が始まる。具体的には、ファイル名・ディレクトリ構造・シンボル（関数名・クラス名・変数名）がベクトルデータベースに格納される。これにより、@codebase で「UserServiceに関連するコードを探して」と聞いたとき、Cursorは意味的に近いファイルを高速に検索できる。

ただし、ここで重大な誤解が生じやすい。「インデックスされている ≠ AIが全部読んでいる」という事実だ。

LLMにはコンテキストウィンドウという物理的な制限がある。たとえば10万行のコードベースがあっても、AIが一度の会話で処理できる情報量は限られている。インデックスはあくまでも「どこに何があるか」を把握するための地図にすぎない。実際にAIが読むのは、その地図を使って取り出した「関連度の高い断片」だけだ。

Composerでリクエストを投げたとき、コンテキストに入るものを整理すると以下のようになる。

flowchart TD
    subgraph UserInput["ユーザー入力"]
        Q["プロンプト（自然言語）"]
        AT["@参照（明示的指定）"]
    end

    subgraph AutoContext["Cursorが自動収集するコンテキスト"]
        OT["開いているタブ（最近編集したファイル）"]
        CS["カーソル位置周辺のコード"]
        RT["リポジトリツリー（構造情報）"]
    end

    subgraph SemanticSearch["セマンティック検索（インデックス）"]
        EMB["埋め込みベクトル検索"]
        SYM["シンボルグラフ（import/export関係）"]
    end

    subgraph ContextWindow["コンテキストウィンドウ（LLMへの入力）"]
        MERGED["統合されたコンテキスト\n（優先度順にトリミング）"]
    end

    Q --> MERGED
    AT --> MERGED
    OT --> MERGED
    CS --> MERGED
    RT --> SemanticSearch
    SemanticSearch --> EMB
    SemanticSearch --> SYM
    EMB --> MERGED
    SYM --> MERGED

この構造を理解することで、「なぜAIがあのファイルを見ていないのか」という問題の根本が分かるようになる。AIの応答品質は、コンテキストの設計品質に直結している。

Section 2: @参照の使い方

Cursorが提供する @ 参照は、コンテキストを明示的にコントロールするための最も強力なツールだ。単に「雰囲気でAIに任せる」のではなく、「何を見せるか」を開発者が主体的に選択できる。

@filename ── 特定ファイルを参照する

最も基本的な参照方法。特定のファイルを直接コンテキストに渡す。

@src/lib/auth.ts このファイルのJWT検証ロジックに、リフレッシュトークンの有効期限チェックを追加してください

使いどころ：実装の詳細が分かっているとき、特定のバグ修正をするとき。AIが見当違いのファイルを参照するのを防ぎ、回答の精度が格段に上がる。

@folder ── フォルダ全体を参照する

ディレクトリ単位でコンテキストに含める。

@src/components/forms/ このフォルダ内のフォームコンポーネントの命名規則を分析して、統一したバリデーション処理を設計してください

使いどころ：リファクタリング計画を立てるとき、特定のドメイン（フォーム、API層など）を一括して改善するとき。ただしフォルダが大きすぎるとコンテキストウィンドウを圧迫するため注意が必要だ。

@codebase ── コードベース全体のセマンティック検索

プロジェクト全体のインデックスに対してセマンティック検索を行い、関連度の高いスニペットを自動で収集する。

@codebase Stripeの決済処理に関連するすべてのコードを見つけて、エラーハンドリングが統一されているか確認してください

使いどころ：どのファイルに実装があるか分からないとき、横断的な調査（「認証関連のコードを全部見たい」）をするとき。ただし、意図しないファイルが混入することもあるため、結果を目視で確認する習慣をつけたい。

@docs ── カスタムドキュメントの参照

URLを登録しておいたカスタムドキュメントを参照する。詳細は Section 4 で後述するが、使い方のイメージは次の通り。

@convex-docs Convexのschema定義でoptionalフィールドを扱う正しい方法を教えてください

使いどころ：社内APIドキュメント、プライベートライブラリ、または公式ドキュメントの特定バージョン（Cursorに最初から入っていない新しいライブラリ）を参照するとき。

@web ── リアルタイムWeb検索

会話中にリアルタイムでWeb検索を行い、最新情報を取得する。

@web Next.js 15のServer Actionsの最新のベストプラクティスを調べてください

使いどころ：Cursorのトレーニングデータに含まれていない最新のAPIや、ライブラリのバージョンアップで破壊的変更があったとき。「なぜAIが古い書き方を提案するのか」と感じたら @web を使う習慣をつけると良い。

@git ── コミット履歴・差分を参照する

Gitのコミット履歴やdiffをコンテキストに含める。

@git 直近5コミットで変更されたファイルを確認して、今日の作業内容をまとめたコミットメッセージの草案を書いてください

使いどころ：コードレビューの準備、変更履歴のサマリー作成、「あのリファクタリングの前はどういうコードだったか」を確認するとき。

Section 3: .cursorignore ── 不要なノイズを排除する

コンテキストの質を上げるには「何を入れるか」だけでなく「何を除くか」も重要だ。.cursorignore は .gitignore と同じ文法を使い、Cursorのインデックスから除外するファイルやフォルダを指定できる。

node_modules はデフォルトで除外されているが、モダンなWebプロジェクトには他にも大量のノイズになりうるファイルが存在する。

以下は実際のプロジェクトで使える .cursorignore の例だ。

# ビルド成果物・生成ファイル
.next/
dist/
out/
build/
.turbo/
.cache/

# パッケージマネージャー
node_modules/
.pnp/
.pnp.js

# テストカバレッジレポート（生成ファイル）
coverage/
.nyc_output/

# 大容量データファイル（AIが読んでも意味がないもの）
*.csv
*.json.gz
*.parquet
fixtures/large_dataset/

# シークレット・環境変数（セキュリティ上必須）
.env
.env.local
.env.*.local
*.pem
*.key

# ログファイル
*.log
logs/

# IDE・OSメタデータ
.DS_Store
.idea/
*.swp

# Prismaの生成クライアント（スキーマだけあれば十分）
node_modules/.prisma/
prisma/generated/

# Storybookの静的出力
storybook-static/

# ドキュメントの自動生成HTML（ソースのMarkdownで十分）
docs/api-reference/generated/

なぜ除外するとインデックス精度が上がるのか。LLMのコンテキストは有限であり、ノイズが多ければ多いほど「信号対雑音比」が下がる。.next/server/pages/_app.js のような自動生成ファイルが検索結果に混入すると、AIは手書きのコードと生成コードを区別できず、誤った提案をすることがある。除外リストを適切に設定することは、チームの生産性に直結する投資だ。

Section 4: カスタムDocsの活用

Cursorの標準インデックスにはReact、TypeScript、Next.jsなど主要ライブラリのドキュメントが含まれているが、社内専用のAPIやニッチなライブラリ、あるいはドキュメントが日々更新される新興フレームワークには対応していない。これを解決するのがカスタムDocs機能だ。

設定方法は簡単だ。Cursor Settings → Features → Docs → Add new doc からURLを入力すると、Cursorはそのサイトのすべてのサブページをクロールしてインデックス化する。登録されたドキュメントは @docs から参照できるようになる。

活用シナリオ：ConvexとSupabaseのドキュメントを登録する

バックエンドとして Convex を使いながら、認証に Supabase を組み合わせているプロジェクトを例に考えよう。どちらも進化が速く、Cursorの標準インデックスが追いついていないことがある。

# カスタムDocs登録URL（例）
https://docs.convex.dev/
https://supabase.com/docs/
https://supabase.com/docs/reference/javascript/

登録後、以下のようなプロンプトが使えるようになる。

@convex-docs @supabase-docs
SupabaseでGoogle OAuthログインしたユーザーのIDを、ConvexのユーザーテーブルにUpsertする処理を実装してください。
ConvexのschemaとSupabaseのRLSポリシーの両方を考慮した実装にしてください。

カスタムDocsはベクトル検索によって動作するため、ドキュメント全文をコンテキストに詰め込むのではなく、質問に関連する箇所だけが自動で抽出される。社内のAPIドキュメントが Confluence や Notion にある場合も、そのURLを登録しておくことで、AIが社内仕様を理解した回答を返せるようになる。

Section 5: 長時間セッションの罠

Cursorのエージェントモードは非常に便利だが、セッションが長くなるほど注意が必要な落とし穴が存在する。

エージェントセッションが2時間を超えると、AIの認識するコードの状態と実際のリポジトリが乖離してくることがある。症状としては、「さっき修正したバグがまだあるかのように振る舞う」「すでにリファクタリングしたはずのコードを元の書き方で提案する」といったケースだ。これはコンテキストウィンドウの長さと、Cursorのインデックスの更新タイミングに起因する問題だ。

長時間セッションを管理するための実践的なチェックリストを示す。

## 長時間エージェントセッション管理チェックリスト

### セッション開始時（必ず実施）
- [ ] `Cursor Settings → Indexing` でインデックスのステータスを確認
- [ ] 作業対象のブランチが最新であることをgit pullで確認
- [ ] 作業スコープを明確に定義し、プロンプトの冒頭に記載

### 90分ごとのチェックポイント
- [ ] 変更内容を一度コミット（checkpoint: セッション中間）
- [ ] Cursorを再起動、またはComposerの「New Conversation」を開始
- [ ] 新セッションの冒頭で「前回までの作業: [概要]」をコンテキストとして渡す
- [ ] @git で直近のコミット内容を確認させ、AIの認識を同期させる

### セッション終了時
- [ ] 変更内容をすべてコミット
- [ ] 動作確認（テスト実行 / ローカルサーバー確認）
- [ ] 次回セッションのために「残タスク一覧」をコメントまたはメモに残す

### 問題が発生したとき
- [ ] まず新しいConversationを開始する（コンテキストリセット）
- [ ] 問題のあるファイルを @filename で明示的に参照させる
- [ ] 「最新のコードを読んでから回答してください」と明示的に指示する

長時間セッションの問題は、AIの能力の問題ではなく、コンテキスト管理の問題だ。チェックポイントを設けて定期的にリセットする習慣を持つことで、2時間以上の複雑な実装作業でも安定したパフォーマンスを維持できる。

コンテキスト管理は地味に見えて、実はAI駆動開発の生産性を大きく左右するスキルだ。@ 参照の使い分け、.cursorignore の整備、カスタムDocsの登録、そして定期的なセッションリセット──これらを習慣化することで、Cursorは単なる「賢いオートコンプリート」から「設計を共に考えるパートナー」へと変わる。