Claude Code で複数プロジェクトの文脈を分離しつつ相互参照する3つの方法 (additionalDirectories / subagent / agent-session)

複数のプロジェクトを同じ workspace/ 以下で並行して開発していると、Claude Code に「他プロジェクトのファイルは参照してほしいが、作業文脈は混ぜたくない」という場面があります。

この記事では、そのための構成として、方法A. additionalDirectories、方法B. subagent、方法C. claude --agent による agent-session の3通りを比較します。

関連記事
コード実装を担当する永続メモリ付きサブエージェント設定ファイルの例 (全部日本語) — 開発支援エージェントの定義ファイルの例です。

やりたいこと： 相互参照はしたいが、文脈は混ぜたくない

あるディレクトリ以下で複数のプロジェクトを並行して開発しているとします。

workspace/
├─ project_green/
├─ project_red/
└─ project_blue/

これらの開発を AI エージェントに手伝ってほしいが、以下の要件があるとします。

• 各プロジェクトで作業の前提が異なり (ドキュメントが英語なのか日本語なのかとか、コードのライフサイクルとか)、そもそも個々のプロジェクトがそれなりに大規模なため、プロジェクトごとに文脈を分離したい。
  • そもそもあまり作業ルールが変わらない / 個々のプロジェクトが複雑でないなら、親ディレクトリで起動した Claude に全て任せるのが楽だと思います。¹
• 他方、各プロジェクトの作業上、互いに他プロジェクトのディレクトリにあるファイルを参照したい。

3つの方法の比較

このようなとき、下記の 方法A.～C. が取れると思います。² なお、方法A. は他の方法と併用できませんが、³ 方法B. と 方法C. は併用できます。

各方法は以下のケースのときに向くのではないかと思いますが、方法C. はまだ運用を始めたばかりなので、長期運用上の欠点は見えていません。

• agent を定義するコストが払えないなら、方法A. がよい。
• プロジェクト間の行き来が多くセッションを統合したいときや、メインエージェントにある程度頼りたいなら (プロジェクト横断的な依頼をしたいなど)、方法B. がよい。
• 逆に、メインエージェントの意図せぬ介入を完全に排除したいなら、方法C. がよい。

方法	文脈分離	相互参照	コンソール	agent 定義
A. 各プロジェクトで 個別に起動	強	additionalDirectories	N個	不要
B. subagent に委譲	中〜強	親から参照	1個	必要
C. agent-session	強	親から参照	N個	必要

凡例

• 白色の ⬜ は Claude の起動場所を示す。
• 色付きの 🟢 は subagent として呼び出せる状態を示す。
• 色付きの 🟩 は agent を指定して Claude を起動することを示す。

方法A. 各プロジェクトで Claude を別個に起動する (他プロジェクトは additionalDirectories で参照)

最もシンプルな方法です。

workspace/
├─ project_green/ ⬜
├─ project_red/ ⬜
└─ project_blue/ ⬜

.claude/settings(.local).json の additionalDirectories に記入すれば他プロジェクトも参照できます (ドキュメント)。他プロジェクトから参照されるときはそこにある CLAUDE.md は勝手には読み込まれないので (はず)、文脈は妨げられません。

.claude/settings(.local).json

{
  "permissions": {
    "additionalDirectories": [
      "../project_red/",
      "../project_blue/"
    ]
  }
}

以下の長所・短所があると思います。

• ⭕ 文脈を完全に分離できる。
• ❌ CLAUDE.md や .claude/settings.json を個別管理する必要がある (それを各リポジトリでバージョン管理するなり無視するなりする必要もある)。
• ❌ 共通設定があるなら親ディレクトリにも CLAUDE.md を置く必要がある (Claude 設定とその管理がますます分散する)。
• ❌ コンソール N 画面を行き来する必要がある。

方法B. 親ディレクトリで Claude を起動し、作業は各 agent に移譲させる (subagent 方式)

こちらは各プロジェクト向けの agent を記述して、メインエージェントに作業を委譲させる方法です (subagent の形になる)。委譲といっても以下のように依頼するだけです (本来は各 agent の役割に応じて自然に委譲されるはずなのだが、明示が安全である)。ターンをまたいで subagent に文脈を継続させたいときは再開を依頼する必要があります (ドキュメント)。

