Claude Codeにファイルの内容を伝える方法はいくつかある。ドラッグ&ドロップで添付する方法、@を使ってメンションする方法、そしてファイルパスをそのまま文章中に書く方法である。見た目の操作はどれも似ているが、内部の処理フローは方法ごとに異なる。この記事では、それぞれの方法がどのように処理され、消費コストや速度にどう影響するかを、公式ドキュメントの記述に基づいて整理する。
「この記事でわかること」
- @メンションとパス指定とで、Claude Code内部の処理フローがどう変わるか
- ファイル添付・@メンション・パス指定それぞれの、追加のツール呼び出しの有無
- 追加のツール呼び出しが発生する場合に、速度とトークン消費にどう影響するか
- ディレクトリを参照した場合の挙動の違い
- CLAUDE.mdやコマンド（スキル）ファイルの読み込みへの影響
- 実際に自分のセッションで処理内容を確認する方法
1. Claude Codeにファイルを伝える3つの方法
Claude Codeとやり取りする中で、手元のファイルの内容を見てもらいたい場面は多い。その伝え方は、大きく分けて次の3通りがある。
まずはそれぞれがどんな操作なのか、順番に見ていく。
ファイル添付（ドラッグ&ドロップ・貼り付け）
Claude Codeのウィンドウにファイルをドラッグ&ドロップするか、画像であればコピーしてCtrl+V（macOSのiTerm2ではCmd+Vも可）で貼り付ける方法である。主に画像を扱うときに使われる。
@メンション
メッセージの中で「@」を入力すると、パスの候補が表示される。目的のファイルやディレクトリを選んでEnterまたはTabで確定する方法である。
パスをそのまま文章に書く
「src/app.jsを見て」のように、@を付けずにパスを文章の一部として書く方法である。見た目はシンプルだが、後述するとおり内部の処理は@メンションとは異なる。
2. @メンションとパス指定で処理フローが分かれる理由
ここからは、それぞれの方法でClaude Codeの内部処理がどう違うのかを見ていく。なお、作業ディレクトリより上の階層にあるCLAUDE.mdは、伝え方に関係なくセッション開始時にまとめて読み込み済みである。以下で扱うのは、まだ読み込まれていないサブディレクトリのCLAUDE.mdが、ファイルアクセスのタイミングでどう読み込まれるかという話である。
@メンションの場合
@でファイルを指定すると、Claude Codeはメッセージを送信する前に、ローカルでそのファイルの内容を読み込み、メッセージ本文と一緒にモデルへ送る。モデル側から見ると、追加の操作をしなくても最初のメッセージの中にファイルの中身がすでに含まれている状態になる。
パス指定の場合
@を付けずに「src/app.jsを見て」とだけ書いた場合、Claude Codeはその時点ではファイルの中身を読み込まない。モデルがメッセージを受け取り、内容を把握するためにReadツールを呼び出す必要があると判断して初めて、ファイルの読み込みが行われる。これは、最初のリクエストとは別に、もう一往復のやり取りが発生することを意味する。
公式ドキュメントでは、Readツールはファイルパスを受け取り、行番号付きの内容を返すツールとして説明されている。ファイル全体の読み込みがトークン上限を超える場合は、先頭部分だけを返し、続きをoffsetとlimitで読むよう案内が付く。
なお、Readツールを呼ぶかどうかはモデルの判断に委ねられている。パス指定で話題にしても、モデルが「読む必要はない」と判断すればReadツールは呼ばれず、ファイルもCLAUDE.mdも読み込まれないまま応答が返ることがある。@メンションではこの判断が介在しないため、必ず読み込まれる。
ファイル添付の場合
画像などをドラッグ&ドロップやCtrl+Vで添付する場合も、@メンションと同様に、送信の時点で内容がすでにメッセージに含まれる。追加のReadツール呼び出しは発生しない。ただし、これは主に画像を対象にした操作方法であり、テキストファイルの内容を渡す用途では、@メンションやパス指定がより一般的な手段になる。
3. ディレクトリを@メンションした場合の挙動
@メンションの対象がファイルではなくディレクトリの場合、挙動が変わる。ディレクトリを@メンションすると、その中の全ファイルの内容が展開されるわけではなく、ディレクトリの一覧情報（ファイル名などの情報）が渡される。
なお、@でファイルを参照すると、そのファイルのディレクトリと親ディレクトリにあるCLAUDE.mdも合わせてコンテキストに追加される。これは複数ファイルを@メンションした場合も同様であり、2章で見た読み込みタイミングと変わらない。
4. コマンド（スキル）ファイルの読み込みへの影響
Claude Codeのコマンドやスキルは、/<name>で呼び出すMarkdownファイルであり、CLAUDE.mdとは別の仕組みで読み込まれる。この仕組みは、ファイルの伝え方（@メンション・パス指定・ファイル添付）とは連動していない。図で並べると、2つの流れがつながっていないことが分かる。
図のとおり、ファイルの伝え方の3つの箱から、コマンド・スキルの読み込みの箱へは矢印が伸びていない。あるファイルを@メンションしても、それをきっかけに関連するコマンドやスキルが自動で読み込まれるわけではないということである。
まとめると、@メンション・パス指定・ファイル添付の違いが実際に影響するのは2章で見たCLAUDE.mdの読み込みタイミングであり、コマンドやスキルファイルの読み込みには影響しない。
5. コストと速度への影響
往復が増えることの意味
パス指定でReadツールが呼び出される場合、最初のリクエストとツール結果を送るリクエストとで、少なくとも2回のAPIリクエストが発生する。@メンションやファイル添付では、最初の1回のリクエストで完結する。
公式ドキュメントの記載では、Claude Codeは会話の全履歴を毎回のリクエストに含めて送信しており、ツールを使うたびにそのツール結果を含めた新しいリクエストが発生するとされている。つまり、パス指定によって発生する追加の往復は、そのまま追加のリクエスト1回分のレイテンシと、ツール呼び出し・ツール結果部分のトークンの上乗せになる。
最終的にファイルの中身がコンテキストに乗る分量そのものは、@メンションでもパス指定でも大きくは変わらない。違いが出るのは、その中身が届くまでに要する往復の回数と、それに伴う応答までの時間である。
プロンプトキャッシュとの関係
Claude Codeはプロンプトキャッシュによって、繰り返し送信される内容のコストを抑えている。ただし、キャッシュの有効期限を過ぎてから最初に送るメッセージはキャッシュが効かず、会話全体を読み直す扱いになる。これは@メンションかパス指定かによらず共通の仕組みだが、セッションを長時間開いたまま少しずつやり取りを続けると、往復のたびに積み上がったツール呼び出し履歴も含めて再送されることになるため、パス指定による往復の増加は長いセッションほど効いてくる。
コンテキストの圧迫という観点
公式ドキュメントでは、コンテキストのサイズが大きいほどトークンコストが増えるとされており、対策として会話をこまめに整理すること（/clear）や、適切なモデルを選ぶことなどが挙げられている。ディレクトリを丸ごと@メンションして展開してしまうと、必要以上に多くのファイル内容がコンテキストに乗ってしまう可能性がある。一方でディレクトリの@メンションは一覧情報のみを渡すため、この点では不要な展開を避けやすい。
ユースケースで考える
ここまでの内容を、1本の判断の流れとして図にする。
6. 実際に確認する方法
同じ依頼を@メンションとパス指定の両方で試し、Readツールの呼び出しが発生しているかどうかを見比べることで、この違いを自分の目で確認できる。
ひとつの方法は、非対話モード（-pフラグ）でストリーム形式の出力を使い、ツール呼び出しの種類を確認するやり方である。
# @メンションを使った場合
claude -p "@src/app.js のロジックを説明して" --output-format stream-json
# パス指定を使った場合
claude -p "src/app.js のロジックを説明して" --output-format stream-json
出力はJSON形式のイベントが並ぶ形になる。パス指定の場合は、途中に"type":"tool_use"かつ"name":"Read"を含むイベントが現れる。@メンションの場合は、そのようなRead呼び出しのイベントが現れず、最初から説明のテキストが返ってくる。
もうひとつの方法は、セッション中に/usageコマンドを実行して、現在のセッションのトークン使用量を確認するやり方である。同じ内容のファイルを、@メンションで渡した場合とパス指定で渡した場合とで、それぞれ別のセッションとして試し、/usageが示すリクエスト数やトークン数を比較すると、往復の差が数値として表れる。
CLAUDE.mdの読み込み状況については、セッション中に/contextコマンドを実行すると、「Memory files」の一覧として、現在読み込まれているCLAUDE.mdの内訳を確認できる。
いずれの方法でも、実際の数値はファイルの大きさや内容、モデルの挙動によって変わるため、まずは自分の環境で試して傾向をつかむのがよい。
7. まとめ
Claude Codeにファイルの内容を伝える方法には、ファイル添付、@メンション、パス指定という3通りがある。ファイル添付と@メンションは、メッセージを送る時点でファイルの内容がすでに含まれているため、追加のツール呼び出しなしに1回のリクエストで処理が進む。一方でパス指定は、モデルがReadツールを呼び出す必要があると判断して初めてファイルが読み込まれるため、少なくとも2回のリクエストが発生する。
この違いは、最終的にコンテキストに乗るファイル内容の分量そのものよりも、そこに至るまでの往復の回数、つまり応答までの速度と、その往復にかかる追加のトークンに表れる。加えて、サブディレクトリのCLAUDE.mdが読み込まれるタイミングにも同じ違いが表れる。@メンションであれば送信時点で確実に読み込まれるのに対し、パス指定ではモデルが実際にそのファイルを読みに行くまで読み込まれない。一方、コマンドやスキルファイルの読み込みは、この3通りの伝え方とは独立した、別の仕組みで動いている。ディレクトリを@メンションした場合は一覧情報のみが渡される点も、あわせて覚えておくとよい。
出典