マルチルートワークスペースは便利だがClaude Codeではひと工夫必要な話

takeda
2026-08-12
2026-08-12
KEY-VI~1

こんにちは！

今回はVSCodeのマルチルートワークスペースとその環境でClaude Codeを使用する場合の注意点などについて書いてみたいと思います。

システム開発において複数プロジェクト（リポジトリ）を横断的に扱う場面がありますよね。フロントエンド+バックエンド開発や、複数のマイクロサービスが関連するシステムなどです。

これまでは例えばフロントエンド開発とバックエンド開発の2つを同時に扱おうとすれば、

  • フロントエンド、バックエンドそれぞれをVSCodeで起動して使い分ける
  • フロントエンド、バックエンドのソースコードを子に配置した親フォルダからVSCodeを起動してまとめて操作する

のどちらかが一般的かと思います。

ただ、前者はウィンドウの切り替えが地味に面倒で、プロジェクトをまたいだ検索もできません。後者は親フォルダ配下がすべて読み込まれるため、無関係なフォルダまで検索対象に入ってしまったり、設定の管理やターミナル操作が煩雑になったりしがちです。

さらに最近はAIの導入によって、「フロントを修正したらバックも合わせて直す」「複数サービスが絡みあった問題の調査をする」といったように、1つの開発で複数プロジェクトを横断的に扱う場面が増えています。これらを効率的に操作できると便利です。

マルチルートワークスペース機能

VSCodeには、複数のプロジェクトをまとめて扱える「マルチルートワークスペース」という機能があります。

マルチルートワークスペースとは、複数のフォルダを別々のワークスペース（ルート）として1つのウィンドウで同時に開くことができる機能です。

親フォルダ方式と似ているようで異なるのは、各フォルダが独立したプロジェクトとして認識される点です。また、フォルダの物理的な配置場所は自由で、兄弟階層に並んでいる必要すらありません。別ドライブのフォルダを組み合わせることもできます。

何が便利か

ターミナルをプロジェクトごとに使い分けられる

地味ですが個人的に一番便利だと感じているのはこれです。マルチルートワークスペースでは、新しいターミナルを開くときにどのルートフォルダで開くかを選択できます。

つまり、フロントエンドのターミナルで npm run dev、バックエンドのターミナルで docker compose up を並べて起動し、それぞれのターミナルでそのままGit操作をする、といったことが1つのVSCodeウィンドウで完結します。VSCodeを切り替える必要もありませんし、親フォルダ方式のように毎回 cd する必要はありません。

フロントエンドのターミナル

バックエンドのターミナル

Git操作については親フォルダ方式でもソース管理ビューでのリポジトリの並列表示自体は自動検出されるのでGUIでは操作感はほぼ変わりませんが、Git操作で差が出るのはターミナル側で操作するときです。前述のとおり cd することなく各プロジェクトのカレントディレクトリからCLI操作できる点は非常に快適です。

必要なプロジェクトだけを、場所を問わず組み合わせられる

親フォルダ方式では配下のフォルダがすべて読み込まれるため、今回の開発に関係ないプロジェクトまで検索対象に入ってきます。また、まとめたいリポジトリをあらかじめ同じ親フォルダの下に配置しておく必要があります。

マルチルートワークスペースなら、ディスク上のどこにあるフォルダでも自由に組み合わせて、必要なプロジェクトだけのワークスペースを作れます。「この案件はフロント+バック+共通ライブラリの3つ」のように、案件単位のワークスペースを複数用意しておく、といった使い方もできます。

検索・ジャンプが全プロジェクトを横断する

全文検索や定義ジャンプはすべてのルートに対して効きます。「このAPI、バック側ではどう定義されてたっけ？」というときに、ウィンドウを切り替えることなくそのまま検索できます。

VSCodeの設定自由度が高い

フォルダ単位の設定の使い分けや、タスク設定しておけば1操作でフロント+バックを同時にサーバー起動するといった応用もできます。

マルチルートワークスペースの設定方法

設定はとても簡単です。

  1. VSCodeでいずれかのプロジェクトを開く
  2. メニューの「ファイル > フォルダーをワークスペースに追加...」で他のプロジェクトを追加
  3. 「ファイル > 名前を付けてワークスペースを保存...」で保存

これだけで .code-workspace という拡張子のファイルが作成されます。中身はシンプルなJSONです。vi等で直接作成してもOKです。親フォルダ基準にするときは直接作成してから起動するほうがやりやすいかもしれません。

{
    "folders": [
        {
            "name": "frontend",
            "path": "./example-frontend"
        },
        {
            "name": "backend",
            "path": "./example-backend"
        }
    ],
    "settings": {}
}

folders に含めるパスは相対パス・絶対パスどちらでもOKです。settings にはワークスペース全体で共有したいVSCodeの設定を書けます。

次回起動時はこの .code-workspace ファイルを開くだけで、同じ構成のワークスペースが復元されます。

コマンドラインからの起動は引数で指定します。

code example.code-workspace

Claude Codeでの注意点

さて、前置きが長くなりましたがここからが本題です。便利なマルチルートワークスペースですがその環境でClaude Codeを使うと、ちょっとした落とし穴があります。

Claude Codeの視点は「起動フォルダ」中心

Claude Codeの作業ディレクトリは、起動フォルダがカレントディレクトリになります。ここで言う起動フォルダとはマルチルートワークスペースで設定されている代表のフォルダです。厄介なのはClaudeの認識しているカレントディレクトリはVSCodeを起動したディレクトリではなく、マルチルートワークスペースのプロジェクト（おそらく最初に定義されているプロジェクト）のフォルダが基準になる点です。