@zundamon に project_green について依頼があります。…
@akane に project_red について依頼があります。…
@aoi に project_blue について依頼があります。…

workspace/ ⬜ (あるいは委譲だけをこなす agent を定義しそれを指定して起動 🟧)
├─ .claude/agents/
│    ├─ zundamon.md 🟢
│    ├─ akane.md 🔴
│    └─ aoi.md 🔵
├─ project_green/
├─ project_red/
└─ project_blue/

以下の長所・短所があると思います。

• ⭕ 文脈を分離できる (メインエージェントが意図通りに作業を委譲してくれれば)。
• ⭕ CLAUDE.md や .claude/settings.json を個別管理しなくてよい (ので、Git リポジトリ側を Claude 設定に依存しない状態に保てるし、親ディレクトリに設定を集約できる)。
• ⭕ コンソール 1 画面で完結する。
• ⭕ メインエージェントにプロジェクト横断的な依頼ができる。
• ❌ 各プロジェクト向けの agent を記述する必要がある。
• ❌ メインエージェントが意図通りに作業を委譲してくれないことがある (@zundamon のように subagent を名指しするのが安全である)。
• ❌ メインエージェントが勝手なプロンプトを追加することがある (@zundamon に以下をそのまま伝えてください などと指示するのが安全である)。
• ❌ 毎回上記のように明示的に依頼するか、あるいは作業の委譲だけをこなす agent を記述してそれを指定してセッションを起動するか、どちらかをする必要がある。

この方法 B. (subagent 方式) は、メインエージェントの仲立ちで上手くこちらの意図を汲んでくれることも期待できる一方で、余計なことをしてくることもある諸刃の剣といえます。

方法C. 親ディレクトリで各 agent を指定した Claude を別個に起動する (agent-session)

こちらも各プロジェクト向けの agent を記述する方法ですが、claude --agent zundamon のようにエージェント名を指定して起動することで、そのエージェントとのセッションを開始します (ドキュメント)。個別の agent に直接指示を出す必要がありますが、メインエージェントに意図せぬ介入をされることもありません。

workspace/ 🟩🟥🟦
├─ .claude/agents/
│    ├─ zundamon.md
│    ├─ akane.md
│    └─ aoi.md
├─ project_green/
├─ project_red/
└─ project_blue/

以下の長所・短所があると思います。

• ⭕ 文脈を完全に分離できる。
• ⭕ CLAUDE.md や .claude/settings.json を個別管理しなくてよい (ので、Git リポジトリ側を Claude 設定に依存しない状態に保てるし、親ディレクトリに設定を集約できる)。
• ❌ 各プロジェクト向けの agent を記述する必要がある。
• ❌ コンソール N 画面を行き来する必要がある。

Tips

• 方法 B. や 方法 C. で各 (サブ) エージェントにリントやテストをさせるときは uv run --directory project_green pytest のように uv の --directory オプションが活用できる (エージェントをワークルートにいさせたまま、サブディレクトリをテストできる)。
  • 個人的に、プレツールフックスクリプト・回答後フックスクリプトで、呼び出し元 (＝エージェントが現在いるワーキングディレクトリ) を利用しているので、エージェントにあちこち移動されると破綻するため。

まとめ

複数プロジェクトを Claude Code で扱うときは、「文脈分離」「相互参照」「コンソール数」「agent 定義の有無」のどれを優先するかで構成を選ぶことになると思います。

私は、プロジェクト横断の依頼をしたいときは subagent 方式、各 agent に直接作業させたいときは agent-session 方式を使うのがよさそうだと考えています。

1. ただこれで Claude を並列起動するなら、.claude/settings(.local).json で "autoMemoryEnabled": false にしておかないと自動記憶の編集が競合する恐れがあると思われる。 ↩

2. そもそも各プロジェクトに各プロジェクトのルールを記述した CLAUDE.md を置いた上で親ディレクトリで Claude を起動する方法があるが、これは全く文脈を分離していないし、project_green を開発しているときのに project_red のファイルを参照させたら project_red のルールが読み込まれてしまう (方法A. の additionalDirectories 式なら読み込まれないようである；CLAUDE.md files from --add-dir directories are not loaded by default)。 ↩

3. 方法 A. のための CLAUDE.md を各プロジェクトに置くと、方法 B., C. の運用時に妨げになる。 ↩