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

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

Claude Codeの@参照でファイル・ディレクトリ・MCPリソースを渡す書き方と、パス補完・CLAUDE.mdの自動読み込み・権限との関係、CLAUDE.mdの@importや@メンションとの違いを示します。

読了目安 約11分

@に続けてパスを打つだけで、Claude Codeにファイルやディレクトリの中身をその場で読み込ませられます。Claudeが自分でファイルを探して読むのを待たず、対象を先に指定できるのが利点です。本記事は@でファイル・ディレクトリ・MCPリソースを渡す書き方に加えて、補完の操作、CLAUDE.mdが一緒に読み込まれる仕組み、権限との関係を扱います。

同じ@でも、CLAUDE.mdの中で使う@pathや、別のセッション宛ての@メンション、サブエージェントの指名は働きが違います。違いは後半の節で切り分けます。

Claude Codeの@参照で会話に入るもの

@参照は、プロンプト中で@に続けてパスを書き、そのファイルやディレクトリの情報を会話に含める機能です。渡る情報は対象によって違います。

対象

@で渡せる3種類の対象

  • ファイル

    ファイルの中身がまるごと会話に入ります。@src/utils/auth.jsのように、相対パスでも絶対パスでも指定できます。

  • ディレクトリ

    入るのはファイルの一覧で、各ファイルの中身は入りません。@src/componentsのように指定します。

  • MCPリソース

    接続済みのMCPサーバーが公開するデータが、添付ファイルとして加わります。@サーバー名:リソースの指定の形で書きます。

@を打つとパスの候補メニューが開くので、正確なパスを覚えていなくても選んで確定できます。Claude Codeでは、@を打った時点でこのメニューが開きます。

ファイルとディレクトリを指定する書き方

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

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

送信するとauth.jsの中身が会話に入ります。ファイルを探す手順を省けるので、Claudeに探索させる場合より意図した対象に絞りやすくなります。

ディレクトリも同じ書き方で、渡るのはファイルの一覧だけです。

What's the structure of @src/components?

構成を把握させたいだけならディレクトリを指定し、実装まで読ませたいファイルは個別に@参照します。1つのプロンプトに両方を入れて、「@src/componentsの構成を見せて、その中のButton.tsxの実装も見せて」と頼むこともできます。

MCPリソースを@参照するときの書き方

接続済みのMCPサーバーがリソースを公開していれば、ファイルと同じ@で参照できます。@を打つと、リソースがファイルと並んで補完候補に出ます。MCPリソースのパスは、補完メニューでファジー検索(部分一致に近い絞り込み)が効きます。

書き方について、公式の2つのページで例の形が違います。ワークフローのページの例は@github:repos/owner/repo/issuesで、MCPのページの説明は@server:protocol://resource/pathという形です。

Can you analyze @github:issue://123 and suggest a fix?
Compare @postgres:schema://users with @docs:file://database/user-model

実際にどう書くかは、サーバーが公開するリソースのURIで決まります。迷ったら@と数文字を打って、補完に出た候補をそのまま選ぶのが確実です。

ui://で始まるUI用のリソース(MCP Apps)は、@の候補には出ません。メディアタイプがtext/html;profile=mcp-appのリソースも含め、どちらも@の候補とリソース一覧ツールの結果に出ません。UIリソースしか持たないサーバーは、一覧が空になります。

読み物としてClaudeに渡すためのものではなく、ホストアプリが画面に描画するためのものだからです。URIを指定して読むことは、引き続きできます。

パス補完の操作と、送信してしまう事故

補完メニューの操作は次の流れです。

手順

@補完でパスを確定して送るまで

  1. 1

    @を打つ

    パスの候補メニューが開きます。数文字続けて打つと候補が絞られます。

  2. 2

    候補を確定する

    TabかEnterで、ハイライトされたパスが入力欄に入ります。この時点ではまだ送信されません。

  3. 3

    もう一度Enterを押す

    ここでメッセージが送信されます。

確定のつもりでEnterを続けて押すと、そのまま送信されます。確定はTabに決めておくと、送信のEnterと混ざりません。

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

1つのメッセージに@参照をいくつでも含められます。

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

リファクタリングのように変更対象を最初から確定させたい場面で使いやすい書き方です。「@src/api/client.tsと@src/api/types.tsと@src/hooks/useApi.tsを一貫した命名規則にリネームして」のように、範囲を先に全部指定しておけます。

一方、関係の薄いファイルまで念のため含めると、会話のコンテキストを余計に使います。本当に必要なファイルだけに絞るのが基本です。

@参照と自然文の指示はどう使い分けるか

「auth.jsを読んで」と自然文で頼んでも、Claudeは自分でファイルを探して読みます。違いは、対象がいつ決まるかです。

指定方法対象の確定タイミング向く場面
@参照対象の確定タイミングプロンプト送信前に確定向く場面パスが分かっていて、そのファイルを確実に渡したいとき
「auth.jsを読んで」対象の確定タイミングClaudeが探索して確定向く場面ファイル名は分かるがパスが曖昧なとき
「〜に関するファイルを探して」対象の確定タイミングClaudeが検索して確定向く場面ファイル名も分からず、内容から探したいとき

パスが分かっているなら@参照、分からないなら自然文で探索させる、という分け方になります。

CLAUDE.mdが一緒に読み込まれる

ファイルを@参照すると、そのファイルのあるディレクトリと親ディレクトリのCLAUDE.mdもコンテキストに加わります。CLAUDE.mdの書き方を階層ごとに整えているプロジェクトでは、これが効きます。

