最近、Max プランの登場もあって、Claude Code が少しずつ話題になってきている印象があります。
Anthropic 社は「エディタや IDE を選ばず全てのエンジニアに馴染みやすいものを」という考えで CLI ベースのツールにすることを決定したそうです。
自分も現在 Claude Code を使ってみているのですが、使っているうちに「作業ディレクトリの扱いってどうなってるんだろう？」と気になることがありました。特に、ひとつのリポジトリの中で複数のアプリケーションを開発しているような構成で使う場合、Claude がどこまでのコードを見ているのか、どうやって作業範囲を限定できるのかが気になりました。
今回はそのあたりを少し踏み込んで調べてみたので、気づいたことをまとめておこうと思います。
AI と開発をする上での前提
AI に開発支援してもらうには「文脈の共有」が不可欠
AI ツールを開発に活用する場合、単にコードを読ませるだけでは不十分で、「どんな目的で書かれているのか」「どういうルールに沿っているのか」といった開発の文脈をうまく共有する必要があります。
これは Claude Code に限らず、あらゆる AI 開発支援ツールに共通する前提です。
プロンプトやルール、設計方針などを構造化された形で渡すことで、AI はより精度の高い支援を行えるようになります。
Claude Code の場合、この文脈共有のための手段として CLAUDE.md というメタ情報ファイルが用意されています。
このファイルにプロジェクトの背景や命名規則、ディレクトリ構成の意図などを書いておけば、REPL 起動時に Claude Code に読み込ませることができます。
Claude Code の作業ディレクトリの話
Claude Code はどの範囲のファイルを見るのか？
Claude Code はターミナルで claude コマンドを実行するだけで REPL セッションがスタートします。
公式ドキュメントの記述を確認すると、Claude Code の REPL は起動時に以下のような範囲でファイルを読み込むようです。
- REPL を起動したディレクトリと、そのすべてのサブディレクトリ
- 起動ディレクトリから上位（親）ディレクトリにある
CLAUDE.mdファイル - 明示的に指定した追加ディレクトリ（
--add-dirオプション）
つまり、REPL をどのディレクトリで起動するかによって、Claude Code の認識するコードベースが決まるということです。
どのディレクトリで REPL を起動すればいい？
1リポジトリ1アプリケーションの構成の場合は問題ないのですが、1リポジトリに複数アプリケーションがある場合、どこで REPL を起動すべきか悩むと思います。
開発したいアプリケーションのディレクトリで REPL を起動すれば、Claude Code が開発対象を正しく認識できる一方で、特定のルールを AI に認識してもらうには CLAUDE.md を各アプリケーションディレクトリに配置する必要があります。
※ 親ディレクトリの CLAUDE.md も読み込んでくれるからリポジトリの構成次第では個別作成は不要です。
似たような CLAUDE.md が量産されることのメリットはあまりないと思っていて、統一したいってなるとリポジトリルートに配置することを検討すると思います。
ただリポジトリルートで REPL を起動すると Claude Code の認識対象がリポジトリ全体になってしまって、開発したいアプリケーションに集中してくれないかもしれません。
どうにかして CLAUDE.md を1つに集約しつつ、開発対象のアプリケーションも絞れないかと思っていました。
実は REPL の中でディレクトリ移動できる
Claude Code の REPL 内では、通常のターミナルのように cd コマンドを使ってディレクトリを移動できます。ただし注意点として、これはREPL の作業ディレクトリが変わるというだけで、Claude Code が最初に読み込んだコードベースが変わるわけではありません。
一方で、cd によってファイルの操作やプレビューの対象ディレクトリが切り替わるため、Claude Code に作業範囲を意識させる手段としては有効です。
完全に他のアプリケーションの情報を完全に切り離すことはできないものの基本的には作業ディレクトリ内で作業をしてくれます。
試してみた
Claude Code の REPL 内でディレクトリ移動をして調査範囲が変わるかどうか試してみました。
今回実施したのは、複数の Python プロジェクトが入っているリポジトリのルートで REPL を起動し、どんな Python プロジェクトが存在するのか調査してもらいました。
そして特定の Python プロジェクトにディレクトリ移動して同じ質問をするを何を返してくれるのか調査しました。
(⑉°з°)-♡ claude
╭───────────────────────────────────────────────────────────╮
│ ✻ Welcome to Claude Code! │
│ │
│ /help for help, /status for your current setup │
│ │
│ cwd: /xxxxxxxxxxxxxxxxxxxxxxxxx/sample-repo │
╰───────────────────────────────────────────────────────────╯
What's new:
• Added --add-dir CLI argument for specifying additional working directories
• Added streaming input support without require -p flag
• Improved startup performance and session storage performance
• Added CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR environment variable to freeze working directory for bash commands
• Added detailed MCP server tools display (/mcp)
> あなたがいま認識できるPythonのアプリケーションを教えてください。全てのPythonアプリケーションは uv を使っていて、pyproject.toml がアプリケーションのルートディレクトリに配置されています。
⏺ Search(pattern: "**/pyproject.toml")
⎿ Found 10 files (ctrl+r to expand)
⏺ Read(pyproject.toml)
⎿ Read 82 lines (ctrl+r to expand)
⏺ Read(api/api1/pyproject.toml)
⎿ Read 31 lines (ctrl+r to expand)
⏺ Read(api/api2/pyproject.toml)
⎿ Read 24 lines (ctrl+r to expand)
⏺ Read(api/api3/pyproject.toml)
⎿ Read 25 lines (ctrl+r to expand)
⏺ Read(api/api4/pyproject.toml)
⎿ Read 26 lines (ctrl+r to expand)
⏺ Read(api/api5/pyproject.toml)
⎿ Read 29 lines (ctrl+r to expand)
⏺ Read(mcp/mcp1/pyproject.toml)
⎿ Read 25 lines (ctrl+r to expand)
⏺ Read(mcp/mcp2/pyproject.toml)
⎿ Read 23 lines (ctrl+r to expand)
⏺ Read(mcp/mcp3/pyproject.toml)
⎿ Read 23 lines (ctrl+r to expand)
⏺ Read(mcp/mcp4/pyproject.toml)
⎿ Read 23 lines (ctrl+r to expand)
⏺ 以下の9つのPythonアプリケーションを認識できます：
API (api/)
1. api1 - サンプルAPI 1 です
2. api2 - サンプルAPI 2 です
3. api3 - サンプルAPI 3 です
4. api4 - サンプルAPI 4 です
5. api5 - サンプルAPI 5 です
MCP (mcp/)
6. mcp1 - サンプル MCPツール1 です
7. mcp2 - サンプル MCPツール2 です
8. mcp3 - サンプル MCPツール3 です
9. mcp4 - サンプル MCPツール4 です
ルートには sample_apps というメインプロジェクトがあり、uvのワークスペース機能を使って上記全てのアプリケーションを管理しています。
> cd api/api1
⏺ Bash(cd /xxxxxxxxxxxxxxxxxxxxxxxxx/sample-repo/api/api1 && pwd)
⎿ /xxxxxxxxxxxxxxxxxxxxxxxxx/sample-repo/api/api1
⏺ List(.)
⎿ Listed 35 paths (ctrl+r to expand)
> あなたがいま認識できるPythonのアプリケーションを教えてください。全てのPythonアプリケーションは uv を使っていて、pyproject.toml がアプリケーションのルートディレクトリに配置されています。
⏺ Search(pattern: "**/pyproject.toml")
⎿ Found 1 file (ctrl+r to expand)
⏺ 現在のディレクトリ（api1）から認識できるPythonアプリケーションは：
api1 - 現在のディレクトリにあるアプリケーション
- LangChainとOpenAIを使用
- pyproject.tomlで管理されているuvプロジェクト
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ > │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✓ Update installed · Restart to applyディレクトリの移動をするとそのディレクトリで検索を実施してくれました！
結果として自分が採用した運用
この挙動を踏まえて、私が取っている運用は以下のようなものです：
- REPL はリポジトリのルートで起動する
- リポジトリルートに
CLAUDE.mdを1つ置いておく- プロジェクト全体の概要や開発方針などを記述
- REPL 起動後、開発対象のディレクトリに
cdで移動する- Claude Code にそのディレクトリ配下のコードを中心に扱ってほしいという意思表示
この運用であれば、リポジトリ全体に CLAUDE.md を分散させずに済みますし、Claude の文脈もルートの CLAUDE.md を通じて共有されるため、ある程度まとまったコンテキストを維持しながら作業できます。
まとめ
Claude Code の REPL は、起動時の作業ディレクトリとファイル読み込み範囲に密接な関係があります。
そのため、どこで REPL を起動するか、起動後にどのように作業ディレクトリを切り替えるかは、日々の開発体験に意外と大きく影響します。
今回調べてみて得られたポイントは以下のとおりです。
- Claude は REPL を起動したディレクトリ以下のコードをすべて読み込む
- 上位の
CLAUDE.mdも読み込むため、共通文脈はルートにまとめられる - セッション中に
cdで移動すれば、作業対象を切り替えることは可能 - 特定のアプリケーションだけに集中したい場合にも、この仕組みをうまく使えば対応できる
Claude を活用した開発の中で、作業範囲をどのように管理するかというのは、今後さらに重要になる部分だと感じました。
皆様の参考になりますと幸いです。
