Cursorが思うように動かないときの確認点

Cursorで、fileを読んでくれない、Agentが同じ修正を繰り返す、期待と違うfileを編集する、promptを送れない、indexingが終わらない、日本語や文字コードが崩れるとき、いきなり再installするより原因を分けた方が早く直せます。

2026年時点の公式Docsでは、主にcontext、ignore設定、indexing、network、extensionの5系統から切り分ける方法が案内されています。

先に確認する順番

おすすめは、

1. 対象file / folderを明示

2. .cursorignore / .gitignore

3. codebase reindex

4. chat contextを整理

5. network diagnostics

6. extension conflict

7. encoding / file format

8. Cursor再起動・update

です。

1. 読んでほしいfileを@で明示する

Agentが意図したfileを拾わない場合、まず@fileや@folderでtarget contextを直接渡します。

Cursor公式では、@Files / Folders、@Terminals、@Chats、@Git diff、@Browserなどをcontextとしてattachできます。

Agentが自動searchできる場合でも、修正対象が分かっているなら明示した方がブレにくくなります。

2. .cursorignoreと.gitignoreを確認

fileを読んでくれない場合、ignore ruleが原因のことがあります。

Cursorは.cursorignore、.gitignore、default ignore listを使ってAI contextからfileを除外します。

画像、動画、lock file、.env、binary等はdefaultでignoreされるものがあります。

「fileはprojectに存在するのに@で出てこない」場合はignore ruleを確認します。

3. Reindexする

official Agent troubleshootingでは、file discoveryがおかしい場合にprojectのReindexを案内しています。

Command Paletteから「Reindex」を実行し、codebase indexを作り直します。

large monorepoではirrelevant directoryをignoreし、index対象を減らす方がsearch精度とperformanceを改善しやすくなります。

4. chatが長すぎるなら新しくする

Agentが以前のinstructionを引きずる場合、contextが混ざっていることがあります。

Cursor公式も、feature完了やtask切り替え時にはnew chatを使うことを推奨しています。

長いchatへ何十個も修正指示を積むより、目的、current state、target files、constraintsを短くまとめてnew chatへ移した方が安定する場合があります。

5. 複雑な変更はPlanから始める

大量fileを触るtaskで期待と違う変更をする場合、いきなりAgentへ実装させずPlan modeから始めます。

「まず原因を調査。変更はしない」

「該当fileと修正方針だけ出して」

と分けると、誤編集を減らせます。

official troubleshootingでもmany-file taskではPlan modeを使うことを推奨しています。

6. promptを送れないならNetwork Diagnostics

AI機能そのものが動かない場合、Cursor Settings → Network → Run Diagnosticsを実行します。

CursorはHTTP/2 streamingを使うため、corporate proxyやVPNで通信が止まることがあります。

その場合、HTTP Compatibility ModeをHTTP/1.1へ変更し、Cursorを完全終了して再起動する方法が案内されています。

7. VPN・proxy・firewallを確認

network issueでは、VPN、corporate proxy、DNS、SSL inspection、firewallを切り分けます。

Cursorが必要なdomainをfirewallがblockしていないか確認します。

Remote SSHの場合も、AI request自体はlocal machineからCursor serverへ通信します。

remote serverのnetworkだけ見ても原因が分からない場合があります。

8. extension conflictを確認

AI completionやshortcutを扱うextensionがCursorと競合することがあります。

official Docsでは、

1. 全extensionをdisable

2. 問題が消えるか確認

3. 一つずつenable

して原因を特定する方法を案内しています。

他のAI coding assistant extensionが特に競合しやすいとされています。

9. 日本語が崩れる場合

日本語が文字化けする場合は、Cursor Agentよりfile encoding側を確認します。

見るポイントは、UTF-8か、Shift_JIS / CP932か、BOM有無、terminal locale、shell commandがencodingを変えていないか、formatterがfileを再保存していないかです。

AIが文章を「変な日本語にする」場合と、byte encodingによる文字化けは別です。

前者はprompt / context、後者はfile / terminal encodingを確認します。

まずは使ってみる

記事の文脈に合うToolへ進めます。報酬の有無で見た目は変えていません。

• 

  Cursor

  公式サイトを見るTool詳細を見る比較を見る

