Claude Code VS Code拡張の@メンションでファイル・フォルダを参照する
VS Code拡張のプロンプトボックスで@メンションを使い、ファイル・フォルダ・PDFの特定ページ・選択中のコードをClaudeに渡す書き方をまとめます。
VS Code拡張のプロンプトボックスで @ に続けてファイル名やフォルダ名を打つと、Claudeはその中身を読んだうえで回答や編集に進みます。名前を指定するだけで文脈を渡せる書き方です。
ただし、ファイルを渡す入り口は@メンションだけではありません。エディタで選んだ範囲は何もしなくても届き、開いているファイルのパスも既定で届きます。Shiftを押しながらのドラッグ、/ のコマンドメニュー、ターミナル出力の参照(@terminal:name)もあります。
「何が自動で届いていて、何を自分で足す必要があるか」を知っておくと、指定漏れも余計な指定も減ります。VS Code拡張の導入と全体像は別記事にあるので、ここでは文脈の渡し方に絞ります。
渡したいものから選ぶ入力手段
名前がわかるファイル・フォルダ
@authや@src/components/のように打ちます。あいまい一致なので、フルパスを覚えていなくても候補が絞られます。いま見ているコード
エディタで選択するだけで届きます。行番号つきで明示的に固定したいときだけ
Option+K(Mac)/Alt+K(Windows・Linux)を使います。エクスプローラーのファイル
Shiftを押しながらプロンプトボックスへドラッグします。画像は貼り付けでも渡せます。ターミナルのエラー出力
@terminal:名前で参照します。コピーして貼る手間が要りません。
ファイルとフォルダを@メンションで指定する
@ の直後にファイル名やパスの断片を入力します。あいまい一致に対応しているため、名前の一部だけで候補が出ます。
Explain the logic in @auth@auth なら auth.js や AuthService.ts のような近い名前が拾われます。ファイル数が多いプロジェクトでは、正確なパスを思い出すより断片を打つほうが速く済みます。
フォルダ全体を渡すときは、パスの末尾に / を付けます。
What's in @src/components/公式のサンプルにも「フォルダは末尾のスラッシュを含める」と注記があります。フォルダ配下をまとめて渡せるので、ファイルを1つずつ列挙する手間が省けます。命名規則をそろえたい、あるモジュールのimportを整理したい、といった依頼で範囲をフォルダ単位で渡す使い方です。
1つのプロンプトに複数の@メンションを並べる書き方も試せます。公式のサンプルは1件ずつなので、複数指定の挙動は手元で確かめてからお使いください。「@src/api/ の実装と @docs/api-spec.md の仕様を突き合わせて、ズレている箇所を教えて」のような依頼が一例です。
長いPDFはページ範囲を指定して読ませる
大きなPDFをまるごと読ませると、無関係な章まで文脈に入ります。@メンションしたPDFには、読ませたいページを依頼文で指定できます。単一のページ、1-10 のような範囲、3ページ目以降のような開いた範囲のいずれも使えます。
手元で試すときに引っかかりやすいのが、ページ範囲の指定が別の道具に依存している点です。公式のReadツールの説明によると、10ページを超えるPDFは pages パラメーターで範囲を分けて読み、1回に読めるのは20ページまでです。ページ範囲の読み取りにはpoppler-utilsに含まれる pdftoppm が必要で、無いと pdftoppm is not installed というエラーになります。
インストールはmacOSなら brew install poppler、DebianやUbuntuなら apt-get install poppler-utils です。WindowsなどではpopplerのビルドをPATHに通す必要があります。しかもこの要件は「Claude Codeが動いているマシン」に対するものです。リモート環境やコンテナで拡張を動かしているなら、入れる先は手元のPCではなく、そちらになります。
短いPDFであれば、ページ範囲を指定しなくても全体が読まれます。範囲指定が効くのは、10ページを超える仕様書やレポートから必要な章だけを読ませたい場面です。
選択範囲と開いているファイルは何が自動で届くか
エディタでテキストを選択すると、選んだコードはClaudeから自動的に見えます。プロンプトボックスの下部には、選択中の行数が表示されます。
Option+K(Mac)/ Alt+K(Windows・Linux)を押すと、ファイルパスと行番号の参照が入力欄に入ります。たとえば @app.ts#5-10 の形です。選択は自動で届くので、このショートカットの役目は「この範囲を指していると文面にも明示する」ことです。
選択の自動送信を止めたいときは、選択インジケーターのXをクリックします。別のテキストを選び直すとインジケーターは戻ります。つまりXは「今回の選択を外す」操作で、設定のオフではありません。
選択していなくても、開いているファイルは届きます。Claudeはエディタで開いているファイルを把握していて、プロンプトボックスにもそのファイル名が表示されます。これを止めるのが attachOpenFile 設定で、オフにすると選択したテキストだけが渡ります。この設定はClaude Code v2.1.271以降が対象です。オフにしても、そのファイル内でテキストを選択している間は、ファイルのパスが届きます。
選択とファイルパスは、拡張が起動するローカルのMCPサーバー(名前は ide)経由でCLIに渡ります。このサーバーは設定するものがないため /mcp の一覧には出ません。組織が PreToolUse フックでMCPツールを許可リスト化している場合は、存在を知っておく必要があります。
作業中のClaudeにメッセージを積んだ場合の挙動も押さえておきます。Enter を押した時点の選択が保持され、そのあとに別の場所を選んでも入れ替わりません。
選択したコードが届いているか確かめる
- 1
送信後にトランスクリプトを見る
⧉ Selected N lines from <file>という行が出ていれば、その範囲は届いています。Claudeに何が渡ったかを後から確かめる手がかりになります。 - 2
行が出ないときはXで外していないか見る
外した直後は選択が送られません。選び直してから送信します。
- 3
それでも届かないときはファイルの種類を見る
files.excludeやsearch.excludeに一致するファイルは、パスまでしか届きません。次の節が該当します。
選択しても中身が届かないファイル
選択したのに回答が的外れなときは、拡張が意図的に中身を伏せている可能性があります。ワークスペース内で files.exclude または search.exclude に一致するファイルは、選択したテキストではなくパスまでしか届きません。
.gitignore に一致するファイルにも同じ扱いが及びます。条件は、VS Codeの search.useIgnoreFiles と拡張の respectGitIgnore がどちらもオンであることで、どちらも既定でオンです。respectGitIgnore は選択の文脈だけでなく、ファイル検索にも効きます。@メンションの候補検索も同じ検索なら、ビルド生成物や依存パッケージのディレクトリが候補に出にくくなるはずですが、公式の記述はファイル検索までで、候補への効き方は推測です。
一方で、この伏せる処理はチャットパネルにしか効きません。統合ターミナルでClaude Codeを動かしているときは、CLIが選択したテキストをファイルの種類に関係なく送ります。公式は、中身を絶対に渡したくないファイルに Read の拒否ルールを書くよう案内しています。このルールに一致するファイルは、選択したテキストも、開いているファイルの通知も届きません。
.env のような機密ファイルは、拡張側の除外設定だけに頼らず、拒否ルールを書いておく選択肢があります。書式は permissions の deny に Read ルールを並べる形です。
{
"permissions": {
"deny": ["Read(./.env)", "Read(./secrets/**)"]
}
}ファイル名だけの Read(.env) はどの階層の .env にも一致し、Read(**/.env) と同じ意味になります。逆に、生成物の中身をClaudeに見せたい場面では respectGitIgnore をオフにできます。対象は候補の検索だけでなく選択の文脈にも及ぶため、影響範囲は広めです。
ターミナルの出力を@terminalで渡す
エラー文やログをコピーして貼る代わりに、@terminal:名前 で参照できます。名前にはターミナルのタイトルを入れます。
@terminal:zsh の直近のエラーを見て、原因を教えてタイトルはVS Codeのターミナルタブに表示されている名前です。コマンドの出力やエラーメッセージ、ログをそのまま渡せるので、長いスタックトレースを貼り直す手間がなくなります。
ファイルや画像はドラッグと貼り付けで添付する
Shift を押しながらファイルをプロンプトボックスへドラッグすると、添付として追加できます。エクスプローラーからそのまま持ってきたいときに向いています。添付を外すときは、添付に付いたXをクリックします。添付はプロンプトボックスに残るため、送信前に不要なものを外して文脈を軽くできます。@メンションとの違いは、名前で探させるか、実際のファイルを手で持ち込むかという入り口の差です。
/ を打つか、/ ボタンを押すと開くコマンドメニューにも、ファイルの添付、モデルの切り替え、拡張思考の切り替えといった項目があります。キーボードの記法に慣れていなければ、メニューから選ぶ手もあります。ほかのコマンドはスラッシュコマンド実用集で確認できます。
関連ファイルを渡したうえで計画を立てさせたいときは、/plan が使えます。/plan に続けて作業内容を書くと、計画モードに切り替わって計画づくりが始まります。この機能はv2.1.280以降です。許可モード全体の切り替え方はClaude Codeとは — できること・料金・使い方にまとめています。
Option+Kが反応しないときの確認手順
Option+K / Alt+K は、エディタにフォーカスがあるときだけ動きます。公式のショートカット表にも「エディタにフォーカスされている必要がある」と書かれています。カーソルがプロンプトボックスの中にあると、押しても何も起きません。
Option+Kが効かないときの切り分け
- 1
フォーカスをエディタに戻す
Cmd+Esc(Mac)/Ctrl+Esc(Windows・Linux)は、エディタとClaudeの間でフォーカスを切り替えるショートカットです。コードを選択してから、もう一度Option+Kを押します。 - 2
Cmd+Escが効かないときはmacOSの設定を見る
macOS Tahoe以降では、Game Overlayのショートカットが既定で
Cmd+Escに割り当てられていて、VS Codeに届く前に奪われます。システム設定の「キーボード」から「キーボードショートカット」、「ゲームコントローラー」の順に開き、Game Overlayのチェックを外すと使えるようになります。割り当てを外さない場合は、拡張のキー割り当てを変える手もあります。VS Codeのキーボードショートカット画面でClaude Code: Focus inputを検索します。 - 3
エディタをクリックして直接フォーカスを移す
ショートカットが使えない環境でも、コードの上を直接クリックすればエディタにフォーカスが移ります。そこで範囲を選べば、選択自体はそのまま届きます。
Option+Kが要るのは、参照を文面に挿入したいときだけです。
JetBrainsプラグインではショートカットが違う
JetBrainsプラグインでも、選択範囲を参照として挿入する機能があります。キーが異なり、Cmd+Option+K(Mac)/ Alt+Ctrl+K(Windows・Linux)です。公式のJetBrains向けページでは、挿入される参照の例として @src/auth.ts#L1-99 が挙がっています。行範囲に L が付く書き方です。
VS Codeの例(@app.ts#5-10)とは表記が違うので、記事や社内資料で例を書くときはIDEごとに書き分ける必要があります。JetBrains版はGUIのチャットパネルではなく、IDE内のターミナルでCLIを動かす構成です。@メンションの入力もターミナルへのテキスト入力になるため、拡張のプロンプトボックスとは操作感が変わります。
両方のIDEを行き来するなら、押すキーが1つ増えます。VS Codeでは Option+K、JetBrainsでは Cmd+Option+K です。差分表示の切り替え(auto / terminal)など、JetBrains固有の設定はリンク先の記事にあります。
手元のClaude Codeで確認した点
claude --version の出力は 2.1.285 (Claude Code) でした。claude --help を見ると --ide オプションが載っていて、説明は「起動時にIDEへ自動接続する。有効なIDEがちょうど1つだけ利用できる場合」という趣旨です。拡張のプロンプトボックスではなく、ターミナルからCLIを動かす場合のIDE連携になります。
この節で確認できたのは、バージョンとヘルプの出力までです。選択範囲がCLIに届く挙動や、チャットパネルでだけ伏せる処理の違いは、公式の説明に基づいて書いています。手元のVS Codeでは再現していません。