Claude Code @参照でファイル・ディレクトリを指定する実践Tips

@に続けてパスを打つだけで、Claude Codeにファイルやディレクトリの中身をその場で読み込ませられます。Claudeが自分でファイルを探して読むのを待つ必要がなく、対象を明示できるぶん狙った箇所だけを的確に扱わせられます。本記事は@でファイル・ディレクトリ・MCPリソースを参照する具体的な使い方を扱います。同じ@でもセッションやサブエージェント宛てにメッセージを送る用途は別物なので、両者の違いは記事の最後で切り分けます。

Claude Codeの@参照でできること

@参照とは、プロンプト中で@に続けてパスを書くことで、そのファイルやディレクトリの情報を会話に直接含める機能です。用途は大きく3つに分かれます。

• 単一ファイルの参照: ファイルの中身をまるごと会話に含める
• ディレクトリの参照: ディレクトリの構成をファイル一覧として含める
• MCPリソースの参照: 接続済みのMCPサーバーが公開しているデータを含める

いずれも@を打った時点でClaude Codeがパス候補の入力補完を表示するため、正確なパスを覚えていなくても選択して確定できます。

ファイルを@参照する

対象のファイルパスを@に続けて書きます。

Explain the logic in @src/utils/auth.js

このプロンプトを送ると、auth.jsの中身がそのまま会話に含まれます。パスは相対パス・絶対パスのどちらでも指定できます。Claudeが自分でファイルを探しに行く場合と違い、対象が確定しているため、同名のファイルが複数のディレクトリにある場合でも取り違えが起きません。

ディレクトリを@参照する

ディレクトリを指定すると、中身のファイル一覧が会話に含まれます。

What's the structure of @src/components?

ファイル参照との違いは、渡されるのがファイルの中身ではなく一覧情報だという点です。ディレクトリ構成を把握させたいだけのときはこちらを使い、特定ファイルの中身まで読ませたいときは個別にファイルを@参照します。両方を組み合わせて、「まず@src/componentsの構成を見せて、その中のButton.tsxの実装も見せて」のように1つのプロンプトに含めることもできます。

MCPリソースを@参照する

接続済みのMCPサーバーがリソースを公開している場合、ファイルと同じ@構文で参照できます。

Show me the data from @github:repos/owner/repo/issues

指定の形式は@サーバー名:リソースパスです。@を打った時点で、接続中の全MCPサーバーのリソースがファイルと並んで補完候補に表示されるため、正確な記法を覚えていなくても候補から選べます。参照したリソースは自動的に取得され、添付ファイルとして会話に加わります。

パス補完を使いこなす

@を打つとパス候補のメニューが開きます。TabかEnterでハイライトされたパスを確定し、もう一度Enterを押すとメッセージが送信されます。この2段階の挙動を意識していないと、パスを確定したつもりで意図せずメッセージを送ってしまうことがあります。

パスの一部だけを打ってから候補を絞り込む使い方も可能です。ファイル名の一部が分かっていれば、フルパスを覚えていなくても@と数文字の入力だけで候補にたどり着けます。MCPリソースの補完もファジー検索に対応しているため、正確なリソースパスの綴りを覚えている必要はありません。

複数ファイルをまとめて参照する

1つのメッセージの中に複数の@参照を含められます。

Compare the logic in @file1.js and @file2.js

比較や横断的な修正を依頼するときにまとめて渡しておくと、Claudeが自分で探しに行く手間を省け、対象範囲を取りこぼしなく指定できます。ただし関係のないファイルまで大量に含めると会話のコンテキストを圧迫するため、本当に必要なファイルだけに絞るのが基本です。

リファクタリングのように「変更対象のファイル一式を最初から確定させておきたい」場面では、この複数参照が特に効きます。「@src/api/client.tsと@src/api/types.tsと@src/hooks/useApi.tsを一貫した命名規則にリネームして」のように、変更が波及する範囲をあらかじめ全部指定しておけば、Claudeが把握していないファイルを見落として修正が中途半端に終わるリスクを減らせます。

@参照と「読んで」という指示の違い

Claude Codeにファイルの中身を扱わせる方法は@参照だけではありません。「auth.jsを読んで」と自然文で頼んでも、Claudeは自分でファイルを探して読みます。どちらも最終的にはファイルの中身を読む点は同じですが、挙動には実務上の差があります。

@参照は対象を先に確定させるぶん、同名ファイルが複数のディレクトリに存在するプロジェクトで威力を発揮します。逆に「このバグに関係していそうなファイルを探して」のような曖昧な依頼では、@参照ではなく自然文でClaudeに探索させたほうが手間がかかりません。パスが分かっているときは@参照、分かっていないときは自然文、という使い分けが基本です。

