CLAUDE.md 階層設計 — プロジェクト・ユーザー・グローバルの三層構造
読了 10分 ＋ 実践 20分
CLAUDE.md は Claude Code がセッション開始時に最初に読む「起動契約」です。適切に設計された CLAUDE.md は、Claude Code に対してプロジェクトの制約・スタイル・参照すべきルールの所在を伝え、以降のすべての会話の基盤となります。このページでは、CLAUDE.md の三層構造の仕組みと、ハーネスとして機能するエントリーポイントの設計パターンを学びます。
仕組み: CLAUDE.md の三層
Section titled “仕組み: CLAUDE.md の三層”CLAUDE.md は一つのファイルではなく、スコープの異なる三つの層として機能します。Claude Code はセッション開始時にこれらをすべて読み込み、スコープの狭い層が優先されます。
| 層 | ファイルパス | 適用範囲 | 用途 |
|---|---|---|---|
| グローバル | ~/.claude/CLAUDE.md | すべてのプロジェクト | 個人のコーディングスタイル・言語設定 |
| プロジェクト | <project>/CLAUDE.md | そのプロジェクト全体 | 非交渉ルール・コマンド一覧・共有アセット参照 |
| サブディレクトリ | <project>/src/content/posts/CLAUDE.md | そのディレクトリ以下 | 特定ディレクトリ固有のルール |
読み込み順とマージルール
Section titled “読み込み順とマージルール”Claude Code は三層を以下の順序で読み込み、内容をマージします。
グローバル → プロジェクト → サブディレクトリ
（優先度: 低） （優先度: 高）同じ内容に関するルールが複数の層に存在する場合、スコープの狭い層（サブディレクトリ）が優先されます。たとえば、グローバルで「日本語で回答する」と設定し、特定プロジェクトのサブディレクトリで「英語で回答する」と設定した場合、そのディレクトリ内では英語が優先されます。
/memory コマンドで現在の状態を確認する
Section titled “/memory コマンドで現在の状態を確認する”Claude Code 内で /memory を実行すると、現在有効な CLAUDE.md の一覧とロード順を確認できます。
> /memory出力例:
Active memory files (in order of priority):
1. /Users/yourname/.claude/CLAUDE.md (global)
2. /Users/yourname/my-project/CLAUDE.md (project)
3. /Users/yourname/my-project/src/content/posts/CLAUDE.md (local)
Current directory: /Users/yourname/my-project💡 活用法: 設定変更後に予期しない動作が発生した場合、
/memoryでロードされているファイルを確認することがデバッグの第一歩です。
ベストプラクティス
Section titled “ベストプラクティス”1. CLAUDE.md は短く保つ
Section titled “1. CLAUDE.md は短く保つ”CLAUDE.md に長い仕様を直接書くと、ファイルが肥大化してメンテナンスが困難になります。長い仕様は shared/rules/・shared/skills/ などに分割し、CLAUDE.md からは参照のみを記述します。
悪い例（CLAUDE.md に直接すべてを書く）:
## ルール
- npm run build は本番デプロイを発火し得るため実行しない
- ユーザーの明示承認なしにビルドを実行しない
- UI、ナビゲーション、ルーティング、生成ホームページを変更しない
- 既存のコンテンツ構造を harness migration の一部として変更しない
- 日本語を source of truth とし...（以下100行続く）良い例（参照を記述する）:
## Non-Negotiable Rules
1. `npm run build` は本番デプロイを発火し得るため、ユーザーの明示承認なしに実行しない。詳細: `shared/rules/build-and-deploy.md`
2. UI・ナビゲーション・ルーティングを変更しない。詳細: `shared/rules/no-ui-regression.md`
3. 日本語を source of truth とする。詳細: `shared/rules/content-i18n.md`2. 共有アセットマップを使う
Section titled “2. 共有アセットマップを使う”どのニーズにどのファイルを参照すればよいかを表形式で明示します。Claude Code がタスクに応じて適切なファイルを参照できるようになります。
## Shared Asset Map
| Need | Canonical Source |
| --- | --- |
| Rules | `shared/rules/*.md` |
| Agents | `shared/agents/*.md` |
| Skills | `shared/skills/*/SKILL.md` |
| Commands | `shared/commands/*.md` |
| Workflows | `shared/workflow/*.md` |3. 非交渉ルールを明確なセクションで宣言する
Section titled “3. 非交渉ルールを明確なセクションで宣言する”「必ず守らなければならないルール」と「推奨事項」を分けて記述します。## Non-Negotiable Rules のような明確なセクション名を使うことで、Claude Code がルールの重要度を識別しやすくなります。
## Non-Negotiable Rules
1. `npm run build` はユーザーの明示承認なしに実行しない
2. secrets・credentials をコードに含めない
3. 既存の UI・ナビゲーション構造を変更しない4. コマンド一覧を表で管理する
Section titled “4. コマンド一覧を表で管理する”利用可能なコマンドとその制限を表形式で整理します。新しいメンバーがオンボーディングする際の参照としても機能します。
## Commands
| Command | Use | Rule |
| --- | --- | --- |
| `npm run dev` | local preview | 通常実行可 |
| `npm run build` | production build | ユーザー明示承認後のみ |
| `npm run test:content-review` | コンテンツレビューテストを実行 | 通常実行可 |このプロジェクトの CLAUDE.md を例として読む
Section titled “このプロジェクトの CLAUDE.md を例として読む”このプロジェクト（ai_learning_playground）の CLAUDE.md は、ハーネス型エントリーポイントの実装例です。主要なセクションを確認します。
Non-Negotiable Rules セクション: 各ルールが 1〜2 行で記述され、詳細は shared/rules/*.md に委譲されています。CLAUDE.md 自体はルールの「宣言」のみを持ち、「詳細」は別ファイルで管理します。
Commands セクション: | Command | Use | Rule | の三列テーブルで、コマンド・用途・制約の関係を一覧化しています。
Shared Asset Map セクション: | Need | Canonical Source | の形式で、ニーズとファイルパスの対応を明示しています。これにより Claude Code はタスクに応じて適切なファイルを自律的に参照できます。
Step 1: このプロジェクトの CLAUDE.md を確認する
Section titled “Step 1: このプロジェクトの CLAUDE.md を確認する”cat CLAUDE.md## Non-Negotiable Rules、## Commands、## Shared Asset Map の三セクションを確認します。
✅ 確認: 三つのセクションが存在し、各ルールが
shared/rules/への参照を持っていれば、ハーネス型の構造になっています。
Step 2: グローバル CLAUDE.md を作成する
Section titled “Step 2: グローバル CLAUDE.md を作成する”~/.claude/CLAUDE.md を作成して個人設定を追加します。このファイルはすべてのプロジェクトに適用されます。
mkdir -p ~/.claude~/.claude/CLAUDE.md の内容例:
# ユーザー設定 — Claude へのグローバル指示
## コミュニケーション
- 日本語で回答する
- 要点を先に述べる（Answer First）
- 実装前に不明点を確認する（推測で進めない）
## コーディングのデフォルト
- TypeScript を使う（型定義を省略しない）
- パッケージマネージャー: npm
- テスト: Vitest
## 出力形式
- コードブロックにはファイルパスをコメントで示す
- 複数ファイルを変更する場合は変更ファイル一覧を最初に提示する✅ 確認:
cat ~/.claude/CLAUDE.mdを実行してファイルの内容が表示されれば作成成功です。
Step 3: /memory で三層が認識されていることを確認する
Section titled “Step 3: /memory で三層が認識されていることを確認する”Claude Code を起動して /memory を実行します。
cd ai_learning_playground
claude> /memory出力に ~/.claude/CLAUDE.md（global）と ai_learning_playground/CLAUDE.md（project）の両方が表示されることを確認します。
✅ 確認:
Active memory filesに少なくとも二つのファイルが表示されていれば、グローバルとプロジェクトの二層が有効です。表示されない場合は Claude Code を再起動してください。
💡 何が起きているか: Claude Code は起動時にホームディレクトリとプロジェクトルートを走査して CLAUDE.md を自動検出します。手動でパスを指定する必要はありません。
Step 4: 新しいルールを追加して CLAUDE.md から参照する
Section titled “Step 4: 新しいルールを追加して CLAUDE.md から参照する”実際にルールファイルを作成し、CLAUDE.md から参照する流れを体験します。
まず、ルールファイルを作成します。
shared/rules/no-force-push.md の内容:
# no-force-push ルール
## 目的
リモートブランチへの強制プッシュを禁止し、チームメンバーの作業ロスを防ぐ。
## ルール
- `git push --force` を実行しない
- `git push --force-with-lease` も原則使わない
- やむを得ない場合はユーザーの明示的な承認を得てから実行する
## 例外
- 自分だけが使っているフィーチャーブランチで、リベース後に push し直す場合
- チームリーダーが明示的に承認した場合次に、プロジェクトの CLAUDE.md の ## Non-Negotiable Rules セクションに参照を追加します。
## Non-Negotiable Rules
...（既存のルール）...
7. `git push --force` は実行しない。詳細: `shared/rules/no-force-push.md`✅ 確認:
cat shared/rules/no-force-push.mdでファイルが確認でき、CLAUDE.mdの Non-Negotiable Rules セクションに参照行が追加されていれば完了です。
この時点のディレクトリ構造
Section titled “この時点のディレクトリ構造”プロジェクトルート/
├── CLAUDE.md # 更新: Non-Negotiable Rules に参照追加
├── shared/
│ └── rules/
│ ├── build-and-deploy.md
│ ├── content-i18n.md
│ └── no-force-push.md # 追加: 新しいルールファイル
└── ~/.claude/CLAUDE.md # 追加: グローバル個人設定（プロジェクト外）- CLAUDE.md はグローバル（
~/.claude/）・プロジェクト・サブディレクトリの三層に配置できる - 読み込み順はグローバル → プロジェクト → サブディレクトリで、スコープが狭い層が優先される
/memoryコマンドで現在有効な CLAUDE.md の一覧と優先順位を確認できる- CLAUDE.md は「宣言」のみ持ち、「詳細」は
shared/rules/などに委譲して短く保つ - 非交渉ルール・コマンド一覧・共有アセットマップの三セクション構成がハーネス型の基本形
次のステップ
Section titled “次のステップ”- Settings JSON 設計 — 権限・フック・MCP の設定方法
- Rules ファイル設計 — shared/rules/ の設計パターンと命名規則
よくある質問
Section titled “よくある質問”Q: CLAUDE.md に書いた内容はどのくらい確実に守られますか？
A: CLAUDE.md の内容はモデルへのコンテキストとして機能しますが、モデルが必ずその通りに動作する保証はありません。特に重要な制約（本番ビルドの禁止・機密ファイルの読み書き禁止など）は .claude/settings.json の permissions フィールドでシステムレベルで制御することを推奨します。
Q: CLAUDE.md のファイルサイズはどのくらいが適切ですか？
A: プロジェクトの CLAUDE.md は 100〜200 行以内に収めることを推奨します。それ以上になる場合は shared/rules/ への委譲が不十分な状態です。Claude Code がロードするコンテキストには上限があり、CLAUDE.md が長すぎると他の重要な情報を圧迫します。
Q: サブディレクトリの CLAUDE.md はいつ使うべきですか？
A: 特定のディレクトリのみに適用したいルールがある場合に使います。典型的な用途は、ブログ記事ディレクトリの文体ルール、テストディレクトリのコーディング規約、ドキュメントディレクトリの執筆ガイドラインなどです。プロジェクト全体に適用すべきルールをサブディレクトリの CLAUDE.md に書かないよう注意してください。
Q: グローバル CLAUDE.md とプロジェクト CLAUDE.md で同じ設定が衝突した場合はどうなりますか？
A: スコープの狭い層（プロジェクト CLAUDE.md）の設定が優先されます。ただし「優先」はルールを上書きする意味ではなく、Claude Code がどちらを参照するかの問題です。衝突する設定がある場合、明示的にプロジェクト CLAUDE.md で「このプロジェクトでは〇〇とする」と宣言することを推奨します。
このページの外部仕様・背景情報は、参考文献を参照してください。[1][2]
- Anthropic, Claude Code documentation
- Anthropic, Claude API documentation