フロントとバックエンドを別リポジトリで持っていると、片方で起動した Claude Code にもう片方を見せたくなります。/add-dir はそのための仕組み。起動したディレクトリの外まで、ファイルの読み書き範囲を広げます。
別リポジトリのファイルを今のセッションに足す
アクセス範囲を広げる入口は3つあります。起動時の CLI フラグ、会話中のスラッシュコマンド、そして settings.json での永続化です。手早く試すなら、まずは起動時に渡す形が分かりやすい。
起動時に渡すか、会話の途中で足すか
起動時にまとめて渡すなら --add-dir にスペース区切りで並べます。
claude --add-dir ../api ../sharedこのコマンドは渡したパスが実在するディレクトリかを検証します。タイプミスで存在しないパスを渡すと、セッションは始まらず弾かれます。
claude --add-dir ../apii
# Error: ../apii is not a valid directory会話の途中で「やっぱりあのリポジトリも見せたい」となったら、セッションを落とさず /add-dir を打ちます。
> /add-dir ../shared追加した直後から、../shared 配下のファイルは確認のプロンプトなしで読めるようになります。実際に効いたかは /context を開けば作業ディレクトリ一覧に並んで見えます。
パスは起動ディレクトリからの相対で解決される
渡すパスは、Claude Code を起動したディレクトリを基準に解決されます。../api は「起動した場所のひとつ上にある api」を指す。絶対パスでも渡せますが、隣り合うリポジトリ群なら相対で書くほうが短く済みます。
add-dir で何が読めて、何が読めないのか
/add-dir でディレクトリを足すと、そのリポジトリの ファイルは読み書きできるようになります。ただし、そこにある .claude/ の設定までフルに効くわけではない。つまずくのはこの境目です。公式ドキュメントは Configure permissions の中で、はっきり見出しを立ててこう書いています。
Additional directories grant file access, not configuration
ファイルアクセスは増えるが、設定の大半は読まれない
「設定ルートが増える」と思い込むと事故ります。追加ディレクトリに置いた settings.json の Hooks、サブエージェント定義、カスタムコマンド、output style — これらは追加先からは読み込まれません。読み込み元はあくまで起動ディレクトリとその親、ユーザーの ~/.claude/、それと管理者設定です。別リポジトリの Hooks を当てにしてファイルを足しても、フックは沈黙したままになります。たとえば追加先の .claude/settings.json に PreToolUse フックを仕込んでいても、/add-dir で足しただけでは起動しない。「フックが効かない」と悩む前に、それが起動ディレクトリ側のものか追加先のものかを切り分けると早いです。共有したい設定は、追加ディレクトリ任せにせずユーザー設定かプラグインに寄せるのが筋になります。
例外として読み込まれる設定
全部が無視されるわけではなく、--add-dir と /add-dir で足したディレクトリに限って、いくつかは読まれます。表で整理します。
| 設定の種類 | add-dir で読まれるか |
|---|---|
.claude/skills/ の Skill | 読まれる(ライブリロードあり) |
| プラグイン設定 | enabledPlugins と extraKnownMarketplaces のみ |
CLAUDE.md / .claude/rules/ | 環境変数を立てたときだけ |
| Hooks・サブエージェント・コマンド・output style | 読まれない |
共通の検証スクリプトを Skill にしておけば、足したリポジトリ側でもそのまま発火します。ライブリロードが効くので、Skill を書き換えても再起動は要りません。
CLAUDE.md を読ませる環境変数
追加ディレクトリの CLAUDE.md は、デフォルトでは読まれません。読ませたいなら環境変数を明示的に立てます。
export CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1
claude --add-dir ../sharedこれを立てた状態で起動すると、../shared/CLAUDE.md や .claude/rules/ がプロジェクトメモリと並んで読み込まれます。立てなければファイルアクセスだけで、メモリには何も足されない。後方互換を保つための opt-in なので、デフォルトが「読まない」側に倒れている点を押さえておきます。CLAUDE.md とメモリの関係そのものは Claude Code memoryとは？CLAUDE.mdとの違いと運用設計の実例で別途整理しました。
毎回打たずに済ませる—settings.json への永続化
同じリポジトリ群を毎日触るなら、起動のたびに --add-dir を打つのは面倒です。settings.json に書けば、起動時から足された状態で始まります。
permissions.additionalDirectories に書く
永続化のキーは permissions の下にあります。
{
"permissions": {
"additionalDirectories": [
"../api",
"../shared"
]
}
}これをプロジェクトの .claude/settings.json に置けば、次回以降は何も打たずに2リポジトリへアクセスできる状態で起動します。CLI で毎回渡していた2行が消えます。
永続版が読むのはファイルだけ
ひとつ注意点があります。permissions.additionalDirectories で足したディレクトリは、ファイルアクセスだけ。さきほどの「例外として読まれる設定」すら載りません。Skill も、環境変数つきの CLAUDE.md も、settings 経由では読み込まれない。つまり挙動が --add-dir フラグと完全には一致しません。Skill まで効かせたい構成なら、settings に書くのではなく --add-dir 起動を選ぶ必要があります。
追加ディレクトリの編集権限はモードで決まる
足したディレクトリのファイルは、読み取りはプロンプトなしで通ります。編集は別で、その時点のパーミッションモードに従います。acceptEdits モードなら、作業ディレクトリと同じく additionalDirectories 内の編集も自動承認される。デフォルトモードなら最初の編集で確認が入ります。
気をつけたいのは読み取りのほうです。足した瞬間からプロンプトなしで読めるので、秘密ファイルを含むディレクトリを軽い気持ちで足すと、その中身も確認なしで読まれる対象に入ります。読ませたくないパスがあるなら、Read の deny ルールを併用して塞いでおきます。要は、追加ディレクトリだけ特別扱いされるわけではなく、元の作業ディレクトリと同じルールが横展開されるだけです。モードと許可ルールの詳しい評価順序は Claude Code permissions—allow/denyの落とし穴と評価順序にまとめてあります。
/add-dir と /cd は役割が違う
似た名前で /cd がありますが、やることは逆方向です。/add-dir はアクセス範囲を横に広げる。/cd はセッションの主ディレクトリそのものを引っ越します。
横に広げる add-dir、引っ越す cd
| /add-dir | /cd | |
|---|---|---|
| 動き | アクセス先を追加する | 主ディレクトリを移動する |
| 元の場所 | そのまま残る | 移動先に切り替わる |
| 移動先の CLAUDE.md | 原則読まない | 読み込まれる |
| 必要バージョン | — | v2.1.169 以降 |
「このセッションはもう向こうのリポジトリ中心で進める」なら /cd。「片方を主にしつつ、もう片方も参照したい」なら /add-dir。主役を移すのか、脇に足すのか。そこで2つは分かれます。
–continue と –resume が拾うセッション
セッションを再開するとき、--continue と --resume は /add-dir で別ディレクトリを足したセッションも候補に含めます。あるリポジトリで作業して別リポジトリを足したセッションは、足した側のディレクトリから --resume しても拾える。再開時に「あのセッションが見つからない」となりにくい作りです。
複数リポジトリでどう使い分けるか
使えるようになると、つい何でも足したくなります。ただ、足したディレクトリはそのまま探索範囲を広げるので、数を増やすほど Claude が見て回る場所も増えます。
ルートから起動できるならそれが速い
パッケージが一段下に並ぶモノレポなら、サブパッケージの中で起動して /add-dir で兄弟を足すより、リポジトリのルートで起動するほうが速い。ルートから起動すれば、サブパッケージは最初から全部見える。足し算の手間がそもそも要りません。
# サブパッケージで起動して足していく
cd packages/web && claude --add-dir ../api ../shared
# ルートで起動すれば一発で全部見える
cd monorepo-root && claude下のほうは追加引数ゼロで、packages/web も packages/api も最初から探索範囲に入ります。実際、別パッケージのリポジトリで作業していて、後から2つ3つと足していくうちに「最初からルートで開けばよかった」と気づいたことがある。足す対象が固定なら、見直すのは起動位置のほうです。ただし、足したディレクトリはそのぶん grep や glob の走査対象に入ります。今のタスクに関係ないリポジトリまで足すと、探索の空振りが増えてトークンも余計に食う。必要なものだけ足す、が結局いちばん効きます。
worktree とどちらを使うか
別リポジトリではなく、同じリポジトリの別ブランチを同時に触りたいなら、/add-dir より worktree のほうが噛み合います。/add-dir はあくまで「今のセッションに別の場所のファイルを足す」だけで、ブランチの並行作業は守備範囲外。git の worktree でセッションごとに作業ツリーを分ける設計は Claude Code worktreeの使い方—並列開発でセッション衝突を防ぐ設計で扱っています。横断は /add-dir、並行は worktree、と分けて考えると迷いません。
まとめ
--add-dir(起動時)、/add-dir(会話中)、permissions.additionalDirectories(永続)の3経路でアクセス範囲を広げられる- 追加ディレクトリはファイルアクセスが増えるだけで、Hooks やサブエージェント定義などの設定は基本読まれない
- Skill とプラグイン設定の一部は
--add-dir経由なら読まれ、CLAUDE.md はCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を立てたときだけ載る - settings 永続版はファイルアクセスのみで、Skill も CLAUDE.md も読まない
- 主役を移すなら
/cd、脇に足すなら/add-dir。モノレポはルート起動が手早い