Cursor での Context Sync のトラブルシューティングと最適化

Context Sync は、Cursor がコードベースをインデックスし、AI アシスタントに関連コンテキストを提供するメカニズムです。正常に動作している場合は、正確なコード提案、正確なファイル参照、インテリジェントなプロジェクト対応の応答が可能になります。故障すると、古い提案、欠落したファイル参照、または恐ろしい「Context Sync is not running」エラーが発生する可能性があります。本ガイドは、診断、修復、最適化を案内します。

Context Sync の理解

Context Sync はバックグラウンドで動作し、プロジェクトファイルを継続的にスキャンして検索可能なインデックスを構築します。このインデックスにより、AI はプロジェクト構造を理解し、関連ファイルを見つけ、コンテキストに正確な応答を提供できます。

インデックスの仕組み

インデックスプロセスは以下の段階に従います：

1. 発見: Cursor はワークスペース内のすべてのファイルをスキャンし、.gitignore とカスタム除外ルールを尊重
2. 解析: 各ファイルを解析してシンボル、インポート、構造メタデータを抽出
3. 埋め込み: コードチャンクをベクトル埋め込みに変換してセマンティック検索を実行
4. 保存: インデックスはローカルに保存され、オプションでクラウドに同期
5. 更新: ファイル変更が増分インデックス更新をトリガー

ヒント

大規模なコードベースの初回インデックスには数分かかる場合があります。この間、CPU 使用率が高くなり、AI 応答が遅くなる場合があります。これは正常であり、初回インデックスが完了すると解決します。

コンテキストウィンドウ管理

コンテキストウィンドウは、AI が一度に処理できる情報量を決定します。Cursor はこれを自動的に管理しますが、制限を理解することでワークフローを最適化できます：

プラン	コンテキストウィンドウ	最大インデックスファイル数
Free	25,000 トークン	500 ファイル
Pro	200,000 トークン	5,000 ファイル
Business	200,000 トークン	25,000 ファイル
Enterprise	カスタム	カスタム

Context Sync の問題の診断

同期ステータスの確認

トラブルシューティングの最初のステップは、現在の Context Sync ステータスを確認することです。Cursor はこれを行うためのいくつかの方法を提供しています：

方法 1：ステータスバー

Cursor ウィンドウの右下隅を見てください。回転アイコンはアクティブな同期を示し、チェックマークは同期が最新であることを意味します。エラーアイコンが表示された場合は、ホバーして詳細を確認してください。

方法 2：コマンドパレット

# コマンドパレットを開く（Ctrl+Shift+P / Cmd+Shift+P）
# 入力：Cursor: Show Context Sync Status

これにより以下を表示する詳細パネルが開きます：

• 現在の同期状態（running、paused、error）
• インデックスされたファイル数
• 最終同期タイムスタンプ
• エラーメッセージ
• ディスク上のインデックスサイズ

方法 3：出力パネル

# View > Output
# ドロップダウンから「Cursor Indexing」を選択

出力パネルには、ファイルごとの進行状況やエラーメッセージを含むリアルタイムインデックスログが表示されます。

警告

Context Sync ステータスが「not running」と表示され、表示可能なエラーがない場合、サイレント障害を示している可能性があります。UI に表示されていない可能性のあるエラーメッセージについて出力パネルを確認してください。「ERROR」または「FATAL」を含む行を探してください。

一般的なエラーメッセージ

以下は最も頻繁に遭遇する Context Sync エラーとその意味です：

「Context Sync is not running」

これは複数の原因を持つ可能性のある一般的なエラーです。同期プロセスが停止し、再起動する必要があります。以下の修復セクションでステップバイステップの手順を参照してください。

「Index corruption detected」

ローカルインデックスファイルが破損しています。通常、予期しないシャットダウンやディスクエラーが原因です。解決策はインデックスを削除し、ゼロから再構築することです。

「File watcher limit reached」

オペレーティングシステムのファイルウォッチャー制限を超えました。これは大規模なワークスペースを持つ Linux システムで一般的です。解決策はシステムの inotify 制限を増やすことです。

「Embedding service unavailable」

クラウド埋め込みサービスが一時的に利用できません。これは通常一時的であり、数分以内に自動的に解決します。

「Rate limit exceeded for indexing」

インデックスレート制限に達しました。これは短時間に多くのファイルが変更された場合に発生します。数分待つと同期が自動的に再開します。

Context Sync の修復

クイックフィックス：Context Sync の再起動

