ankuro.dev
← ブログ一覧に戻る
【Claude Code基本操作 #6】ディレクトリ構成とClaude Codeの関係
2026-03-17#Claude Code#AI#ディレクトリ

【Claude Code基本操作 #6】ディレクトリ構成とClaude Codeの関係

Claude Codeを使っていると、「なぜかファイルが見つからない」「CLAUDE.mdが効いていない」という状況に出くわすことがある。

原因のほとんどは起動場所とファイルの置き場所にある。

どこで起動するかが全てを決める

Claude Codeは起動したディレクトリをルートとして動く。ファイルの読み書き・検索はすべてそこを基点に行われる。

たとえば ~/my-project で起動すれば、Claude Codeは my-project/ 以下のファイルしか見えない。上の階層（~/ など）には原則アクセスしない。これはセキュリティ上の意図的な設計で、起動ディレクトリの外を勝手に書き換えられないようになっている。

# このディレクトリがClaude Codeの「世界」になる
cd ~/my-project
claude

「Claudeがファイルを見つけられない」「存在するはずのファイルを読んでくれない」という場面のほとんどは、プロジェクトのルートではなく別の場所で起動していることが原因だ。Claude自体の問題ではなく、起動場所の問題。

CLAUDE.mdの探し方と適用範囲

Claude Codeは起動時に複数の場所をチェックしてCLAUDE.mdを探す。

1. ~/.claude/CLAUDE.md        ← 全プロジェクト共通のルール
2. [起動ディレクトリ]/CLAUDE.md ← このプロジェクト専用のルール
3. サブディレクトリの CLAUDE.md ← そのディレクトリに移動したとき

重要なのは**「上書き」ではなく「追加読み込み」**という点だ。下のファイルが上のルールを完全に消すわけではなく、内容が重複した場合のみ下が優先される。

つまりホームに「コミットメッセージは日本語で」と書き、プロジェクトに「このコードはTypeScriptで書く」と書けば、両方が同時に有効になる。矛盾する指示があったときだけプロジェクト側が優先される。

ホームの CLAUDE.md（全体共通）

~/.claude/CLAUDE.md

「コミットメッセージは日本語」「出力は簡潔に」など、全プロジェクトで共通させたいルールを書く場所。個人の名前・文体・好みの操作スタイルなど「人に紐づく設定」はここに書く。プロジェクトのCLAUDE.mdはGitで共有されるため、個人設定を混ぜると他のメンバーに影響が出る。

プロジェクトルートの CLAUDE.md（プロジェクト専用）

~/my-project/CLAUDE.md

「このプロジェクトはNext.js + TypeScript」「テストはVitest」など、プロジェクト固有の情報を書く。Gitで管理してチームと共有するのが基本。ここに書いておけばプロジェクトに入るたびに同じ説明を繰り返さなくて済む。

サブディレクトリの CLAUDE.md（部分適用）

~/my-project/backend/CLAUDE.md

backend/ に移動したときだけ有効になる。フロントとバックで技術スタックが異なる場合など、一部のディレクトリだけ別のルールを適用したいときに使う。

よくある構成パターン

フロント・バック分離構成

my-project/
├── CLAUDE.md          ← 共通ルール（言語・コミットメッセージ等）
├── frontend/
│   ├── CLAUDE.md      ← Next.js固有のルール
│   └── src/
└── backend/
    ├── CLAUDE.md      ← FastAPI固有のルール
    └── app/

フロントを触るときは frontend/ で起動、バックを触るときは backend/ で起動する。

なぜこうするのか： フロントとバックでは技術スタックが全く異なる。フロントのCLAUDE.mdに「TypeScript・Tailwind・ESLint」を書き、バックのCLAUDE.mdに「Python・FastAPI・pytest」を書いておけば、起動場所を変えるだけで適切な前提知識がClaudeに伝わる。ルートのCLAUDE.mdに全部書こうとすると情報が多すぎてClaudeの判断が鈍くなる。

モノレポ構成

