はじめに — 「このファイルを読んでほしい」を、迷わず伝える

Claude Codeに質問するとき、こんなところで止まることがあります。

「READMEについて聞きたいけど、どうやって指定したらええんやろ」

ファイル名を文章で書いても伝わることはあります。でも、同じ名前のファイルが複数あったり、フォルダが深かったりすると、Claude Codeが対象を探すところから始まります。そこで今日使うのが、@メンションです。

Claude Codeの入力欄で@を入力すると、ファイルパスの候補が表示されます。候補から読みたいファイルを選び、そのまま質問を書けます。人に資料を渡すとき、「あの資料」ではなく、目の前の1枚を指さす感じですね。

この記事で扱う機能は、この@ファイルパスメンションだけです。インストールから始めて、練習用のREADME.mdを指定し、1文の説明を返してもらうところまでを10分で進めます。

先に大事な点です。@は通常のターミナルにコマンドとして打つのではなく、claudeを起動した後のClaude Codeの入力欄で使います。

`@`メンションとは何か

Claude Code公式のInteractive modeでは、@はFile path mentionとして説明されています。入力すると、ファイルパスのオートコンプリートが起動します。

ここで出てきた言葉を、先にほどいておきます。

CLI: ターミナルで文字を打って操作する方式です。Claude Codeはclaudeというコマンドで起動できます。
ファイルパス: ファイルがどこにあるかを示す「住所」です。たとえばREADME.mdやsrc/app.jsです。
オートコンプリート: 入力の途中で候補を表示し、選べるようにする仕組みです。
メンション: ここでは、質問の中で「このファイルです」と対象を示す入力方法です。

つまり@メンションは、Claude Codeへ質問するときに、読んでほしいファイルの住所を候補から選ぶための入口です。

@README.md このファイルの役割を1文で説明してください

この例の@README.md部分は、全部を手入力するより、@を打って表示された候補から選ぶのが基本です。候補を選んだあとに、質問を続けます。

なお、@を付けたから回答が必ず正しくなる、という機能ではありません。対象ファイルを指定しやすくする入力機能です。回答内容は、最後に自分でもファイルと照らし合わせるのが安心です。

なぜ便利なのか — 探し直す1往復を減らせる

Claude Codeは、必要に応じてプロジェクト内のファイルを探してくれます。公式Quickstartにも、プロジェクトのファイルを必要に応じて読むとあります。なので、毎回すべてを指定しないと使えないわけではありません。

それでも@が便利なのは、質問の対象が決まっているときに、その場所を最初から渡せるからです。

たとえば、次の2つを比べてみます。

設定ファイルを説明してください

@config/app.json この設定項目を、初めて触る人向けに説明してください

前者では、どの設定ファイルかをClaude Codeが探す必要があります。後者では、対象を先に絞れます。大きなプロジェクトほど、この小さな指定が「どのファイルですか」という確認や、別ファイルを読んで戻る1往復を減らしてくれます。

便利さの正体は、派手な自動化ではありません。質問のスタート地点をそろえることです。

使う前の準備 — インストールから初回起動まで

ここからは、まだClaude Codeを入れていない状態から進めます。ターミナルを開き、公式QuickstartにあるNative Installを実行します。

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

WSLは、Windows上でLinux環境を使う仕組みです。WindowsのPowerShellを使う場合は、次のコマンドです。

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

インストールできたか確認します。

claude --version

正常なら、バージョン番号と(Claude Code)が表示されます。筆者環境では次を確認しました。

2.1.220 (Claude Code)

バージョン番号は更新で変わります。同じ数字でなくても、claude --versionがエラーにならずClaude Codeのバージョンを表示すれば大丈夫です。

初回は次のコマンドで起動します。

claude

初めて使うときは、ブラウザでのログイン案内が表示されます。公式Quickstartによると、Claude Codeを使うには対象のClaudeプラン、Claude Consoleアカウント、または対応するクラウドプロバイダー経由のアクセスが必要です。画面の案内に沿って認証してください。

ログイン、2段階認証、組織の権限確認が出た場合は、内容を自分で確認して進めます。認証情報を記事のコード例やチャットへ貼り付ける必要はありません。

10分ハンズオン — READMEを`@`で指定する

いきなり仕事のプロジェクトを使うと不安になりやすいので、まずは練習用フォルダを作ります。次のコマンドを上から順にコピーしてください。

mkdir claude-at-practice
cd claude-at-practice
printf '# Sample App\n\nCSVを読み込み、月次レポートを作る練習用アプリです。\n' > README.md

作れたことを確認します。

ls

Windows PowerShellでlsを使っても一覧を表示できます。README.mdが見えたら準備完了です。

このフォルダでClaude Codeを起動します。

claude

ここから先は通常のターミナルコマンドではなく、Claude Codeの入力欄で操作します。

入力欄で@を1文字入力します。
表示されたファイルパス候補からREADME.mdを選びます。
選んだファイル名の後ろへ、質問を続けます。

完成形は、次のような内容です。

@README.md このファイルの役割を1文で説明してください