ほとんどの Context Sync 問題の最もシンプルな修正は、同期プロセスを再起動することです：

# コマンドパレット（Ctrl+Shift+P / Cmd+Shift+P）
# 入力：Cursor: Restart Context Sync

または、設定を使用して強制的に再起動できます：

// settings.json で
{
  "cursor.contextSync.forceRestart": true
}

この設定を保存すると、次回のウィンドウリロード時に同期プロセスが再起動します。

完全再インデックス

クイックリスタートで問題が解決しない場合、完全再インデックスが必要です。これは既存のインデックスを削除し、ゼロから再構築します。

# ステップ 1：インデックスキャッシュをクリア
# コマンドパレット：Cursor: Clear Index Cache

# ステップ 2：完全再インデックスをトリガー
# コマンドパレット：Cursor: Reindex Workspace

警告

大規模なコードベースでの完全再インデックスには 10〜30 分かかる場合があります。この間、AI 機能のコンテキストは限定されるか、利用できません。休憩中や AI アシスタントがすぐに必要ない時に再インデックスを計画してください。

手動インデックス修復

組み込みコマンドが機能しない場合、インデックスファイルを手動でクリアできます：

Windows の場合：

# まず Cursor を閉じる
# インデックスディレクトリをクリア
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\index"
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\codebase-index"

# キャッシュをクリア
Remove-Item -Recurse -Force "$env:APPDATA\Cursor\cache"

# Cursor を再起動してインデックスを再構築させる

macOS の場合：

# まず Cursor を閉じる
rm -rf ~/Library/Application\ Support/Cursor/index
rm -rf ~/Library/Application\ Support/Cursor/codebase-index
rm -rf ~/Library/Application\ Support/Cursor/cache

# Cursor を再起動

Linux の場合：

# まず Cursor を閉じる
rm -rf ~/.config/Cursor/index
rm -rf ~/.config/Cursor/codebase-index
rm -rf ~/.config/Cursor/cache

# Cursor を再起動

ヒント

インデックスを削除する前に、そのサイズを確認してください。インデックスディレクトリが異常に大きい場合（小規模プロジェクトで数 GB）、破損している可能性が高いです。再構築後の比較のために、削除前にサイズを記録してください。

インデックス設定

インデックススコープの最適化

どのファイルをインデックスするかを制御することが、Context Sync のパフォーマンスを向上させる最も効果的な方法です。デフォルトでは、Cursor は .gitignore を尊重しますが、カスタム除外を追加できます。

// settings.json で
{
  "cursor.contextSync.exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.next/**",
    "**/coverage/**",
    "**/*.min.js",
    "**/*.map",
    "**/vendor/**",
    "**/.cache/**",
    "**/*.lock",
    "**/package-lock.json",
    "**/yarn.lock",
    "**/*.png",
    "**/*.jpg",
    "**/*.gif",
    "**/*.svg"
  ],
  "cursor.contextSync.include": [
    "**/*.ts",
    "**/*.tsx",
    "**/*.js",
    "**/*.jsx",
    "**/*.py",
    "**/*.go",
    "**/*.rs",
    "**/README.md",
    "**/*.json"
  ]
}

警告

インデックスにバイナリファイル（画像、コンパイル済みバイナリ、ロックファイル）を含めると、スペースが無駄になり、検索品質が低下します。バイナリファイルと生成されたファイルは常にインデックスから除外してください。AI はバイナリコンテンツを意味のある方法で処理できず、これらのファイルはインデックスにノイズを追加します。

インデックス制限の設定

非常に大規模なコードベースの場合、インデックスされる最大ファイル数と最大ファイルサイズを制限できます：

{
  "cursor.contextSync.maxFiles": 10000,
  "cursor.contextSync.maxFileSize": 1048576,
  "cursor.contextSync.maxLinesPerFile": 5000
}

これらの制限により、インデックスが制御不能に増大するのを防ぎ、最も重要なファイルが優先されます。

ファイルウォッチャー設定

Linux システムでは、デフォルトの inotify ウォッチャー制限が大規模プロジェクトには低すぎることがよくあります。「file watcher limit reached」エラーを防ぐために増やしてください：

# 現在の制限を確認
cat /proc/sys/fs/inotify/max_user_watches

# 一時的に制限を増やす
sudo sysctl fs.inotify.max_user_watches=524288

# 恒久的に制限を増やす
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Windows では、同等の設定は MaxExtendedTdiHandleCount レジストリ値ですが、調整が必要になることはほとんどありません。