monorepo/
├── CLAUDE.md          ← 全体共通（Turborepo・pnpm等の説明）
├── apps/
│   ├── web/
│   │   └── CLAUDE.md  ← webアプリ固有
│   └── api/
│       └── CLAUDE.md  ← API固有
└── packages/
    └── ui/

モノレポではルートで起動して全体を把握させるか、サブアプリで起動して集中させるかを使い分ける。

なぜ使い分けるのか： 「apps/webのバグを直す」だけならルートから起動する必要はない。apps/web/ で起動すればコンテキストがそこに絞られ、余計なファイルを読まずに済む。トークン消費も抑えられる。一方、「packages/uiのコンポーネントがwebとapiの両方に影響する」ような変更はルートで起動して全体を見せた方が判断精度が上がる。

複数プロジェクト管理

~/
├── .claude/
│   └── CLAUDE.md      ← 全プロジェクト共通（名前・言語・スタイル等）
├── project-a/
│   └── CLAUDE.md
└── project-b/
    └── CLAUDE.md

なぜ ~/.claude/CLAUDE.md を使うのか： 自分の名前・好みの文体・コミットスタイルなど「人に紐づく設定」はプロジェクトに書く必要がない。~/.claude/CLAUDE.md に一度書けば全プロジェクトで有効になる。プロジェクトのCLAUDE.mdはGitで共有するため、個人設定を混ぜると他のメンバーに影響が出る。個人設定はホーム、プロジェクト設定はリポジトリで分離するのが原則。

よくある失敗パターン

① 上の階層から起動している

# NG：ホームディレクトリから起動してしまう
cd ~/
claude

なぜ悪いのか： Claude Codeはカレントディレクトリを「今いる場所」として文脈を理解する。ホームから起動するとどのプロジェクトの話をしているのかClaudeが判断しにくくなり、엉뚱한ファイルを触るリスクが増える。ファイルを指定するたびにフルパスが必要になり、指示も長くなる。

# OK：プロジェクト直下で起動する
cd ~/my-project
claude

② CLAUDE.mdをサブディレクトリに置いている

# NG：src/の中に置いてもルートから起動すると起動時に読まれない
my-project/src/CLAUDE.md

なぜ間違えやすいのか： 「プロジェクトのルールはsrc/に書けばいい」と直感的に思いがちだが、Claude Codeはあくまで「起動したディレクトリのCLAUDE.md」を最初に読む。src/CLAUDE.md はClaude Codeが src/ に入ったタイミングで読まれるが、起動時には読まれない。意図したルールが最初から効いていないと、セッション全体がズレた前提で進んでしまう。

# OK：起動ディレクトリのルートに置く
my-project/CLAUDE.md

③ VSCode Remote・SSH環境での起動場所を確認していない

VSCode Remote SSH経由で使う場合、ターミナルを開いたときのカレントディレクトリが ~ になっていることがある。そのまま claude を実行するとホームが起点になり、プロジェクトのCLAUDE.mdが読まれない。

なぜ起きやすいのか： ローカルで使うときはVSCodeがワークスペースのルートでターミナルを開くため気にならない。しかしSSH接続後のターミナルはデフォルトでホームに入るため、意識的に cd が必要になる。

# ターミナルを開いたら最初にここから始める
cd ~/my-project
claude

まとめ

  • Claude Codeは起動したディレクトリ以下しか見えない
  • CLAUDE.mdは ~/.claude/ → プロジェクトルート → サブディレクトリの順に追加で読み込まれる
  • 個人設定は ~/.claude/CLAUDE.md、プロジェクト設定はリポジトリに分ける
  • フロント・バック分離やモノレポではどこで起動するかを意識するだけで快適になる
  • 「効いていない」はだいたい起動場所かCLAUDE.mdの置き場所の問題

← 第5回：CLAUDE.mdとは？プロジェクトにルールを設定する ｜ 第7回：メモリ機能：会話をまたいで記憶させる方法 →

← ブログ一覧に戻る