送信して、「CSVを読み込み、月次レポートを作る練習用アプリの説明です」のように、READMEの内容に沿った1文が返れば成功です。

確認するのは3つだけです。

@を入力したらファイルパスの候補が出た
候補からREADME.mdを選べた
READMEに書いた内容に沿う説明が返った

これで、最初の1ファイルを直接指定できました。大きな設定は要りません。まずこの小さな成功だけで十分です。

動作確認について: claude --versionは筆者環境で実行済みです。@を使う対話部分は筆者環境では動作未確認で、公式Interactive modeの仕様に基づいています。

同じ`@`機能を、実務でどう使うか

基本形は「@で対象を選ぶ + そのファイルについて頼む」です。機能を増やさず、質問だけを変えれば使い回せます。

READMEの前提を短くつかむ

@README.md このプロジェクトを初めて触る人が、最初に知るべき前提を3つ挙げてください

設定ファイルの項目を説明してもらう

@config/app.json 各設定項目が何を変えるのか、値を変更せずに説明してください

テストが確認している条件を整理する

@tests/login.test.js このテストが確認している成功条件と失敗条件を分けてください

どれも@の役割は同じです。対象を選ぶところまでを人間が決め、読み解きや整理をClaude Codeへ頼む。この分担にすると、「違うファイルを見ていた」という手戻りを減らしやすくなります。

ファイルを直してほしくないときは、依頼文に「変更せずに説明してください」と書いておくと目的が伝わりやすくなります。ただし、実際にどの操作が許可されるかはClaude Codeの権限設定にも関係します。この記事では@だけに集中するため、権限設定の詳細には広げません。

つまずきポイントとよくある質問

`@`を打っても候補が出ません

まず、次を順に確認します。

通常のシェルではなく、claude起動後の入力欄で@を打っているか
claudeを起動したフォルダに、目的のファイルがあるか
ファイル名のつづりが合っているか
claude --versionが正常に表示されるか

今回の練習なら、Claude Codeをいったん終了した後、次の2行で場所を確認できます。

pwd
ls

Windows PowerShellではpwdとlsのどちらも利用できます。claude-at-practiceの中にREADME.mdが見える状態で、もう一度claudeを起動します。

同じ名前のファイルが複数あります

README.mdが複数あるプロジェクトでは、候補に表示されるパスを見て、フォルダまで含めて選びます。

@docs/README.md この文書の対象読者を1文で説明してください

ファイル名だけでなく、docs/のような途中の住所を見るのがポイントです。

`@`の後ろに質問を書いてもいいですか

はい。候補からファイルを選んだ後、そのまま目的を書きます。「説明して」だけより、長さ、対象読者、変更してよいかを添えると、望む形に近づきやすくなります。

@README.md 内容は変更せず、セットアップ手順だけを5行以内で要約してください

フォルダ全体を指定する記事ですか

この記事の成功条件は、ファイルを1つ選ぶところまでです。最初から範囲を広げるより、1ファイルで候補表示と質問の流れを確かめるほうが、つまずいた場所を見つけやすいからです。

どんなファイルでも指定してよいですか

いいえ。秘密鍵、アクセストークン、パスワード、個人情報、顧客データを含むファイルは指定しないでください。.envという名前のファイルには認証情報が入ることが多いので、内容を確認できない状態で例に使わないのが安全です。

会社やチームで使う場合は、組織のデータ利用ルールも先に確認します。「技術的に選べる」と「送ってよい」は別の判断です。

`@`を使わなくてもよいケース

この機能は便利ですが、いつでも必須ではありません。

たとえば、ファイルが数個しかない練習プロジェクトで「このプロジェクトは何をするもの？」と聞くなら、Claude Codeの自動探索で十分なことがあります。質問の対象がまだ分からず、まず全体を調べてほしい場面でも、先に1ファイルへ絞ると視野を狭める可能性があります。

見分け方はシンプルです。

対象ファイルが決まっている → @で指定する
対象ファイルから探してほしい → 目的を文章で伝え、探索を任せる

もう一つの限界は、@で正しいファイルを選んでも、質問が曖昧なら回答も広くなりやすいことです。「誰向けに」「何を」「どの長さで」「変更するかしないか」を一言足すと、やり直しを減らせます。

まとめ — 今日は1ファイルを指せれば十分

Claude Codeの@メンションは、入力欄でファイルパスの候補を表示し、質問の対象を選びやすくする機能です。

使い方は3動作でした。

claudeを起動する
入力欄で@を打ち、ファイル候補から選ぶ
そのファイルについて質問する

最初から大きなコードベースで試す必要はありません。今日の10分ハンズオンでREADME.mdを1つ指定し、1文の説明が返れば、もう最初の成功です。

次の1アクションは、普段使うプロジェクトのREADME.mdを一度だけ@で指定し、「初めて参加する人が迷う点を1つ挙げてください」と聞くこと。押した後に起きるのは、対象ファイルを探すところではなく、その内容について考えるところから会話が始まる、という小さな変化です。

参考リンク

最終確認日: 2026-08-03

生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。続きはXで同名義を探してみてください。