【Cursor】既存ファイルを参照しない時の確認|フォルダー・@指定・除外設定

Cursorにログイン処理の調査を頼んだのに、既存の関数を見つけず、新しい実装案ばかり返してくる。コードは目の前にあるのに「見つかりません」と言われる場合は、機能の説明を長くするより、どの作業フォルダーの、どのファイルを調べているかを確かめましょう。

以下では、例として「src/auth/login.ts」の「validateSession」を調べます。まず1ファイルの現在の内容を正しく説明できる状態にし、その後で呼び出し元へ調査を広げます。ファイルの場所が分かっている人向けに、パス指定、@参照、除外設定の順で確認する手順です。

Cursorが開いているのは、目的の作業フォルダーか

最初に、Cursorのエクスプローラーから対象ファイルを自分で開きます。その中に調べたい関数があるかを見てください。同じファイル名でも、旧コピーや別ブランチなら内容が違います。「web-app」と「web-app-old」がある場合は、どちらの「src/auth/login.ts」なのかが重要です。

見つからなければ、目的のプロジェクトを開いているかを確かめ、正しい作業フォルダーへ切り替えましょう。別の場所にあるファイルを想定して質問していても、Cursorはそのつもりをくみ取れません。検索結果を見る時も、名前だけでなくフォルダーを含むパスを押さえます。

複数のフォルダーを1つのワークスペースに登録している場合は、対象のルートも依頼に書きます。Cursorの検索の説明では、複数ルートの文脈もAgentで扱えるとされています。フォルダーを1つに減らすことを先に試すより、どのルートのファイルを調べるのかを明示するところから始めましょう。

機能名だけでなく、パスと関数名を渡す

「ログインの実装を調べて」では、画面、API、認証の共通処理のどれを探すべきかが広すぎます。場所が分かっている今回は、相対パスと関数名をそのまま渡しましょう。公式検索ガイドでも、関数名やエラー文字列など、具体的な一致条件を使う検索が説明されています。

このワークスペースのsrc/auth/login.tsにあるvalidateSessionを調べてください。
ファイルの変更はまだ依頼していません。
まず、この関数が実際にあるか確認し、読んだファイルの相対パスと該当箇所を示してください。
次に、どの条件でfalseを返すか説明してください。
対象が見つからない場合は、似た実装を新しく作らず、探した場所を報告してください。

パスと関数名は、自分のプロジェクトのものに置き換えてください。回答に示されたファイルを開き、「falseを返す」と説明した条件式が実際にあるかを照合します。「おそらく次のような実装です」と新しいコードが出ただけなら、既存ファイルの調査はまだできていません。

この段階では、実ファイルを読んだ説明なのか、一般的な実装例なのかを見極めることが目的です。コードの変更が始まってしまう場合は、コードを変更せず原因を調べる手順も参照し、説明だけを求める作業に合わせて進めましょう。

@でファイルを指定し、同じ質問を試す

パスを渡しても検索で見つからない場合は、入力欄の「@」から対象ファイルを選びます。Cursorの依頼方法の案内にある、ファイルやフォルダーを文脈として付ける操作です。名前の似た候補があれば、ここでもパスを見て選びましょう。

1. 対象ファイルを開いた状態で、新しい会話の入力欄に@とファイル名を入力します。
2. 候補から選び、入力欄に対象ファイルの参照が付いたかを確かめます。
3. 先ほどと同じ関数名と質問を送り、回答されたコードを実ファイルと比べましょう。

@指定で初めて正しく答えられたなら、少なくともそのファイルを参照して調査を続けられる状態です。元の依頼では関連ファイルを見つける条件が足りなかった可能性があるので、以後もファイル指定を残し、必要な呼び出し元を追加していきましょう。

一方、候補に出ない、選んでも参照できないという場合は、指定の詳しさだけでは解決しません。次の除外設定を調べます。フォルダー全体を一度に付けても、必要な全ファイルの全文が必ず回答に使われるわけではないため、まず1ファイルで結果を比べる方が状況を把握しやすくなります。

対象を除外している設定を探し、必要な範囲だけ直す

Cursorの除外ファイルの説明では、プロジェクトのルートにある「.cursorignore」で、Agentや@参照などが扱うファイルを制御します。対象ファイルの名前だけでなく、親フォルダーや拡張子をまとめて除外していないかも見てください。

例えば「src/auth/」全体が除外されていれば、その中のlogin.tsにも影響します。まず、なぜその設定があるかを確認しましょう。必要なソースを調べられるようにすることと、APIキーや秘密鍵まで参照可能にすることを一緒に扱うべきではありません。「.cursorignoreを消して解決」とせず、対象に作用しているパターンを特定します。

例外を示す「!」を付けても、親ディレクトリーごと除外されていると、その中のファイルだけを戻せない場合があります。公式説明では、除外されたディレクトリーは探索されないためです。1行の例外を追加して効かなければ、親フォルダーの指定まで見直してください。

Git側の除外を調べる手掛かりには、git check-ignore -v src/auth/login.tsがあります。ただし、このコマンドでCursorの共通設定や.cursorignoreまで検査できるわけではありません。Gitでは除外されていないと分かっても、Cursor側の設定は引き続き確認する必要があります。

なお、.cursorignoreは秘密情報を完全に隔離する仕組みではありません。公式説明では、AgentのターミナルやMCPツールはこの制御の外にあります。除外の問題を試すために、秘密ファイルを別のツールで読ませたり、その内容をチャットへ貼ったりする操作は避けましょう。

参照できるのに説明が古い時は、保存状態と会話を見直す

対象ファイルを選べたのに、すでに書き換えたはずの実装を説明する場合は、ファイルが保存済みか、別の作業用コピーやブランチを開いていないかを調べます。そのうえで新しい会話に同じファイルを指定し、現在の関数の短い範囲を説明してもらいましょう。

前の回答を「この実装について」と貼り直すと、古いコードの説明を自分から渡すことになります。比較には現在の実ファイルを使い、必要な条件式を自分でも開いて見てください。行番号は編集でずれるので、関数名や条件式も照合の手掛かりになります。

現行の公式検索ガイドでは、Instant Grepによるローカル検索が説明されています。古い記事にあるインデックス再作成のボタンが、今の画面にもあるとは限りません。見当たらない設定を探し続けるより、存在するファイル、除外条件、@指定での結果を先に押さえましょう。版によって表示される設定が違う場合は、自分の版と公式案内を照らして確認してください。

実ファイルと説明が一致したところから、調査を再開する

最初の質問へ戻り、validateSessionがfalseを返す条件を、現在のコードと比べます。条件式にある判断が説明され、実装にない処理が追加されていなければ、そのファイルを調べる作業は進められます。次に呼び出し元を加え、入力値や処理の流れへ調査を広げましょう。

ファイルを見つけたことだけで、ログイン不具合の原因まで分かったわけではありません。参照先の問題が解消した段階で、元の調査目的に戻ることが大切です。回答が実装と食い違う間は、提案された修正を適用する前に、その根拠のファイルを確かめてください。

解消しない場合は、Cursorの版、開いているフォルダー、対象の相対パス、自動検索と@指定の結果、関係する除外パターンを控えます。秘密情報を含まない小さな例でも同じ現象が起きるか試せると、プロジェクト全体を渡さずに問題を相談しやすくなります。モデルを替える前に、この情報がそろっていれば、何を試してどこまで参照できたかを説明できます。