Claude Media
Claude Code CLIのファイル添付とVS Code拡張の@メンション

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. 1

    送信後にトランスクリプトを見る

    統合ターミナルでClaude Codeを動かしている場合、⧉ Selected N lines from <file> という行が出ていれば、その範囲は届いています。Claudeに何が渡ったかを後から確かめる手がかりになります。

  2. 2

    行が出ないときはAttach Selection設定を見る

    拡張の attachSelection 設定(Claude Code v2.1.300以降)がオフだと、CLIは選択を文脈に含めません。オフのままでも、選択して Option+K / Alt+K を押せば、その範囲を@メンションとして足せます。

  3. 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. 1

    フォーカスをエディタに戻す

    Cmd+Esc(Mac)/ Ctrl+Esc(Windows・Linux)は、エディタとClaudeの間でフォーカスを切り替えるショートカットです。コードを選択してから、もう一度 Option+K を押します。

  2. 2

    Cmd+Escが効かないときはmacOSの設定を見る

    macOS Tahoe以降では、Game Overlayのショートカットが既定で Cmd+Esc に割り当てられていて、VS Codeに届く前に奪われます。システム設定の「キーボード」から「キーボードショートカット」、「ゲームコントローラー」の順に開き、Game Overlayのチェックを外すと使えるようになります。割り当てを外さない場合は、拡張のキー割り当てを変える手もあります。VS Codeのキーボードショートカット画面で Claude Code: Focus input を検索します。

  3. 3

    エディタをクリックして直接フォーカスを移す

    ショートカットが使えない環境でも、コードの上を直接クリックすればエディタにフォーカスが移ります。そこで範囲を選べば、選択自体はそのまま届きます。Option+K が要るのは、参照を文面に挿入したいときだけです。

CLIでファイルと画像を添付する3つの方法

拡張ではなくターミナルで claude を動かしている場合、ファイルは @ で、画像はドラッグ・貼り付け・パス指定で渡せます。

手順

CLIで文脈にファイルを加える

  1. 1

    @でパスを指定する

    Explain the logic in @src/utils/auth.js のように書きます。@ を打つとパスの候補メニューが開き、EnterかTabで候補を確定できます。パスは相対でも絶対でもかまいません。

  2. 2

    画像をドラッグまたは貼り付ける

    画像はClaude Codeのウィンドウへドラッグできます。コピーした画像は Ctrl+V で貼れて、WindowsとWSLでは Alt+V を使います。貼ると [Image #N] というチップが入り、プロンプトの中で番号を指して参照できます。

  3. 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固有の設定はリンク先の記事にあります。

参照した一次ソース

この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。

  1. code.claude.com/docs/en/vs-code
  2. code.claude.com/docs/en/tools-reference
  3. code.claude.com/docs/en/jetbrains
  4. code.claude.com/docs/en/common-workflows
  5. code.claude.com/docs/en/interactive-mode
この記事を共有:XはてブLinkedIn