Claude Code VS Code拡張の@メンションでファイル・フォルダを参照する

VS Code拡張のプロンプトボックスで @ に続けてファイル名やフォルダ名を打つと、Claudeはその内容を読み込んだ上で回答や編集を行います。開いているファイルをいちいち説明せずに、名前を指定するだけで文脈を渡せる書き方です。

VS Code拡張のプロンプトボックスには、@メンション以外にもファイルを渡す経路が複数あります。/ で開くコマンドメニューにもファイル添付の項目があり、エディタでの選択・ドラッグ&ドロップと合わせて4つの入力手段が並行して使えます。どれを使うかは「どこまで具体的に指定したいか」で決まります。名前で狙い撃ちしたいなら@メンション、いま見ている範囲をそのまま渡したいなら選択、深い階層のファイルを直感的に渡したいならドラッグ&ドロップが向いています。

@メンションでファイルを参照する基本の書き方

書き方はシンプルで、@ の直後にファイル名やパスの断片を入力します。あいまい一致に対応しているため、フルパスを正確に覚えていなくても候補が絞り込まれます。

Explain the logic in @auth

このように @auth と打つだけで、auth.js や AuthService.ts のような名前が近いファイルが候補として拾われます。プロジェクトが大きくなるほどファイル名を正確に思い出すコストが上がるため、あいまい一致は地味に効く機能です。

フォルダを参照するときは末尾にスラッシュを付ける

フォルダ全体を参照させたいときは、パスの末尾に / を付けます。

What's in @src/components/

末尾のスラッシュが無いと、同名のファイルとの区別がつかず候補が期待通りに絞られないことがあります。フォルダ配下のファイル一覧をまとめて把握させたい場面、たとえば「このディレクトリの命名規則を揃えたい」「このモジュール配下のimportを整理したい」といった依頼で活躍します。1つのメンションでディレクトリ配下をまとめて渡せるため、対象ファイルを1つずつ@で列挙する手間を省けます。個々のファイル名を思い出すより、まず対象の範囲をフォルダ単位で渡してからClaudeに絞り込ませるほうが早い場面は少なくありません。

複数の@メンションを1つのプロンプトに並べることもできます。「@src/api/ の実装と @docs/api-spec.md の仕様を突き合わせて、ズレている箇所を教えて」のように書けば、コードとドキュメントを同時に渡せます。差分を見つけさせる使い方は、レビューの初手として使いやすい組み合わせです。

PDFはページを指定して部分的に読ませる

大きなPDFをまるごと読み込ませると文脈が圧迫されがちです。VS Code拡張では、@メンションしたPDFに対して読ませたいページ範囲を指定できます。単一ページ、1-10 のような範囲指定、3 ページ以降を読ませる開いた範囲指定のいずれにも対応しています。仕様書やレポートのうち必要な章だけを読ませたいときに使う書き方で、数十ページを超える資料をチームで共有しているプロジェクトほど恩恵が大きくなります。設計書全体ではなく該当セクションだけを渡せば、Claudeの回答も余分な章に引っ張られにくくなります。

エディタで選択したコードは自動でコンテキストに入る

エディタ上でテキストを選択している状態だと、その選択範囲は自動的にClaudeから見える状態になります。プロンプトボックスの下部には選択中の行数が表示されます。選択を明示的に@メンションへ変換したい場合は、Option+K(Mac)/ Alt+K(Windows・Linux)で @app.ts#5-10 のような行番号付き参照を挿入できます。選択インジケーターの目のアイコンをクリックすると、選択範囲をClaudeから隠すかどうかを切り替えられます。斜線が入っていれば選択範囲は見えていない状態です。「見せたくない一時的な選択」と「明示的に渡したい参照」を使い分けたいときに役立ちます。

ドラッグ&ドロップでファイルを添付する

Shift を押しながらファイルをプロンプトボックスへドラッグすると、そのファイルを添付として追加できます。エクスプローラーからファイルを直接持ってきたいときや、@メンションのあいまい一致では絞り込みにくい深い階層のファイルを渡したいときに向いています。添付したファイルはプロンプトボックス内に表示され、不要になったら添付のXアイコンをクリックすれば取り除けます。

@メンション関連のショートカット早見表

Option+K / Alt+K はエディタ側にフォーカスがある状態でしか動きません。プロンプトボックスにカーソルがある状態で押しても反応しない場合は、Cmd+Esc / Ctrl+Esc で一度エディタ側にフォーカスを戻してから試します。他のショートカットと合わせて全体を確認したい場合はスラッシュコマンド実用集も参考になります。

4つの入力手段の使い分け早見表