パフォーマンスチューニング

インデックスパフォーマンスの測定

最適化の前に、現在のインデックスパフォーマンスのベースライン測定を確立します：

# コマンドパレット：Cursor: Show Index Statistics

以下が表示されます：

Index Statistics
================
Total files:      3,247
Indexed files:    2,891 (89%)
Excluded files:   356
Index size:       142 MB
Last full index:  2026-09-14 14:30:22
Index duration:   4m 32s
Incremental updates today: 127
Average update time: 1.2s
Embedding cache hit rate: 87%

ヒント

高い埋め込みキャッシュヒット率（80% 以上）は、ほとんどのファイル変更が新しい埋め込みを必要としないことを意味します。ヒット率が低い場合、ファイルが変更されすぎているか、キャッシュが小さすぎる可能性があります。

大規模なモノレポの最適化

大規模なモノレポは Context Sync に独自の課題をもたらします。以下はそれらを扱うための戦略です：

戦略 1：プロジェクト固有のインデックス

モノレポ全体をインデックスするのではなく、現在作業中のプロジェクトのみをインデックスします：

{
  "cursor.contextSync.workspaceRoot": "packages/web-app",
  "cursor.contextSync.exclude": [
    "packages/**",
    "!packages/web-app/**"
  ]
}

これは、アクティブに作業しているものを除くすべてのパッケージを除外するよう Cursor に指示します。

戦略 2：シンボルベースのインデックス

完全なファイル内容ではなく、関数とクラス定義に焦点を当てたシンボルベースのインデックスを有効にします：

{
  "cursor.contextSync.indexingMode": "symbols",
  "cursor.contextSync.symbolTypes": [
    "function",
    "class",
    "interface",
    "type",
    "method",
    "variable"
  ]
}

戦略 3：優先度ベースのインデックス

異なるディレクトリに優先度レベルを割り当て、重要なコードが最初にインデックスされるようにします：

{
  "cursor.contextSync.priority": {
    "src/core/**": "high",
    "src/api/**": "high",
    "src/components/**": "medium",
    "src/utils/**": "medium",
    "src/tests/**": "low",
    "docs/**": "low"
  }
}

警告

優先度ベースのインデックスは低優先度ファイルを除外せず、最後にインデックスするだけです。初期インデックスフェーズでは、高優先度ファイルが最初に利用可能になります。これは完全なインデックスが完了する前に作業を開始する必要がある場合に役立ちます。

増分更新の最適化

増分更新はファイル変更時にトリガーされます。これらの更新の積極性を制御できます：

{
  "cursor.contextSync.incremental": {
    "enabled": true,
    "debounceMs": 2000,
    "batchSize": 10,
    "maxConcurrentUpdates": 3
  }
}

• debounceMs: 最後のファイル変更後、この時間だけ待ってからインデックスを更新。値が高いほど更新頻度が下がるが、より多くの変更をバッチ処理。
• batchSize: 各更新バッチで処理するファイル数。
• maxConcurrentUpdates: 並行更新ワーカーの最大数。

クラウド同期の最適化

クラウド同期を有効にしている場合、遅い接続でパフォーマンスに影響を与える可能性があります：

{
  "cursor.contextSync.cloud": {
    "enabled": true,
    "syncInterval": 300000,
    "compressBeforeSync": true,
    "maxSyncSize": 50000000
  }
}

ヒント

オフラインで作業することが多い場合、同期間隔を長くして不要な接続試行を避けてください。クラウド同期なしでもローカルインデックスは完全に機能しますが、デバイス間で共有されません。

高度なトラブルシューティング

古いインデックスの診断

AI が古いコードを参照したり、最近の変更を見逃している場合、インデックスが古い可能性があります：

# コマンドパレット：Cursor: Validate Index Integrity

このコマンドは以下をチェックします：

• インデックスに存在するがディスク上に存在しないファイル
• ディスク上に存在するがインデックスに存在しないファイル
• コンテンツハッシュがインデックス版と一致しないファイル
• 孤立したインデックスエントリ

# サンプル出力
Index Integrity Report
======================
Total discrepancies: 14
  Missing from index:      3 files
  Stale entries:          8 files
  Orphaned entries:       3 files

Recommended action: Run "Cursor: Reindex Workspace" to fix all discrepancies.

ファイルウォッチャーの問題のデバッグ

