CLAUDE.md Hierarchy Design — The Three-Layer Structure of Project, User, and Global

CLAUDE.md is the “startup contract” that Claude Code reads first at the start of a session. A well-designed CLAUDE.md communicates the project’s constraints, style, and the location of rules to Claude Code, forming the foundation for all subsequent conversations. This page covers the three-layer structure of CLAUDE.md and the design patterns for an entry point that functions as a harness.

---

How It Works: The Three Layers of CLAUDE.md

CLAUDE.md does not consist of a single file — it functions as three layers with different scopes. Claude Code reads all of them at session start, and layers with a narrower scope take priority.

Layer	File Path	Scope	Purpose
Global	~/.claude/CLAUDE.md	All projects	Personal coding style, language settings
Project	<project>/CLAUDE.md	Entire project	Non-negotiable rules, command list, shared asset references
Subdirectory	<project>/src/content/posts/CLAUDE.md	That directory and below	Rules specific to that directory

Loading Order and Merge Rules

Claude Code loads the three layers in the following order and merges their contents.

Global → Project → Subdirectory
(priority: low)           (priority: high)

When rules about the same topic exist in multiple layers, the layer with the narrower scope (subdirectory) takes priority. For example, if you set “respond in Japanese” globally and “respond in English” in a specific project subdirectory, English takes priority within that directory.

Checking the Current State with the /memory Command

Running /memory inside Claude Code shows the list of currently active CLAUDE.md files and their loading order.

> /memory

Example output:

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

Tip: When unexpected behavior occurs after a configuration change, checking the loaded files with /memory is the first debugging step.

---

Best Practices

1. Keep CLAUDE.md Concise

Writing lengthy specifications directly in CLAUDE.md causes the file to become bloated and hard to maintain. Split lengthy specifications into shared/rules/, shared/skills/, and similar locations, and only write references in CLAUDE.md.

Bad example (writing everything directly in CLAUDE.md):

## Rules

- Do not run npm run build as it may trigger a production deployment
- Do not execute a build without explicit user approval
- Do not modify the UI, navigation, routing, or generated homepage
- Do not change the existing content structure as part of a harness migration
- Japanese is the source of truth...（continues for 100 more lines）

Good example (writing references):

## Non-Negotiable Rules

1. Do not run `npm run build` without explicit user approval, as it may trigger production deployment. Details: `shared/rules/build-and-deploy.md`
2. Do not modify UI, navigation, or routing. Details: `shared/rules/no-ui-regression.md`
3. Japanese is the source of truth. Details: `shared/rules/content-i18n.md`

2. Use a Shared Asset Map

Explicitly indicate which file should be referenced for each need in a table format. This allows Claude Code to reference the appropriate file depending on the task.

## 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. Declare Non-Negotiable Rules in a Clear Section

Write “rules that must always be followed” and “recommendations” separately. Using a clear section name such as ## Non-Negotiable Rules makes it easier for Claude Code to identify the importance of each rule.

## Non-Negotiable Rules

1. Do not run `npm run build` without explicit user approval
2. Do not include secrets or credentials in code
3. Do not modify the existing UI or navigation structure

4. Manage the Command List in a Table

Organize available commands and their constraints in a table format. This also serves as a reference for new members during onboarding.

## Commands

| Command | Use | Rule |
| --- | --- | --- |
| `npm run dev` | local preview | Freely executable |
| `npm run build` | production build | Only after explicit user approval |
| `npm run test:content-review` | run content-review tests | Freely executable |

---

Reading This Project’s CLAUDE.md as an Example

This project’s (ai_learning_playground) CLAUDE.md is an implementation example of a harness-style entry point. Review the main sections.