10. 「動かない」と「期待と違う」を分ける

本当に動かない

network、extension host、indexing、authentication、provider outageを確認。

動くが期待と違う

prompt、context、rules、target files、chat lengthを確認。

fileが見えない

ignore、index、@mention。

editはできるがbugる

変更を小分け、Plan、test、checkpoint。

この分類だけでもtroubleshootingが速くなります。

11. 修正前にCheckpointを使う

Agent changeが悪化した場合はRestore Checkpointで以前の状態へ戻せます。

Git commitと併用すると、AI修正 → diff確認 → test → commitの単位を小さくできます。

大きな修正を一気に受け入れない方が安全です。

症状別に最初の検査を選ぶ

「Cursorが動かない」は、ファイル認識、回答品質、通信、編集結果、表示のどこで止まったかに分けます。まず同じproject・同じモデルで一度だけ再現し、時刻、Cursor version、対象file、表示されたerrorを控えます。これがないまま再installすると、設定やextensionの原因を消してしまい比較できません。

表は横にスクロールできます

症状	最初に確認するもの	切り分けテスト	結果の読み方
fileを見つけない	.cursorignore / .gitignore、file path	@で対象fileを直接添付し、次にReindex	添付で直るなら自動検索/index側、添付候補にも出なければignore側を優先
指示と違うfileを編集	context、対象path、chatの古さ	新しいchatで対象fileと期待結果を一文ずつ明記	新しいchatで改善すれば過去contextの混在が候補
同じ修正を繰り返す	変更範囲、既存rules、失敗したtest	変更前後のdiffと具体的な失敗出力を渡し、原因だけ先に質問	再現条件が不明なら編集を止め、最小test caseを作る
promptが送れない	Network Diagnostics、VPN / proxy / firewall	診断を実行し、proxy経由か別networkかを比較	HTTP/2 streamがproxyで止まる場合は公式手順のHTTP/1.1互換を試す
completionだけ反応しない	AI completion系extension、shortcut競合	全extensionを一時的にdisableして再現するか比較	直る場合は一つずつ戻して競合を特定
日本語だけ崩れる	file encoding、BOM、terminal locale、保存するformatter	元fileのencodingを確認し、AIを使わず同じ表示が再現するか見る	AIの言い換えと文字コード破損を別問題として扱う

変更を安全に戻すテスト

Agentが変更した後は、まずdiffで対象fileと削除行を確認し、次に最小の関連testを実行します。testが失敗した場合は、失敗ログを短く再現できる状態でAgentへ渡し、追加修正の範囲を一つに絞ります。複数fileの変更が崩れたときは、CheckpointまたはGitで変更前へ戻せることを確認してから続けます。大きな変更の途中でUndoを重ねるより、変更単位ごとにcheckpointを置く方が原因を追いやすくなります。

ここまでで直らない場合

• 対象fileだけ再indexしても見つからない場合：ignore rule、workspace root、symlink、file typeを順に確認する。

• すべてのAI機能が同時に失敗する場合：local file設定よりnetwork diagnostics、認証、サービスstatusを優先する。

• clean extension状態で直る場合：extensionを一つずつ戻し、競合するextension名と症状を記録する。

• 特定modelだけ失敗する場合：別modelで一度比較し、model固有の障害か、project context全体の問題かを分ける。これは原因の切り分けであり、別modelを恒久的な解決策と決めるテストではない。

• 文字化けが保存後も残る場合：元の文字コードとGit差分を確認し、復元可能なcopyを作ってから変換する。元fileを上書きする前にbackupを残す。

Cursor公式Troubleshootingは、ファイル認識ではignore確認・Reindex・@添付、複数file作業ではPlan、network問題では診断、extension競合では全停止後の個別再有効化を案内しています。設定名はversionで変わることがあるため、見つからない場合は現在の公式Helpページからたどってください。

AIものさしの判断

Cursorが思うように動かないときは、AI modelを変える前にcontext / ignore / indexing / network / extensionを切り分けるのが有効です。

特に、

「fileを読まない」→ ignore / reindex / @file

「期待と違う」→ new chat / Plan / specific prompt

「通信しない」→ Network Diagnostics / HTTP compatibility

「突然変」→ extension conflict

の順で確認すると原因を絞りやすくなります。