cursor-context-management

Cursor のコンテキスト管理

概要

Cursor が参照する内容を管理し、信頼できる回答や編集に必要な、関連性がありポリシーで許可された最小限のコンテキストだけを各会話に含めます。

前提条件

• タスクの範囲、承認済みのプライバシー設定、データ分類、および適切に機能する除外設定。
• 認証情報、顧客データ、無関係なリポジトリを含まず、共有可能な関連ファイル／インターフェース。

手順

1. 必要なファイル、シンボル、制約を正確に指定して始めます。無差別な @Codebase の使用は避けてください。
2. 送信する前にコンテキストピル／添付ファイルを確認し、古い情報や機密情報を削除します。
3. トピックまたはリポジトリの境界が変わったら、新しいチャットを始めます。
4. 生成された出力をソースやテストと照合して検証します。コンテキストの関連性は検証の代わりにはなりません。

出力

• 最小限の、文書化されたコンテキストセットと、個別にレビューできる範囲を限定した結果。

エラー処理

状況	安全な対応
コンテキストが古い、または矛盾している	最新のファイルを使い、トピックの範囲を限定した新しいチャットを始めます。
機密性の高いパスが表示される	作業を停止して該当項目を削除し、除外設定を修正して、情報漏えい時の手順に従います。
モデルが重要な事実を見落とす	コードベース全体を追加するのではなく、根拠となるファイル／インターフェースを添付します。

例

1つのサービスのバグであれば、そのハンドラー、インターフェース、関連するテストを添付し、発生している問題を説明して、最小限の修正を依頼します。会話が別のサービスの話題に移った場合は、コンテキストを追加し続けるのではなく、新しいチャットを開きます。

Cursor AI がコンテキストを活用して、正確で関連性の高い応答を生成できるよう最適化します。モデルが応答を生成するときに参照するものはすべてコンテキストです。適切な管理は、出力の品質を高めるうえで最も効果の大きい方法です。

コンテキストのソース

Cursor は各 AI リクエストの前に、複数のソースからコンテキストを集めます。

