Claude Codeの--add-dirで別フォルダのREADMEを読ませる — 10分でStatusを1語確認
別のフォルダにあるREADMEを、Claude Codeに読ませたい人向けです。
この記事では--add-dirを1回使い、練習用READMEのStatus: readyからreadyという1語を返すところまで試します。
前提はmacOSまたはLinuxのターミナル、ネット接続、Claude Codeを使えるアカウントです。Windowsでの実行画面はこの記事では検証していません。
今日扱う機能は--add-dirだけ
AIエージェントは、人から目的を受け取り、必要なファイルを読んだり道具を使ったりして作業を進めるAIです。Claude Codeは、ターミナル（文字でパソコンを操作する画面）から使えるAIエージェントです。その操作方式をCLI（コマンドライン・インターフェース）と呼びます。
Claude Codeは、起動した場所を作業の起点にします。でも、説明してほしい資料が隣のフォルダにあることもありますよね。毎回その資料を作業フォルダへコピーすると、どちらが新しいか分からなくなりがちです。
--add-dirは、起動時に追加の作業フォルダを指定する機能です。公式CLIリファレンスは、追加フォルダにあるファイルをClaude Codeが読み書きできるようになる、と説明しています。今回はそのうち「読む」だけを体験します。コマンドを1回実行すると、別フォルダのREADMEから1語を取り出せます。
ここでいうフォルダは、ファイルをまとめる入れ物です。リポジトリは、変更履歴をGitで管理する作業フォルダのこと。この記事の練習ではGitを使わないので、まずは普通の2フォルダで十分です。
agent-add-dir-demo/
├── work/ ← Claude Codeを起動する場所
└── shared/
└── README.md ← 読んでほしい別フォルダのファイル
ただし、便利さと引き換えにアクセス範囲が広がります。--add-dirを「読み取り専用スイッチ」と考えないでください。秘密情報や、触れてほしくないファイルが入ったフォルダは追加しない。まずは匿名の練習フォルダだけで試しましょう。
始める前に：インストールとログイン
すでにclaudeが使える人は、この節のインストールを飛ばして構いません。公式SetupのmacOS・Linux向けネイティブ導入例は次のとおりです。実行前に、リンク先がAnthropicの公式ページであることを自分でも確認してください。
curl -fsSL https://claude.ai/install.sh | bash
インストール後は新しいターミナルを開き、次を実行します。
claude --version
バージョンが表示されればインストール確認はできています。ただし、インストール済みとログイン済みは別です。初回は次のコマンドでClaude Codeを起動し、画面の案内に従ってログインします。ログインや契約の条件は公式Setupで確認してください。この記事では特定の料金や無料利用を保証しません。
claude
ログインが終わったら、Claude Codeの画面では/exitを入力して通常のターミナルに戻ります。ここでの/exitは終了のためだけで、今日の主題は--add-dirです。以下のmkdirなどはClaude Codeの入力欄ではなく、通常のターミナルに打ちます。
1. 匿名の練習フォルダを作る
まず、今いる場所に練習用の2フォルダを作ります。次の4行を通常のターミナルへ順番に貼り付けてください。mkdir -pはフォルダを作るコマンド、printfは短い文字を書き出すコマンドです。
mkdir -p agent-add-dir-demo/work agent-add-dir-demo/shared
printf '# Sample\nStatus: ready\n' > agent-add-dir-demo/shared/README.md
cd agent-add-dir-demo/work
cat ../shared/README.md
最後のcatはファイルの中身を表示するだけです。次の2行が見えれば、準備完了です。
# Sample
Status: ready
../shared/README.mdの..は「今のフォルダの一つ上」を意味します。いまworkにいるので、一つ上へ戻ってsharedのREADMEを見る指定です。実際の仕事用フォルダはまだ触っていません。
2. --add-dirで別フォルダを渡す
通常のターミナルでworkにいるまま、次の1行を実行します。-pは質問を渡して回答を受け取り、対話画面を開きっぱなしにせず終了する公式CLIの使い方です。--permission-mode planは、今回の練習で編集作業を避けるために付けています。ただし、これだけであらゆる操作が永久に安全になると考えず、指定するフォルダの中身を先に確認してください。
claude --permission-mode plan --add-dir ../shared -p 'Read ../shared/README.md and reply only with the value of Status. Do not modify files.'
読んでほしいファイル名を質問の中でも指定しています。AIがどのREADMEか迷わないようにするためです。--add-dir ../sharedは追加フォルダをClaude Codeへ渡し、質問の../shared/README.mdはその中の対象ファイルを示します。片方だけでは、意図が伝わりにくくなります。
期待する回答は次です。AIの返答には前置きが付く場合もありますが、readyという値を正しく示しているかを見ます。
ready
これで「別フォルダのファイルをAIエージェントが読み、値を答えた」という最初の1回が完了です。理解しただけでなく、実際に1つ動いた状態です。
この記事での実行確認
2026年9月27日、macOS上のClaude Code 2.1.282で匿名のwork/sharedを作り、上の相対パス形式のコマンドを実行しました。終了コードは0、標準出力はreadyでした。終了コードは「コマンドが終了した状態を示す番号」で、0は通常の成功を意味します。README作成とcat表示も確認しています。実行環境により文章の揺れやログイン画面の有無は変わります。Windowsでの同じ手順は筆者未検証です。
3. 成功したか、自分でも確かめる
AIの回答がreadyでも、どのファイルを読んだかは人間が確認できます。通常のターミナルで次を実行してください。
cat ../shared/README.md
Status: readyと表示され、AIの答えと一致していれば今回の小さなゴールは達成です。別フォルダへのアクセスを試すだけなら、ここで止めて大丈夫。慣れてから自分の資料へ広げるほうが、どの範囲を渡したか把握しやすいと思います。
一方で、--add-dirは「許可する場所」を増やす機能であり、答えの正確さを保証する機能ではありません。AIが違う値を言ったら、ファイルを読み直して判断してください。機密を含む資料ではなく、公開しても困らないテストファイルから始めるのが安全です。
つまずきポイント
1. claude: command not foundと出る
Claude Codeの導入後に新しいターミナルを開き、もう一度claude --versionを試します。公式Setupは、インストール先にPATHが通っていない場合のトラブルシュートも案内しています。PATHは「コマンドの実体を探す場所の一覧」です。動かないまま推測でフォルダをいじるより、公式の案内で確認しましょう。
2. ログインを求められる
claude --versionが表示されても、AIへの質問には認証が必要です。claudeを単独で起動し、公式画面の案内でログインしてください。ログイン情報やAPIキーをこの記事のコードへ書き込む必要はありません。共有端末では認証状態にも注意してください。
3. README.mdが見つからない
まずpwdで現在地を確かめ、cat ../shared/README.mdでファイルを表示できるか確認します。pwdは「今いるフォルダを表示する」コマンドです。work以外にいると、../sharedが別の場所を指します。記事の4行を実行した順番へ戻って確認してください。
4. --add-dirで追加できない
公式CLIリファレンスによれば、指定先は存在するディレクトリである必要があります。../sharedの綴りを確認し、通常のターミナルでls ../sharedを実行してください。lsは中身の一覧表示です。ファイルそのものではなくフォルダを--add-dirに渡します。ネットワーク共有のパスには制限があるため、最初はローカルの練習フォルダで試してください。
5. ready以外の説明が返る
AIの出力は毎回同じ文面になるとは限りません。Statusの値がreadyと読み取れるかを見て、違うならREADMEとコマンドを照合します。Status: readyの1行をcatで確認できたのに答えが違う場合、AIの返答をそのまま採用せず、質問中のファイルパスが正しいか確認してください。
6. 利用枠に達したと表示される
2026年9月30日の再実行では、筆者の環境でYou've hit your weekly limitと表示され、AIの回答を取り直せませんでした。9月27日の匿名フォルダでのready応答確認と、今日の再実行結果は分けて記録します。利用枠の表示や再開時刻はアカウントごとに確認し、使える状態になってから同じ練習コマンドを試してください。
限界と、使わなくてよい条件
--add-dirは便利ですが、追加フォルダ全体へのファイルアクセスを許します。公式Permissionsは、読み取りだけでなく編集も可能になること、ただし追加した場所を完全な設定ルートとして扱うわけではないことを説明しています。READMEだけ見せたいなら、秘密ファイルを同じフォルダに混ぜないことが大切です。--permission-mode planを付けても、権限の仕組みそのものを理解せず大事なフォルダを指定する理由にはなりません。
また、資料がすでに起動場所の中にある人、1回だけ短いテキストを質問へ貼れば十分な人には、この追加機能は不要かもしれません。余分なアクセス範囲を広げない方がシンプルです。反対に、別フォルダの資料を繰り返し参照したいときは、コピーを増やさずに扱えることが利点になります。最初の1回は匿名の練習で、実資料への適用はその後に判断してください。
参考リンクと確認日
以下は2026年9月30日に再確認した公式ドキュメントです。インストール方法、-p、--add-dir、権限の説明はこれらと照合しました。
- Claude Code CLI reference（
--add-dir、-p、--permission-mode） - Claude Code Permissions（追加フォルダのアクセス範囲）
- Claude Code Quickstart（初回起動）
- Claude Code Setup（導入、確認、認証）
生成AI活用エンジニア&3児のパパ。AI×開発の実践知を毎日発信しています。続きはXで共有しています。