ここまで紹介した4つの手段を、向いている場面ごとに並べると次のとおりです。

コマンドメニュー(/)からもファイル添付を呼び出せるため、キーボード操作よりメニュー操作に慣れている場合はそちらの導線も選べます。

よくあるつまずき

@メンションでの参照は直感的な分、いくつか誤解しやすいポイントがあります。

• フォルダを指定したつもりがファイルとして扱われる: 末尾の / を付け忘れると、同名のファイルと区別できず期待通りに絞り込まれません
• 選択範囲を渡したつもりが渡っていない: 選択インジケーターが非表示状態(目にスラッシュ)になっていると、エディタで選択していてもClaudeには見えていません
• Option+K / Alt+K が反応しない: プロンプトボックス側にフォーカスが残ったまま押している典型パターンです。一度エディタをクリックしてから試します
• 添付したファイルが多すぎて何を渡したか分からなくなる: Shift+ドラッグで足していった添付は、プロンプトボックス内に並んで表示されます。不要になったものはXアイコンでこまめに外し、送信前に一覧を見直す習慣をつけると混乱を防げます
• PDFの必要な章だけ読ませたいのにページ範囲を指定し忘れる: 範囲を指定しなければファイル全体が対象になります。長い資料ほど、あらかじめ必要な章のページ範囲を絞ってメンションしたほうが、狙った箇所についてピンポイントに答えさせやすくなります

JetBrainsプラグインでの参照挿入との違い

JetBrainsプラグインでも同様の参照挿入は可能ですが、ショートカットが異なります。VS Code拡張は Option+K / Alt+K を使います。JetBrains版は Cmd+Option+K(Mac)/ Alt+Ctrl+K(Windows/Linux)です。JetBrains版はGUIチャットパネルではなくIDE内のターミナルでCLIを動かす構成のため、@メンションの入力自体はターミナルへのテキスト入力として行われる点も設計上の違いです。

この違いが実務で効いてくるのは、複数のIDEを併用しているチームです。フロントエンドはVS Code、バックエンドはIntelliJ IDEAといった構成では、同じ@メンションの操作でも指を置く位置が変わります。片方のIDEに慣れた状態でもう片方を触ると、Option+K を押したつもりで反応がない、という戸惑いが起きやすいポイントです。両方のエディタを行き来する場合は、ショートカットが1文字分ずれることだけ覚えておくと混乱しません。差分表示の切り替え(auto / terminal)などJetBrains版固有の設定は、上記リンク先の記事にまとめています。

よくある質問

@メンションで指定したファイルが見つからないときはどうすればいいですか

あいまい一致は近い名前を候補に出す仕組みなので、候補一覧に目的のファイルが出てこない場合は、パスをもう少し具体的に(親ディレクトリ名を含めるなど)入力し直します。フォルダ指定なのにファイルとして扱われる場合は、末尾に / を付け忘れていないか確認します。

@メンションと選択範囲の自動コンテキストを同時に使えますか

使えます。エディタで選択した範囲は自動的にコンテキストへ入り、そのうえで別のファイルを @ メンションで追加参照することも可能です。選択範囲を渡したくない場合だけ、選択インジケーターで明示的に隠します。

開いているだけで選択していないファイルも自動で読まれますか

読まれません。自動でコンテキストに入るのはエディタ上で選択した範囲だけです。開いているだけのファイルをClaudeに読ませたい場合は、@ メンションか Shift ドラッグでの添付が必要です。

.gitignore に書いたファイルも@メンションの候補に出てきますか

出てきません。VS Code拡張の respectGitIgnore 設定は既定で true になっており、.gitignore に一致するパターンをファイル検索の対象から除外します。ビルド生成物やnode_modules配下が候補に紛れ込まないのはこの設定によるものです。あえて含めたい場合は、VS Code設定(Cmd+, / Ctrl+,)のExtensions → Claude Codeでこの項目をオフにします。大規模なリポジトリほど生成物やロックファイルの件数が多く、これらが候補に混ざると本当に探したいソースファイルが埋もれてしまいます。既定のままにしておくメリットが大きい設定です。オフにする判断は、生成物そのものをClaudeに見せる明確な理由があるときに限るのが安全です。

Planモードで実行計画を確認するときも@メンションは使えますか

使えます。プロンプトボックスでの入力方法自体はモードによって変わらないため、Planモードで計画を練る段階から関連ファイルを@メンションで渡せます。実行前に十分な文脈を渡しておくと、計画の精度も上がりやすくなります。Plan Modeを含む許可モードの切り替え方はClaude Code完全ガイドで扱っています。