┌─ Always Included ─────────────────────────────────────┐
│  System prompt (Cursor internal)                      │
│  Active .cursor/rules/*.mdc with alwaysApply: true    │
│  Current file (for Tab, Inline Edit)                  │
└───────────────────────────────────────────────────────┘
┌─ Conditionally Included ──────────────────────────────┐
│  Selected code (highlighted before Cmd+L/Cmd+K)       │
│  @-mention targets (@Files, @Folders, @Code)          │
│  Glob-matched rules (.mdc with matching globs)        │
│  Conversation history (prior turns in chat)           │
│  Open editor tabs (lightweight reference)             │
└───────────────────────────────────────────────────────┘
┌─ On-Demand (explicit @-mention) ──────────────────────┐
│  @Codebase  → semantic search across indexed files    │
│  @Docs      → crawled external documentation          │
│  @Web       → live web search results                 │
│  @Git       → uncommitted diff or branch diff         │
│  @Lint Errors → current file lint diagnostics         │
└───────────────────────────────────────────────────────┘

コンテキストピル

アクティブなコンテキストは、チャット／コンポーザーパネルの上部にピルとして表示されます。

[main.ts] [src/utils/] [@Web: next.js 15] [Rule: typescript-standards]

• ピルをクリックすると展開され、内容を確認できます
• ピルの x をクリックすると、コンテキストから削除できます
• ピルを追加しすぎるとコンテキストウィンドウがいっぱいになり、応答の品質が低下します

タスク別の @-メンション戦略

コードの理解

@src/auth/middleware.ts @src/types/user.ts
Explain how the JWT validation works and what happens when a token expires.

特定のファイルには @Files を使います。ディレクトリ全体が必要な場合を除き、コンテキストを大量に消費する @Folders は避けてください。

バグの調査

@src/hooks/useCart.ts @Lint Errors @Recent Changes
The cart total is NaN after the latest changes. What broke?

@Recent Changes と @Lint Errors を組み合わせると、モデルに調査に役立つコンテキストを提供できます。

アーキテクチャに関する質問

@Codebase where are database queries made?

@Codebase は、インデックス化されたコードベース全体を対象にセマンティック検索を実行します。関連するファイルが分からない場合の探索に適していますが、対象を絞った @Files のメンションよりも多くのコンテキストを消費します。

外部の知識を利用する

@Docs Prisma @Web prisma client extensions 2025
How do I add soft-delete as a Prisma Client extension?

@Docs は、事前にインデックス化されたドキュメントを利用します。@Web はリアルタイム検索を行います。サードパーティ製ツールについて包括的な回答を得るには、両方を組み合わせます。

コンテキスト予算の管理

モデルごとにコンテキストの上限があります。上限を超えると、モデルは情報を通知なく切り捨てることがあります。

モデル	コンテキストウィンドウ	実用上の上限
GPT-4o	128K tokens	約80Kを使用可能
Claude Sonnet	200K tokens	約150Kを使用可能
Claude Opus	200K tokens	約150Kを使用可能
cursor-small	8K tokens	約5Kを使用可能

コンテキストあふれの兆候

• 会話の前半での指示をモデルが忘れる
• 応答が一般的になったり、繰り返しが増えたりする
• 3ターン前の自分の発言と矛盾する
• 提案されたコードが、提供したファイルのコンテキストを無視している

軽減策

1. こまめに新しい会話を始めます。 1つの会話につき1つのトピックにします。
2. @Folders ではなく、具体的な @Files を使います。 @src/api/ より @src/api/users.ts のほうが適切です。
3. 不要になったコンテキストピルを削除します。 x をクリックして古いファイルを削除します。
4. 範囲の狭い質問では @Codebase を避けます。 多くのコードチャンクが取り込まれます。場所が分かっている場合は @Files を使います。
5. 大きなタスクを段階に分けます。 型定義、実装、テストの順に、別々のターンまたはチャットで依頼します。

自動コンテキストと手動コンテキスト

Cursor は一部のケースでコンテキストを自動的に含めます。

機能	自動コンテキスト
タブ補完	現在のファイル + 開いているタブ + 最近の編集
インライン編集（Cmd+K）	選択したコード + 周辺のファイル
チャット（Cmd+L）	会話履歴 + 明示的に追加したコンテキスト
Composer（Cmd+I）	参照されたファイル + コードベース検索

チャットと Composer では、@-メンションを使ってコンテキストを制御します。タブ補完とインライン編集では、コンテキストが自動的に管理されます。

コンテキスト制御のための .cursorignore

ファイルが AI のコンテキストに含まれないようにします。

# .cursorignore (project root)

# Secrets and credentials
.env
.env.*
**/secrets/
**/credentials/

# Large generated files
dist/
build/
node_modules/
*.min.js
*.bundle.js

# Data files that consume context budget
*.csv
*.sql
*.sqlite
fixtures/

注： .cursorignore はベストエフォートです。ファイルがインデックス作成や AI 機能に表示されないようにしますが、秘密情報を保護するためのセキュリティ境界ではありません。実際の秘密情報の管理には、.gitignore と環境変数を使用してください。

上級編：コンテキストとしてのスコープ付きルール

プロジェクトルールは、関連するファイルを開くとコンテキストを自動的に挿入します。

# .cursor/rules/database-patterns.mdc
---
description: "Database query patterns and conventions"
globs: "src/db/**/*.ts,src/repositories/**/*.ts"
alwaysApply: false
---
# Database Conventions
- Use parameterized queries exclusively
- All queries go through repository pattern
- Wrap multi-table operations in transactions
- Use connection pooling (pool size: 10)

このルールはデータベースファイルの編集中に自動的に読み込まれるため、毎回手動でコンテキストを追加しなくても、AI に適切な規約を適用できます。

エンタープライズでの考慮事項

• データの機密性：PII、認証情報、規制対象データを含むファイルを除外するには、.cursorignore を使用します
• プライバシーモード：コンテキストとして送信されるコードが、モデルプロバイダーに一切保持されないようにします
• 会話の整理：コンテキストの混在を避けるため、タスクごとに新しいチャットを開始するようチームに徹底します
• コストへの配慮：コンテキストが大きいほどトークン数が増え、BYOK の使用時に API コストが高くなります

リソース

• @ シンボルの概要
• コードベースのインデックス作成
• 無視ファイル