Non-Negotiable Rules section: Each rule is written in 1–2 lines, with details delegated to shared/rules/*.md. CLAUDE.md itself only holds the “declarations” of the rules; the “details” are managed in separate files.

Commands section: The | Command | Use | Rule | three-column table lists the relationships between commands, purposes, and constraints.

Shared Asset Map section: The | Need | Canonical Source | format explicitly shows the correspondence between needs and file paths. This allows Claude Code to autonomously reference the appropriate file depending on the task.

---

Hands-on Exercise

Step 1: Check This Project’s CLAUDE.md

cat CLAUDE.md

Confirm that the three sections ## Non-Negotiable Rules, ## Commands, and ## Shared Asset Map are present.

✅ Verify: If the three sections exist and each rule includes a reference to shared/rules/, the structure is harness-style.

Step 2: Create a Global CLAUDE.md

Create ~/.claude/CLAUDE.md and add personal settings. This file applies to all projects.

mkdir -p ~/.claude

Example content for ~/.claude/CLAUDE.md:

# User Settings — Global Instructions for Claude

## Communication

- Respond in English
- State the key point first (Answer First)
- Confirm unclear points before implementing (don't proceed on assumptions)

## Coding Defaults

- Use TypeScript (do not omit type definitions)
- Package manager: npm
- Testing: Vitest

## Output Format

- Include the file path as a comment in code blocks
- When modifying multiple files, present the list of changed files first

✅ Verify: Run cat ~/.claude/CLAUDE.md to confirm the file contents are displayed.

Step 3: Verify That Three Layers Are Recognized with /memory

Launch Claude Code and run /memory.

cd ai_learning_playground
claude

> /memory

Confirm that both ~/.claude/CLAUDE.md (global) and ai_learning_playground/CLAUDE.md (project) appear in the output.

✅ Verify: If at least two files appear under Active memory files, both the global and project layers are active. If they do not appear, restart Claude Code.

What is happening: Claude Code scans the home directory and project root at startup to automatically detect CLAUDE.md files. There is no need to specify paths manually.

Step 4: Add a New Rule and Reference It from CLAUDE.md

Experience the flow of creating a rule file and referencing it from CLAUDE.md.

First, create the rule file.

Content for shared/rules/no-force-push.md:

# no-force-push Rule

## Purpose

Prohibit forced pushes to remote branches to prevent work loss for team members.

## Rules

- Do not run `git push --force`
- In principle, do not use `git push --force-with-lease` either
- If unavoidable, obtain explicit user approval before running

## Exceptions

- When re-pushing to a feature branch that only you use, after a rebase
- When explicitly approved by the team lead

Then, add a reference to the project’s CLAUDE.md in the ## Non-Negotiable Rules section.

## Non-Negotiable Rules

...（existing rules）...
7. Do not run `git push --force`. Details: `shared/rules/no-force-push.md`

✅ Verify: Run cat shared/rules/no-force-push.md to confirm the file, and check that the reference line has been added to the Non-Negotiable Rules section of CLAUDE.md.

---

Directory Structure at This Point

project-root/
├── CLAUDE.md                    # Updated: reference added to Non-Negotiable Rules
├── shared/
│   └── rules/
│       ├── build-and-deploy.md
│       ├── content-i18n.md
│       └── no-force-push.md     # Added: new rule file
└── ~/.claude/CLAUDE.md          # Added: global personal settings (outside the project)

---

Summary

• CLAUDE.md can be placed in three layers: global (~/.claude/), project, and subdirectory
• The loading order is global → project → subdirectory, with narrower-scope layers taking priority
• Use the /memory command to check the list of currently active CLAUDE.md files and their priorities
• Keep CLAUDE.md holding only “declarations” and delegate “details” to shared/rules/ and similar locations to keep it concise
• The three-section structure of non-negotiable rules, command list, and shared asset map is the basic form of a harness-type entry point

---

Next Steps

• Settings JSON Design — How to configure permissions, hooks, and MCP
• Rules File Design — Design patterns and naming conventions for shared/rules/

---

Frequently Asked Questions

Q: How reliably will what is written in CLAUDE.md be followed?

A: The content of CLAUDE.md functions as context for the model, but there is no guarantee that the model will always behave accordingly. For particularly important constraints (prohibiting production builds, prohibiting reading and writing of confidential files, etc.), it is recommended to control them at the system level using the permissions field in .claude/settings.json.

Q: What is the appropriate file size for CLAUDE.md?

A: It is recommended to keep the project CLAUDE.md within 100–200 lines. If it exceeds that, delegation to shared/rules/ is insufficient. There is an upper limit to the context Claude Code loads, and if CLAUDE.md is too long, it crowds out other important information.

Q: When should I use a subdirectory CLAUDE.md?

A: Use it when there are rules you want to apply only to a specific directory. Typical use cases include writing style rules for a blog post directory, coding conventions for a test directory, and writing guidelines for a documentation directory. Be careful not to write rules that should apply to the entire project in a subdirectory CLAUDE.md.

Q: What happens when the global CLAUDE.md and the project CLAUDE.md have conflicting settings?

A: The settings in the layer with the narrower scope (project CLAUDE.md) take priority. However, “priority” is a matter of which one Claude Code refers to, not a matter of overwriting rules. If there are conflicting settings, it is recommended to explicitly declare “for this project, use X” in the project CLAUDE.md.