Claude Code CLIのファイル添付とVS Code拡張の@メンション
Claude Code CLIでファイルや画像を添付する3つの方法と、VS Code拡張の@メンションでフォルダ・PDFの特定ページ・選択中のコードを渡す書き方を解説します。
ターミナルのClaude Code CLIでファイルを添付するには、@ でパスを指定するか、画像をドラッグまたは Ctrl+V で貼り付けます。違いは後半の「CLIでファイルと画像を添付する3つの方法」にあります。
VS Code拡張のプロンプトボックスで @ に続けてファイル名やフォルダ名を打つと、Claudeはその中身を読んだうえで回答や編集に進みます。名前を指定するだけで文脈を渡せる書き方です。
ただし、ファイルを渡す入り口は@メンションだけではありません。エディタで選んだ範囲は何もしなくても届き、開いているファイルのパスも既定で届きます。Shiftを押しながらのドラッグ、/ のコマンドメニュー、ターミナル出力の参照(@terminal:name)もあります。
「何が自動で届いていて、何を自分で足す必要があるか」を知っておくと、指定漏れも余計な指定も減ります。VS Code拡張の導入と全体像は別記事にあるので、ここでは文脈の渡し方に絞ります。@メンションの展開そのものを止める方法はDISABLE_FILE_MENTIONSにあります。
渡したいものから選ぶ入力手段
名前がわかるファイル・フォルダ
@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を整理したい、といった依頼で範囲をフォルダ単位で渡す使い方です。
CLIでは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
送信後にトランスクリプトを見る
統合ターミナルでClaude Codeを動かしている場合、
⧉ Selected N lines from <file>という行が出ていれば、その範囲は届いています。Claudeに何が渡ったかを後から確かめる手がかりになります。 - 2
行が出ないときはAttach Selection設定を見る
拡張の
attachSelection設定(Claude Code v2.1.300以降)がオフだと、CLIは選択を文脈に含めません。オフのままでも、選択してOption+K/Alt+Kを押せば、その範囲を@メンションとして足せます。 - 3
それでも届かないときは拒否ルールを見る
そのファイルが
Readの拒否ルールに一致していると、選択したテキストも、開いているファイルの通知も届きません。拒否ルールの書き方は、この次の節にあります。
選択しても中身が届かないファイル
選択したのに回答が的外れなときは、拡張が意図的に中身を伏せている可能性があります。ワークスペース内で 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をクリックします。添付はプロンプトボックスに残るため、送信前に不要なものを外して文脈を軽くできます。@メンションとの違いは、名前で探させるか、実際のファイルを手で持ち込むかという入り口の差です。VS Code 1.140.0以降はエクスプローラーからのドラッグが届かない不具合があり、原因と代替はShiftドラッグが効かない原因と回避策にあります。
/ を打つか、/ ボタンを押すと開くコマンドメニューにも、ファイルの添付、モデルの切り替え、拡張思考の切り替えといった項目があります。キーボードの記法に慣れていなければ、メニューから選ぶ手もあります。ほかのコマンドはスラッシュコマンド実用集で確認できます。
関連ファイルを渡したうえで計画を立てさせたいときは、/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が要るのは、参照を文面に挿入したいときだけです。
CLIでファイルと画像を添付する3つの方法
拡張ではなくターミナルで claude を動かしている場合、ファイルは @ で、画像はドラッグ・貼り付け・パス指定で渡せます。
CLIで文脈にファイルを加える
- 1
@でパスを指定する
Explain the logic in @src/utils/auth.jsのように書きます。@を打つとパスの候補メニューが開き、EnterかTabで候補を確定できます。パスは相対でも絶対でもかまいません。 - 2
画像をドラッグまたは貼り付ける
画像はClaude Codeのウィンドウへドラッグできます。コピーした画像は
Ctrl+Vで貼れて、WindowsとWSLではAlt+Vを使います。貼ると[Image #N]というチップが入り、プロンプトの中で番号を指して参照できます。 - 3
パスを文章で伝える
Analyze this image: /path/to/your/image.pngのように、画像のパスを依頼文に書く方法でも渡せます。
@ で取り込めるのは、Readツールのトークン上限(既定で25,000トークン)に収まるファイルです。256KBを超えるテキストファイルは含まれません。フォルダを指定した場合は、中身ではなくファイルの一覧が入ります。1つのメッセージに @file1.js と @file2.js のように複数を並べることもできます。
@ で指定したファイルでは、そのディレクトリと親ディレクトリの CLAUDE.md も文脈に加わります。@ での取り込みはツール呼び出しを伴わないため、PreToolUse フックは走りません。読ませたくないパスを止めたいときは、「選択しても中身が届かないファイル」の節で見た Read の拒否ルールが有効です。
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固有の設定はリンク先の記事にあります。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。