ファイルの検索など、基本的にはこの起動フォルダ基準で探しに行く挙動を示します。

実際に試してみると、他のルートフォルダをまったく見ないわけではありません。フロントエンド・バックエンドといったワークスペースの構成自体は認識しており、必要に応じて適切な側を探しに行くことはあります。ただし基本的にはファイルを探す際は起動フォルダから探す傾向があり、全ての動作において視点はあくまで起動フォルダ中心です。「バック側を見てくれるときもあれば、見ずに進めてしまうときもある」という不安定さが欠点です。

そして一番の注意点は CLAUDE.md です。自動で読み込まれる CLAUDE.md は「Claudeの起動フォルダ（作業ディレクトリ）とその祖先ディレクトリ」のもののみで、他のルートフォルダの CLAUDE.md は読み込まれません。

つまり、他プロジェクトのコードを探して読むことはできても、そのプロジェクトの前提知識や規約（CLAUDE.mdに書いた内容）は伝わっていない状態で作業することになる、というわけです。

上記の例は、フロントエンドに無いdocs/sample.txtを指定したときの挙動。
フロントエンドにはdocs/sample-old.txtは存在するが、docs/sample.txtはバックエンド側にしか無い場合。
またCLAUDE.mdを認識しているかの確認のため、
フロントエンド側　→回答の末尾に「おわり」と言うようにCLAUDE.mdで指定。
バックエンド側　→回答の初めに「お答えします」と言うようにCLAUDE.mdで指定。
「おわり」としか言っていないのでフロントエンド側のCLAUDE.mdしか認識していない。

ひと工夫で横断的に見てもらう

とはいえ、対策はシンプルです。要は「他のプロジェクトの場所と前提知識を教えてあげる」ことで、横断参照を安定して行えるようになります。

対策1：プロンプトで明示的にパスを指示する

とりあえず手っ取り早い方法はこれです。「../example-backend にバックエンドのコードがあるので、そちらのAPI定義を確認してから修正して」のように、パスを添えて指示すればClaude Codeは参照しに行きます。

ただし毎回書くのは面倒ですし、指示し忘れると1プロジェクト視点に戻ってしまいます。

対策2：CLAUDE.mdに関連プロジェクトの情報を書いておく

CLAUDE.md に関連プロジェクトの場所と役割を書いておくと、指示しなくてもある程度自発的に横断参照するようになります。簡単でまずまず効果的。

## 関連プロジェクト
- バックエンド: `../example-backend`
  - このフロントエンドが呼び出すREST APIの実装
  - APIは `../example-backend/src/routes/` を参照

またCLAUDE.md には明示的に他のCLAUDE.mdを参照させるインポート記法もあります。

@../example-backend/CLAUDE.md

ただしこの方法はプロジェクト横断の場合は少し注意が必要です。初期状態では他プロジェクトのCLAUDE.mdはインポートできません。他プロジェクトのCLAUDE.md を読み込ませるには「プロジェクト外のCLAUDE.mdの読み込みを承認」しておく必要があるためです。

~/.claude.json で"hasClaudeMdExternalIncludesApproved": trueを設定しておくことで読み込みが可能となります。Claude全体またはプロジェクト毎に設定できますが、対象プロジェクトのみに設定しましょう。

セキュリティの観点からデフォルトはfalseなので設定する際はご注意ください。

対策3：additionalDirectoriesでアクセス許可を与える

作業ディレクトリ外へのファイルアクセス許可は、additionalDirectoriesで正式に与えることができます。プロジェクトの.claude/settings.jsonに次のように設定します。

{
  "permissions": {
    "additionalDirectories": ["../example-backend"]
  }
}

注意点として、additionalDirectories はあくまで「追加ディレクトリとしてのファイルアクセスを許可するもの」であり、追加したディレクトリのCLAUDE.md も読ませるには環境変数でCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1を設定しておく必要があります。

承認や許可についてはそれぞれ使い方に注意して設定してください。

設定後の挙動

バックエンド側のファイルも探しに行っており、回答のコメントも「お答えします」から始まり「おわり」で終わっているので、フロントとバック両方のCLAUDE.mdを認識していることが分かります。

まとめ

  • VSCodeのマルチルートワークスペースを使うと、複数プロジェクトを1ウィンドウで独立性を保ったまま扱えて便利
  • プロジェクトごとのターミナル操作や横断検索が快適になり、必要なプロジェクトだけを自由に組み合わせられる
  • ただしClaude Codeの視点は起動フォルダ中心。他ルートも探しには行くが不安定で、他ルートのCLAUDE.mdは読み込まれない
  • CLAUDE.mdで場所と前提知識を教える、アクセス権を適正に設定する、など「ひと工夫」で安定して横断的に働いてもらえる

AIの導入で複数プロジェクトを横断する開発はますます増えていくと思います。ツール側の機能を活かすだけでなく、「AIにプロジェクト構成を説明しやすい形にしておく」こと自体が、これからの開発環境づくりのポイントになります。

 

※ Claude Codeの挙動は執筆時点（バージョン2.1.9）のものです。マルチルートワークスペースでの挙動は公式ドキュメントに明記がないため、筆者環境での確認結果に基づいています。公式見解のものではないためAIの挙動については意図した挙動とならない場合があるのでご了承ください。
© Future Spirits Co.Ltd.