CLAUDE.mdを階層化する方法|プロジェクト・フォルダごとに指示を分ける「マルチレベルCLAUDE.md」

Claude Codeでは、プロジェクトにCLAUDE.mdを配置することで、AIへ共通のルールを伝えられます。

小規模な開発なら、プロジェクト直下に1つ置くだけでも十分です。

しかし、開発が進むと「APIでは入力値を検証する」「データベースでは既存データを保護する」など、フォルダごとに異なるルールが必要になることがあります。

こうした場合に役立つのが、CLAUDE.mdの階層化(マルチレベルCLAUDE.md)です。

今回は、共通ルールとフォルダ固有のルールを分ける仕組みや、実際の配置方法を整理します。

目次

この記事で分かること

  • CLAUDE.mdを階層化する理由
  • 上位・下位フォルダのルールの読み込み方
  • 具体的なファイル配置と記載例
  • .claude/rules/との違い
  • 階層化するときの注意点

なぜCLAUDE.mdを階層化するのか?

CLAUDE.mdには、使用技術やテスト方法、ファイル変更時の注意事項などを記載できます。

しかし、プロジェクトが大きくなると、特定の機能にしか関係しないルールも増えてきます。

例えば、APIの入力値検証に関するルールは、画面デザインを変更するときには必要ないかもしれません。

すべてのルールを1つのCLAUDE.mdに書き続けると、ファイルが長くなり、管理もしにくくなります。

そこで、全体で守るルールは上位に、特定の場所で守るルールは下位に配置する方法を使います。

CLAUDE.mdはフォルダごとに配置できる

例えば、次のようなプロジェクトを考えます。

my-project/
├── CLAUDE.md
├── backend/
│   ├── CLAUDE.md
│   └── api/
├── frontend/
│   ├── CLAUDE.md
│   └── components/
└── tests/
    └── CLAUDE.md

それぞれの役割は次のとおりです。

配置場所記載する内容
ルートのCLAUDE.mdプロジェクト全体の共通ルール
backend/CLAUDE.mdバックエンド固有のルール
frontend/CLAUDE.md画面開発に関するルール
tests/CLAUDE.mdテスト作成時のルール

例えばルートには「変更後はテストを実行する」と記載します。

一方、backend/CLAUDE.mdには「API変更時は入力値検証を確認する」といった具体的なルールを記載します。

これにより、全体の方針を維持しながら、作業場所に応じた指示を追加できます。

上位と下位のCLAUDE.mdはどう読み込まれる?

Claude Codeは、作業ディレクトリとその上位階層にあるCLAUDE.mdを読み込みます。

また、下位フォルダにあるCLAUDE.mdは、そのフォルダ内のファイルを扱う際に必要に応じて読み込まれます。

つまり、下位のCLAUDE.mdが上位のルールを完全に置き換えるわけではありません。

例えば、バックエンドのファイルを扱う場合は、プロジェクト全体のルールに加え、バックエンド固有の指示も参照されます。

ただし、これはプログラミング言語の設定値のような厳密な上書き処理ではありません。

上位と下位で矛盾する指示を書かないことが重要です。

共通ルールと個別ルールの記載例

ルートのCLAUDE.mdには、次のような共通ルールを記載できます。

# Project Rules

- 既存機能との互換性を維持する
- コード変更後は関連テストを実行する
- 重要なデータを無断で削除しない

一方、backend/CLAUDE.mdには次のように記載します。

# Backend Rules

- APIの入力値を検証する
- エラーレスポンス形式を統一する
- DB構造を変更する場合は影響を確認する

これなら、ルートにバックエンド専用の細かなルールを大量に書く必要がありません。

大切なのは、同じルールを何度も記載するのではなく、それぞれのフォルダが担当する範囲を明確にすることです。

個人共通ルールも分けて管理できる

CLAUDE.mdは、プロジェクト内だけでなく、ユーザー単位でも配置できます。

例えば、次の場所です。

~/.claude/CLAUDE.md

ここには「回答は日本語を基本とする」など、複数のプロジェクトで共通して利用したい指示を記載できます。

一方、プロジェクト直下のCLAUDE.mdには、その開発に固有のルールを記載します。

また、チームで共有しない個人的な設定には、CLAUDE.local.mdを利用する方法もあります。

共有するルールと個人用のルールを分けることで、設定を管理しやすくなります。

.claude/rules/との違い

Claude Codeには、CLAUDE.mdを階層化する以外に、.claude/rules/で指示を管理する方法もあります。

例えば次のような構成です。

my-project/
├── CLAUDE.md
└── .claude/
    └── rules/
        ├── testing.md
        └── api.md

この方法では、テストやAPIなど、テーマ別にルールを整理できます。

さらに、ファイルの先頭でpathsを指定すると、対象ファイルに応じて適用するルールを設定できます。

---
paths:
  - "src/api/**/*.ts"
---

# API Rules

- 入力値を検証する
- エラー形式を統一する

※これはTypeScriptのAPIファイルを対象とする記載例です。

使い分けとしては、フォルダ単位でルールが異なるなら下位のCLAUDE.md、テーマ別やファイルパターン別に整理したいなら.claude/rules/が候補になります。

階層化するときの注意点

階層化は便利ですが、すべてのフォルダにCLAUDE.mdを配置すればよいわけではありません。

階層が増えすぎると、人間側もどのルールが適用されるのか把握しにくくなります。

また、上位では「A方式を使用する」、下位では「A方式を禁止する」と記載すれば、指示が矛盾してしまいます。

そのため、まずはルートのCLAUDE.mdだけで運用し、明確に異なるルールが必要になった段階で分割する方法がよいと思います。

設定後は、Claude Codeの/memoryなどで読み込まれるメモリファイルを確認できます。

ファイルを置くだけで終わらせず、実際に意図した指示が参照されるか確認することも大切です。

まとめ|必要な場所に必要なルールを配置する

マルチレベルCLAUDE.mdは、Claude Codeへ渡す指示をプロジェクトやフォルダごとに整理する仕組みです。

上位には共通ルール、下位には個別ルールを配置することで、1つのファイルへすべての情報を詰め込まずに済みます。

さらに.claude/rules/を使えば、テーマ別やファイルパターン別のルール管理もできます。

ただし、小規模なプロジェクトなら無理に階層化する必要はありません。

最初は1つのCLAUDE.mdから始め、開発の規模やルールの違いに応じて分割する。

このように段階的に管理方法を整えていくことが、Claude Codeを継続的に活用するうえで重要だと考えています。

※Claude Codeの読み込み仕様や設定方法は変更される場合があります。最新情報は公式ドキュメントを確認してください。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

この記事を書いた人

目次