サブディレクトリの CLAUDE.md はいつ読み込まれるか:モノレポでの置き方と確認方法

モノレポで packages/api/CLAUDE.md を置いたのに効いていない気がする、逆に無関係なパッケージのルールまで適用されている。こうした混乱は、サブディレクトリの CLAUDE.md が いつ読み込まれるかを知ると解消します。

結論として、起動時に読まれるのは「カレントディレクトリから上」の CLAUDE.md で、「カレントより下」のものは Claude がそのディレクトリのファイルを扱うときに読み込まれます。

読み込みの 2 つのタイミング

CLAUDE.md の位置	読み込まれるタイミング
カレントディレクトリとその上位(リポジトリのルートまで)	セッション開始時
~/.claude/CLAUDE.md(ユーザー用)	セッション開始時
カレントより下のサブディレクトリ	Claude がそのディレクトリ内のファイルを読む・編集するとき

たとえばリポジトリのルートで claude を起動すると、ルートの CLAUDE.md は最初から読まれますが、packages/api/CLAUDE.md は Claude が packages/api/ 配下のファイルに触れた時点で読み込まれます。逆に packages/api/ の中で起動すれば、packages/api/CLAUDE.md とルートの CLAUDE.md の両方が最初から読まれます。

モノレポでの分担例

リポジトリ/
├── CLAUDE.md                 # 全体方針、共通コマンド、全パッケージ共通の規約
├── packages/
│   ├── api/
│   │   └── CLAUDE.md         # API 固有: DB マイグレーションの手順、禁止事項
│   └── web/
│       └── CLAUDE.md         # フロント固有: コンポーネント規約、スタイルの方針
└── docs/

ルートには「どのパッケージでも守ること」だけを書き、パッケージ固有の情報は各パッケージに置きます。こうすると、web の作業中に api のマイグレーション手順がコンテキストを占有することがなくなります。

ルートの CLAUDE.md の例:

## 共通コマンド
- 全体のテスト: `pnpm -r test`
- Lint: `pnpm lint`

## 共通規約
- パッケージ間の依存は `packages/shared` 経由。相互 import は禁止
- 各パッケージの詳細は packages/*/CLAUDE.md を参照

packages/api/CLAUDE.md の例:

## このパッケージ
- テスト: `pnpm --filter api test`(Docker の DB が必要: `docker compose up db`)
- マイグレーションは `prisma/migrations/` に新規ファイルを追加する。既存ファイルは変更しない

確認する方法

対話中に /memory を実行すると、その時点で読み込まれているメモリファイルの一覧が出ます。サブディレクトリの CLAUDE.md は、該当ディレクトリのファイルを扱う前は一覧に出ないのが正常です。「packages/api/src/user.ts を読んで」と頼んだあとに再度 /memory を実行し、packages/api/CLAUDE.md が増えていれば読み込みは機能しています。

読み込まれないときの見直し点

• ファイル名: CLAUDE.md は大文字小文字を含めて正確に。claude.md や Claude.md は読まれない環境があります
• 場所: packages/api/.claude/CLAUDE.md のように .claude/ の中に置く形式も使えますが、両方に置くと二重に読まれます。どちらか一方にします
• まだ触れていない: 下位の CLAUDE.md は「そのディレクトリのファイルに触れたとき」に読まれます。先に読ませたい場合は、指示の最初に「packages/api/CLAUDE.md を読んでから始めて」と伝えるか、packages/api/ で起動します
• 矛盾する指示: ルートとサブディレクトリで逆の指示があると挙動が不安定になります。サブディレクトリには追加情報だけを書き、ルートの規約を上書きしないようにします

関連する記事

CLAUDE.md の 3 階層(ユーザー・プロジェクト・個人)と書くべき内容は、親記事の CLAUDE.md の書き方 を参照してください。長い規約を分けたい場合は @ インポート記法 も使えます。コンテキストの節約全般は Claude Code のコンテキスト管理 にまとめています。

まとめ

• 起動時に読まれるのはカレントディレクトリから上の CLAUDE.md。下位のものはそのディレクトリのファイルを扱うときに読まれる
• モノレポではルートに共通事項、各パッケージに固有事項を置く
• /memory で読み込み状況を確認できる。触れる前に読ませたければ指示で明示する
• サブディレクトリには追加情報だけを書き、ルートと矛盾させない