CLAUDE.mdの自動読み込みも、この確定の違いから来る挙動です。@でファイルを明示的に参照すると、Claude Codeはそのファイルの置かれた場所を正確に把握できるため、同じディレクトリと親ディレクトリのCLAUDE.mdを合わせて読み込み、そのファイルがどんな規約のもとに置かれているかを踏まえて回答します。CLAUDE.mdの書き方を階層的に整備しているプロジェクトほど、この自動読み込みの恩恵が大きくなります。モノレポでパッケージごとにCLAUDE.mdを分けている場合、意図しないパッケージの規約が混ざって見えることがあるため、複数パッケージにまたがる@参照をするときはこの挙動を思い出す価値があります。

よくあるつまずき

• 作業ディレクトリ外のファイルを参照しようとしてエラーになる: Claude Codeが読めるのは起動時の作業ディレクトリと、--add-dirや/add-dirで追加したディレクトリの範囲内です。範囲外のパスを@参照する前に、対象のディレクトリを追加しておく必要があります
• パス確定と送信を混同する: @候補の確定はTabまたは1回目のEnter、メッセージの送信はその後のEnterです。候補を選んだつもりで続けてEnterを押すと、そのまま送信されてしまいます
• ディレクトリ参照でファイルの中身まで読めると思い込む: ディレクトリの@参照が返すのは一覧情報だけです。中身が必要なファイルは個別に@参照します
• CLAUDE.mdの自動読み込みに気づかない: ファイルを@参照すると、そのファイルのディレクトリと親ディレクトリにあるCLAUDE.mdも自動的にコンテキストへ加わります。意図せず遠いディレクトリのCLAUDE.mdまで読み込まれていることがあるので、想定外の指示が反映されているように見えたらこの挙動を疑います
• 大量のファイルを一度に参照してコンテキストを圧迫する: 関連のなさそうなファイルまで念のため含めると、会話が長くなるほど本当に必要な情報が埋もれやすくなります

@参照と@メンションの違い

同じ@構文でも、Claude Codeには目的が異なる2つの使い方があります。本記事で扱った、ファイル・ディレクトリ・MCPリソースを会話に読み込ませる@参照と、別のセッションやサブエージェント宛てにメッセージを送る@メンションです。前者は「情報をこの会話に取り込む」ための機能で、後者は「別の実行主体に指示や連絡を送る」ための機能で、対象がファイルパスかセッション名かで自動的に区別されます。両方を同じプロンプトの中で使うこともでき、「@src/apiの実装を見て、問題があれば@backend-workerに伝えて」のように読み込みと連携を1つの指示にまとめられます。

よくある質問

@参照したファイルはそのままコンテキストに残り続けますか

はい。一度@参照した内容は、明示的に/clearしたり会話が圧縮(compact)されたりしない限り、以降のやり取りでも参照可能な状態で残ります。

存在しないパスを@参照するとどうなりますか

補完候補に出てこないパスを直接入力した場合、Claudeはファイルが見つからない旨を返します。タイプ入力の途中で補完候補から選ぶようにすると、存在しないパスを指定してしまう事故を防げます。

シンボリックリンク越しのファイルも@参照できますか

作業ディレクトリまたは追加済みディレクトリの範囲内であれば参照できます。ただしリンク先が範囲外にある場合は、リンク先のディレクトリを別途--add-dirで追加する必要があります。

隠しファイル(ドットファイル)も@参照の候補に出ますか

.envや.gitignoreのような隠しファイルもパスを直接入力すれば参照対象になります。ただし補完候補への出方は通常のファイルと同じ挙動に従うため、見当たらない場合はフルパスで直接入力します。

大きなディレクトリを@参照するとコンテキストを圧迫しませんか

ディレクトリの@参照が返すのはファイル一覧であって中身ではないため、ファイルを個別に参照するよりはコンテキストへの負荷が小さくなります。それでもファイル数が非常に多いディレクトリでは一覧自体が長くなるため、サブディレクトリ単位で範囲を絞って参照するほうが扱いやすくなります。

@参照はサブエージェントにも引き継がれますか

サブエージェントへタスクを委譲すると、サブエージェントは独立したコンテキストで動きます。親セッションで@参照した内容をそのまま自動で引き継ぐわけではないため、サブエージェントに読ませたいファイルがあれば、委譲する指示の中で改めて対象を明示します。

まとめ

Claude Codeの@参照は、ファイル・ディレクトリ・MCPリソースのいずれも同じ構文で扱える点が実務上の強みです。パス補完を使えば正確な綴りを覚える必要がなく、複数ファイルをまとめて渡せば横断的な依頼も1回で済みます。作業ディレクトリの範囲、CLAUDE.mdの自動読み込み、そしてセッション宛ての@メンションとの違いを押さえておけば、意図しない挙動に振り回されずに使いこなせます。