🔍

Claude Code 実践検証 Day 2｜CLAUDE.mdの読み込み挙動、実際どうなってる？（前編）

に公開
AI
開発環境
Windows 11
Claude Code
tech

結論から言うと、CLAUDE.mdの読み込みには「永続メモリ」と「一時参照」の2種類があり、公式ドキュメントには書かれていない挙動がいくつか見つかりました。

今回はその検証結果をお伝えします。想定よりも発見が多かったので、前後編に分けてお届けします。

検証結果まとめ

検証項目 結果 補足
起動時の読み込み ✅ 正常 User / Project / Local の3種類が読み込まれる
サブディレクトリのCLAUDE.md ✅ 動的読み込み /memoryには表示されないが、ツール実行時に参照される
優先順位 ✅ 確認 CLAUDE.local.md > CLAUDE.md > User memory
日本語パス ✅ 問題なし Git Bash環境でも正常動作
@記法での読み込み ✅ 正常 過去のIssue報告は解消済み

予想通りだった部分もありますが、「サブディレクトリのCLAUDE.mdが動的に読み込まれる」という挙動は、正直最初気づかなくて少し混乱しました。

検証環境

OS: Windows 11 Pro
Shell: Git Bash (MINGW64)
Claude Code: v2.0.56
Model: Opus 4.5
IDE: Cursor

検証1：起動時の読み込み確認

まずは基本から。Claude Codeを起動して /memory コマンドを実行します。

やったこと

cd /c/development/projects/test-project
claude
> /memory

結果

Select memory to edit:
> 1. User memory        Saved in ~/.claude/CLAUDE.md
  2. Project memory     Saved in ./CLAUDE.md
  3. CLAUDE.local.md

3種類のメモリが表示されました。

わかったこと

  • User memory: ユーザー全体の設定（~/.claude/CLAUDE.md）
  • Project memory: プロジェクトルートのCLAUDE.md
  • CLAUDE.local.md: プロジェクトのローカル設定（.gitignore推奨）

ここまでは公式ドキュメント通り。問題なしです。

検証2：サブディレクトリのCLAUDE.mdはどうなる？

ここからが面白いところです。

テスト用に以下のような構成を用意しました。

test-project/
├── CLAUDE.md                    # ROOT-PRIORITY
├── CLAUDE.local.md              # LOCAL-PRIORITY
├── src/
│   ├── CLAUDE.md                # SRC-PRIORITY
│   └── feature/
│       ├── CLAUDE.md            # FEATURE-PRIORITY
│       └── sample.ts

やったこと

プロジェクトルートで起動した状態で、サブディレクトリのファイルを読んでみます。

> Read the file src/feature/sample.ts and tell me what configuration applies to it.

結果

Claude Codeは以下のように回答しました。

Applicable Configurations:

1. User-level (~/.claude/CLAUDE.md) - Global user configuration
2. Project Root (CLAUDE.md) - ROOT-PRIORITY marker
3. Project Local (CLAUDE.local.md) - LOCAL-PRIORITY marker
4. Src Directory (src/CLAUDE.md) - SRC-PRIORITY marker
5. Feature Directory (src/feature/CLAUDE.md) - FEATURE-PRIORITY marker

The most specific configuration comes from the feature directory.

あれ？と思って /memory を再度実行したんですが、表示は変わっていません。

Select memory to edit:
> 1. User memory        Saved in ~/.claude/CLAUDE.md
  2. Project memory     Saved in ./CLAUDE.md
  3. CLAUDE.local.md

わかったこと

ここで重要な発見がありました。

  1. サブディレクトリのCLAUDE.mdは、ツール実行時に動的に読み込まれる
  2. 読み込まれても /memory には追加されない
  3. 処理が終わったら保持されない（一時参照）

つまり、こういう構造になっているようです。

これ、公式ドキュメントには書いてないんですよね。気づくまで少し時間がかかりました。

検証3：優先順位の確認

CLAUDE.mdとCLAUDE.local.mdで矛盾する設定を書いた場合、どちらが優先されるか？

設定内容

  • CLAUDE.md: English language preference
  • CLAUDE.local.md: Japanese language preference

やったこと

> What language should you respond in based on your local configuration?

結果

ローカル設定（CLAUDE.local.md）が読み込まれています。日本語での回答を優先します。

CLAUDE.local.mdが優先されました。

わかったこと

優先順位は以下の通り。

優先度 ファイル
最高 対象ファイルに最も近いCLAUDE.md（サブディレクトリ）
高 CLAUDE.local.md
中 CLAUDE.md（プロジェクトルート）
低 ~/.claude/CLAUDE.md（ユーザー）

「より具体的な設定が優先される」という公式の説明と一致しています。

検証4：日本語パスの動作確認

Windows + Git Bash環境で、日本語パスがちゃんと動くか心配だったので検証しました。

やったこと

> Read src/日本語フォルダ/サンプル.ts

結果

Read(src\日本語フォルダ\サンプル.ts)
  Read 18 lines
  src\日本語フォルダ\CLAUDE.md

日本語フォルダのCLAUDE.mdが正常に読み込まれています。

問題なく動作しました。

ここまででわかったこと

  • Claude Code v2.0.56では、日本語パスは問題なく処理される
  • Git Bash環境でも文字化けなし
  • サブディレクトリの日本語CLAUDE.mdも正常に読み込まれる

公式ドキュメントとの比較

項目 公式の説明 実際の動作 差異
親ディレクトリから読み込み ○ 記載あり ○ 動作確認 なし
具体的な設定が優先 ○ 記載あり ○ 動作確認 なし
動的読み込み（遅延読み込み） × 記載なし ○ 動作確認 あり
/memoryに表示されない設定 × 記載なし ○ 存在する あり

私の環境では、このようになりました。引き続き、気にかけてみたいと思います。

ここまでのまとめ

  1. CLAUDE.mdには「永続メモリ」と「一時参照」の2種類がある - 起動時に読み込まれるものと、ツール実行時に動的に参照されるもの
  2. 優先順位は「より近い、より具体的」が優先 - CLAUDE.local.md > CLAUDE.md > User memory
  3. 日本語パスはWindows + Git Bashでも問題なし - v2.0.56で確認済み

正直、サブディレクトリのCLAUDE.mdの挙動は最初わからなくて、「あれ？設定したはずなのに反映されてない？」と困惑しました。同じところで悩んでいる人の参考になれば。

次回予告

今回は時間の都合で、以下の検証が残っています。

  • 疑問2：/initで生成されるCLAUDE.md、そのまま使っていいの？
  • 疑問4：Windows環境、結局どれを使えばいいの？
  • 疑問5：日本語の文字化け、どう対処する？

後編で検証結果をお伝えします。

シリーズ情報

  • シリーズ名：Claude Code 実践検証ガイド 2025
  • 検証環境：Windows 11 / Git Bash / Claude Code v2.0.56

次回：Day 1-2 後編「CLAUDE.md読み込み挙動の検証（後編）」

Discussion