ファイル変更が Context Sync に拾われていない場合、ファイルウォッチャーが正しく動作していない可能性があります：

# コマンドパレット：Cursor: Test File Watcher

このコマンドは一時的なテストファイルを作成し、ウォッチャーがそれを検出するかを監視します：

File Watcher Test
=================
Creating test file: .cursor-test-watcher-12345.txt
Waiting for watcher response...
Watcher detected change: YES (after 0.3s)
File watcher is functioning correctly.

If you are experiencing sync issues, the problem may be with
specific directories. Check your exclude patterns.

埋め込みサービスの健全性確認

// settings.json で、埋め込み診断を有効化
{
  "cursor.contextSync.debugEmbeddings": true
}

これを有効にすると、出力パネルに詳細な埋め込み情報が表示されます：

[DEBUG] Embedding request: file=src/auth/login.ts, chunks=3, tokens=1842
[DEBUG] Embedding response: success, cache=hit, duration=12ms
[DEBUG] Embedding request: file=src/auth/register.ts, chunks=4, tokens=2103
[DEBUG] Embedding response: success, cache=miss, duration=894ms
[DEBUG] Embedding batch complete: 7 files, 24 chunks, 6 cache hits

警告

すべての埋め込みリクエストが cache=miss と長い時間を示す場合、埋め込みキャッシュが破損しているか小さすぎる可能性があります。設定でキャッシュサイズを増やすか、キャッシュを完全にクリアしてみてください。

ログ分析

持続的な問題については、診断ログを収集して分析します：

# コマンドパレット：Cursor: Generate Diagnostic Report

これにより以下を含む包括的なレポートが作成されます：

• Context Sync 設定
• インデックス統計
• 最近のエラーログ
• ファイルウォッチャーステータス
• 埋め込みサービスの健全性
• システム情報

レポートは以下に保存されます：

# Windows
%USERPROFILE%\Desktop\cursor-diagnostic-report.txt

# macOS / Linux
~/Desktop/cursor-diagnostic-report.txt

Context Sync のベストプラクティス

定期メンテナンス

• 毎週：「Validate Index Integrity」を実行して早期に不整合を発見
• 毎月：プロジェクト変更に基づいて除外パターンを見直して更新
• 大規模リファクタ後：構造的変更が取り込まれるよう完全再インデックスをトリガー
• 依存関係更新後：古い埋め込みを防ぐためにキャッシュをクリア

ワークスペースの整理

// ほとんどのプロジェクトに推奨される設定
{
  "cursor.contextSync.exclude": [
    "**/node_modules/**",
    "**/dist/**",
    "**/build/**",
    "**/.git/**",
    "**/*.log",
    "**/*.min.*",
    "**/coverage/**"
  ],
  "cursor.contextSync.maxFileSize": 1048576,
  "cursor.contextSync.incremental": {
    "enabled": true,
    "debounceMs": 2000
  }
}

ヒント

同じワークスペースで複数のプロジェクトを扱う場合は、マルチルートワークスペースファイルを使用してインデックスコンテキストを分離してください。各ルートフォルダーは独自のインデックスを取得し、関連性が向上しインデックスサイズが減少します。

大規模な生成ファイルの処理

型定義、コンパイル出力、自動生成 API クライアントなどの生成ファイルはインデックスを膨張させます。.cursorignore ファイルを使用してきめ細かく制御します：

# .cursorignore
# すべての生成型ファイルを除外
src/types/generated/**
# 大規模なスキーマファイルを除外
schema/**/*.json
# テストフィクスチャを除外
test/fixtures/**
# マイグレーションファイルを除外（AIコンテキストにはほとんど不要）
migrations/**

警告

マイグレーションファイルを除外する場合、データベース関連のタスクを扱うときは必ず含めてください。除外を一時的に削除するか、Cursor: Index File コマンドを使用して特定のファイルをオンデマンドでインデックスできます。

まとめ

Context Sync は Cursor のインテリジェントなコード支援の基盤です。インデックスの仕組みを理解し、一般的な問題を診断して修復する方法を知り、本ガイドの最適化戦略を適用することで、AI アシスタントが常にコードベースに関する正確で最新のコンテキストを持つことを確保できます。

重要なポイントは：除外パターンを最新に保ち、定期的に整合性チェックを実行し、調子が悪いと感じた場合は躊躇せず完全再インデックスを実行することです。健全なインデックスは、より速くより正確な AI 応答を意味し、それは直接的に開発者の生産性の向上につながります。