複数のファイルを@参照した場合も、公式の説明どおりならファイルごとにその階層のCLAUDE.mdが対象になります。パッケージごとにCLAUDE.mdを分けているモノレポで複数パッケージのファイルを並べて参照すると、各パッケージの規約がそれぞれ加わる点に注意が要ります。想定外の指示が反映されているように見えたら、参照したファイルの階層を確認します。

権限のルールは@参照にも及ぶ

Readの権限ルールは、@fileの参照にも適用されます。公式の説明では、GrepやGlobのようにファイルを読む組み込みツールと同じく@fileの参照にも、Readルールを「best-effort」で適用するとされています。

best-effortは、ルールが確実に効くとは限らないという意味です。permissions.denyで読み取りを禁じたファイルでも、@参照で確実に止まるとは限りません。機密ファイルの保護をdenyだけに頼らないようにします。

同じ@の4つの使い方

@はClaude Codeで4つの場面に出てきます。書く場所が違い、働きも別です。

違い

@の4つの使い方

  • プロンプトの@参照

    書く場所はプロンプトです。ファイル・ディレクトリ・MCPリソースを、その会話に読み込みます。

  • CLAUDE.mdの@path

    書く場所はCLAUDE.mdです。指定したファイルが起動時に展開され、そのCLAUDE.mdと一緒に読み込まれます。相対パスは、CLAUDE.mdのあるディレクトリから見て解決されます。再帰的な取り込みは最大4段までです。

  • @セッション名のメンション

    書く場所はプロンプトです。別のセッション(候補は既定で同じマシン上のもの)を指名し、メッセージを送らせます。v2.1.232以降で使えます。

  • @サブエージェント名の指名

    書く場所はプロンプトです。@の候補からサブエージェントを選び、どのサブエージェントを動かすかを決めます。タスクの内容までは決めません。

CLAUDE.mdの@pathには、実務で引っかかりやすい点が2つあります。まず、パスにスペースがあるときは、スペースの前にバックスラッシュを付けます。引用符で囲んだパスは取り込まれません。

次に、@READMEのようなパスを取り込まずに文字として書きたいときは、バッククォートで囲みます。コードスパンとコードブロックの中は、取り込みの解析から外れるためです。

セッション宛てのメンションは、@のあとに1文字以上打つと、補完に生きているセッションが候補として加わります。1つのプロンプトで「@src/apiの実装を見て、問題があれば@backend-workerに伝えて」のように併用することもできます。別マシン(クラウドやRemote Control)のセッションは、Claudeに一覧させるかメッセージを送らせた後でないと候補に出ません。

セッション名にスペースなどが含まれるときは、@"release notes"のように引用符で囲みます。同じ名前のセッションが複数あれば、送信前にClaudeが確認します。詳しい使い方は別のセッション宛てにメッセージを送る方法にあります。

受け取った側では、メッセージ中の@は書かれたままの文字として届きます。ファイルやMCPリソースが添付されることはありません。パスを渡す必要があれば、受け取ったClaudeが自分のツールで開くことになります。

作業ディレクトリの外のファイルを@参照するには

既定でClaudeがアクセスできるのは、起動したディレクトリです。範囲を広げる起動オプションは、claude --helpに次の行で出ます(v2.1.285で確認)。

claude --version
claude --help

claude --versionは2.1.285 (Claude Code)と表示し、claude --helpには次の行があります。

--add-dir <directories...>            Additional directories to allow tool
                                      access to

「ツールがアクセスできるディレクトリを追加する」オプションで、複数のディレクトリを続けて渡せます。セッション中は/add-dirでも追加できます。

設定ファイルのpermissions.additionalDirectoriesに書けば毎回の指定は要りません。トップレベルではなくpermissionsの下に書きます。ただし設定ファイル経由で追加したディレクトリはファイルアクセスだけが対象で、その中のスキルなどの設定は読み込まれません。--add-dirと/add-dirで足したディレクトリとは、この点が違います。

セッションごと別のディレクトリへ移すなら/cd <path>です。会話は保たれ、移動先のCLAUDE.mdが読み込まれます。v2.1.246より前の/cdは、移動先の設定・フック・MCPサーバー・スキルを、--resumeするまで反映しませんでした。

@の候補に出るファイルの範囲

@のファイル候補は、changelogの記録では次の順に広がってきました。

  • v1.0.6: シンボリックリンクが@の補完で扱われるようになりました
  • v1.0.64: 隠しファイルが検索と@メンションの候補に加わりました
  • v2.1.0: settings.jsonのrespectGitignoreで、@のファイルピッカーの挙動をプロジェクトごとに決められるようになりました

隠しファイルも候補に入るので、候補に出ることと読み取りが許可されることは別だと考えておきます。機密ファイルはReadのdenyルールでも守ります。前の節のとおり、それも確実な遮断ではありません。

よくある質問

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

名前付きのサブエージェントは、渡されたプロンプトだけを持つ新しいコンテキストで動きます。読ませたいファイルは、委譲の指示の中で改めて指定します。

一方、fork(会話を分岐させるサブエージェント)は起動した時点の会話履歴をすべて引き継ぐので、@参照した内容も入っています。forkモードは対話セッションで既定でオンです。

まとめ

パスが分かっているなら@で対象を先に固定します。機密ファイルはdenyだけで守れる前提にせず、そもそも候補に出る場所に置かない運用も併せて考えます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →