Claude Media
Claude Codeの@メンションをパスだけにするCLAUDE_CODE_DISABLE_FILE_MENTIONS
Claude CodeTips

Claude Codeの@メンションをパスだけにするCLAUDE_CODE_DISABLE_FILE_MENTIONS

CLAUDE_CODE_DISABLE_FILE_MENTIONSを1にすると、@で指したファイルの中身が会話に入らずパスだけがClaudeに渡ります。設定場所と効かないときの切り分けをまとめます。

読了目安 約9分

Claude Codeで @src/utils/auth.js のように書くと、既定ではファイルの中身が会話に展開されます。環境変数 CLAUDE_CODE_DISABLE_FILE_MENTIONS を 1 にすると、この展開が止まります。Claudeに渡るのはパスと「ファイルツールで読むこと」という注記だけで、読むかどうかはClaudeが自分で判断します。

v2.1.299以降で使えます(同じリリースの他の変更はv2.1.299のリリースノートにあります)。設定できる場所にも制限があり、プロジェクトの設定ファイルに書いても効きません。

@メンションは既定で何を会話に入れるのか

変数の効果を知るには、止める前の挙動を押さえておくと早くなります。@ で指したときに起きることは、指す対象で変わります。

指す対象会話に入るもの
ファイル会話に入るもの中身。Readツールのトークン上限(既定25,000トークン)に収まる場合
256KBを超えるテキストファイル会話に入るもの展開されない
ディレクトリ会話に入るものファイルの一覧(中身ではない)
ファイルのあるディレクトリと親ディレクトリ会話に入るものそこにある CLAUDE.md も文脈に加わる

@github:repos/owner/repo/issues のようなMCPリソースの指定も同じ @ 構文ですが、変数の説明が挙げているのはファイルとディレクトリの @ メンションです。MCPリソースの展開が止まるかどうかは、説明に記載がありません。

つまり既定では、指したファイルが小さければ、Claudeがツールを呼ぶ前に中身が会話へ入ります。VS Code拡張での書き方や選択範囲の扱いはVS Code拡張の@メンションにあります。

1を設定すると何が変わるか

くらべる

@メンションの渡り方

展開あり

既定

ファイルは中身が、ディレクトリは一覧が、メッセージに含まれます。

パスのみ

DISABLE_FILE_MENTIONS=1

指したパスと「ファイルツールで読むこと」という注記が渡り、中身はClaudeが必要なときに読みます。

この変数が止めるのは「展開」であって「読み取り」ではありません。Claudeは注記を受けて、ReadなどのファイルツールでそのパスのファイルをReadします。ファイルをClaudeに見せたくない用途なら、これは読み取りを禁じる設定ではなく、権限ルール側の領分です。

使いどころ: 中身を先に入れたくない場面

@ の展開が裏目に出る場面は、おおむね次のとおりです。

  • 大きめのファイルを指すたびに、必要のない中身まで会話へ入る
  • PDFや生成物のように、全文を先に渡す必要がないものを @ で指している
  • 中身を見る前にClaudeに範囲を決めさせたい(先頭だけ、特定の関数だけ)

3つ目は、大きなファイルを範囲指定で読む使い方と相性がよい組み合わせです。大きなファイルを全文読ませるときの扱いはReadのallow_largeにまとめています。

逆に、短い設定ファイルを毎回確実に文脈へ入れたい人には、既定のままのほうが手間がかかりません。どちらが合うかは、@ で指すファイルの大きさと、中身を先に見せる価値があるかで決まります。

設定する場所と、効かない場所

変数の行には「project and local settingsでは無視される」と書かれています。リポジトリを取得しただけで、そのリポジトリの設定がメンションの挙動を変えられないようにするための制限と読めます。

設定場所効くか
シェルのexport効くか効く
ユーザー設定の env効くか効く
managed settings効くか設定場所として挙げられている
プロジェクト設定・ローカル設定の env効くか無視される(claude --debug で警告が出る)

シェルで試すなら、起動前にexportします。

claude --version
export CLAUDE_CODE_DISABLE_FILE_MENTIONS=1
claude

常用するなら、ユーザー設定(~/.claude/settings.json)の env に置きます。

{
  "env": {
    "CLAUDE_CODE_DISABLE_FILE_MENTIONS": "1"
  }
}

チームの全員に揃えたい場合に .claude/settings.json(プロジェクト設定)へ書いても、この変数は無視されます。配るならmanaged settingsか、各自のユーザー設定になります。env ブロック全般の仕組みはsettings.jsonの全項目で扱っています。

シェルのexportと設定ファイルの env で同じ変数を書いた場合は、設定ファイルの値がシェルの値を上書きします。複数の設定ファイルが同じ変数を持つときは、優先順位の高いほうが使われます。シェルで 1 にしたのに止まらないときは、設定ファイル側に別の値がないかも見ます。

Claude Desktopアプリや自己ホスト環境のランナーがセッションを起動する場合は逆で、起動側が組み立てた環境が優先されます。起動環境がすでに設定している変数については、設定ファイルの env の値は無視され、無視された変数の名前はデバッグログに出ます。

シェルのexportを打ち消したいときは、変数を空文字 "" にします。この空文字の扱いは設定リファレンスの env の説明にある一般則で、この変数に限った話ではありません。

設定ファイルの env は、ユーザー設定とmanaged settingsからは起動時に反映され、保存した変更で env が変わると実行中のセッションにも反映し直されます。プロジェクトとローカルの設定は、ワークスペースを信頼した後に反映される扱いです。ただしこの変数はそのプロジェクト・ローカル側では無視されるので、反映のタイミングを気にするのはユーザー設定とmanaged settingsの場合です。

パスだけ渡す運用での @ の書き方

変数を 1 にしても、@ の入力まわりの操作は変わりません。公式の手順にある書き方は、そのまま使えます。

  • パスは相対でも絶対でもよい
  • @ を打つとパスの候補メニューが開き、EnterかTabで選び、もう一度Enterで送る
  • 1通のメッセージで複数のファイルを指せる(「@file1.jsと @file2.jsを比べて」のような書き方)

変わるのは、送信した後にClaudeへ渡るものだけです。複数のファイルを指す場合、既定では全ファイルの中身が一度に会話へ入ります。変数を 1 にしておけば、渡るのは複数のパスと読むようにという注記で、どれをどの順で読むかはClaudeが決めます。

ディレクトリを指す使い方も同じです。既定ではファイルの一覧が入りますが、パスだけの運用では「この下を見てほしい」という指定に近くなり、一覧を取るのはClaudeのツール呼び出しになります。

効いているかを確かめる手順

効果は、同じ依頼を設定の前後で比べると分かります。Claudeの実際の出力は環境で変わるため、見る箇所だけ挙げます。

  1. claude --version でv2.1.299以降か見る
  2. 小さなファイルを @README.md を3行で要約して のように指して送る
  3. Claudeが最初にReadなどのファイルツールを呼べば、展開は止まっている。ツールを呼ばずに答えれば、中身はすでに会話へ入っている

2の依頼は、変数なしでも答えが返るため、ツール呼び出しの有無で判断します。

効かないときの切り分けは、上から順に確かめます。

切り分け

展開が止まらないときの切り分け

  1. Qバージョンはv2.1.299以降か?
    答えがいいえのとき

    古いバージョンでは、この変数が使えません。アップデートしてから再度試します。

    答えがはい
  2. Qシェルかユーザー設定に書いたか?
    答えがいいえのとき

    プロジェクト設定やローカル設定の env に書いた場合は無視されます。シェルかユーザー設定に移します。

    答えがはい
  3. Qexportの後にclaudeを起動し直したか?
    答えがいいえのとき

    シェルの変数は起動時に読まれます。exportの後でclaudeを立ち上げ直します。

    claude --debug のログに、無視された変数の警告が出ていないかを見ます。

CLAUDE_CODE_DISABLE_ATTACHMENTSとの違い

隣り合った変数に CLAUDE_CODE_DISABLE_ATTACHMENTS があります。こちらは添付ファイルの処理そのものを止める変数で、説明には「@ 構文のファイルメンションは、ファイルの内容に展開されずプレーンテキストとして送られる」とあります。

観点DISABLE_FILE_MENTIONSDISABLE_ATTACHMENTS
対象DISABLE_FILE_MENTIONSファイルとディレクトリの @ メンションDISABLE_ATTACHMENTS添付の処理全体
@ の扱いDISABLE_FILE_MENTIONSパスと、ファイルツールで読む旨の注記を渡すDISABLE_ATTACHMENTSプレーンテキストとして送る
プロジェクト・ローカル設定DISABLE_FILE_MENTIONS無視されるDISABLE_ATTACHMENTS無視される

ここで分かるのは、どちらも @ を展開しない点です。差は、Claudeに「読むべき場所」を伝えるかどうかにあります。@ の挙動だけを変えたいなら DISABLE_FILE_MENTIONS のほうが対象が絞られています。

DISABLE_ATTACHMENTS の影響範囲は、@ 以外の添付にも及ぶ可能性があります。ただ、その範囲は変数の説明に記載がないため、ここでは断定しません。

似た名前の設定と、混同しやすい点

@ まわりには、展開を止める変数とは別の層で効く設定がいくつかあります。名前が近いので、どこに効くかを分けておくと迷いません。

設定効く場所
CLAUDE_CODE_DISABLE_FILE_MENTIONS効く場所@ を送った後の展開(中身・一覧を会話へ入れるか)
respectGitignore効く場所@ のファイル選択メニューに、gitignoreされたファイルを出すか
fileSuggestion効く場所@ の候補を、自前のコマンドで作るか
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS効く場所ファイル読み取りのトークン上限(既定25,000)

候補メニューに出すファイルを絞りたいなら respectGitignore や fileSuggestion、展開された中身を減らしたいなら今回の変数、という分担です。

CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS は、大きなファイルを丸ごと読ませたいときに上限を上げる変数です。@ の展開で見る「Readツールのトークン上限」がこの変数に連動するかどうかは、説明に記載がありません。上限まわりを触る前に、手元で小さなファイルを使って確かめるのが確実です。

チームで揃えたいときの選択肢

プロジェクトの .claude/settings.json に書いても無視されるので、リポジトリにコミットして全員に配る形は取れません。この変数は、設定リファレンスの「env で無視される変数」の一覧に、CLAUDE_CODE_DISABLE_ATTACHMENTS と並んで載っています。同じ一覧には、保存先を変える変数やテレメトリの出力先を決める変数も入っています。チェックアウトしたリポジトリに握らせたくない種類の設定、という整理です。

残る配り方は次の2つです。

  • 各自がユーザー設定(~/.claude/settings.json)の env に書く
  • 管理者がmanaged settingsで配る

CLAUDE_CODE_DISABLE_ATTACHMENTS については、v2.1.290より前はプロジェクト設定やローカル設定からも設定できた、と書かれています。古いバージョンのままのメンバーがいると、同じ設定でも挙動が揃わない点には注意が必要です。

まとめ

@ で指したファイルの中身を先に入れるか、パスだけ渡してClaudeに読ませるかは、環境変数1つで切り替わります。大きなファイルや範囲を絞りたいファイルを @ で指すことが多いなら、ユーザー設定に置く価値があります。逆に小さなファイルを確実に文脈へ入れたいなら、既定のままで足ります。

プロジェクトの設定ファイルでは効かない点だけは、先に覚えておくと詰まりません。

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

関連する記事

Claude Code をもっと見る →