CLAUDE.md as Hierarchical Project Memory
CoreApply the CLAUDE.md memory hierarchy · Difficulty 2/5
Explanation
What CLAUDE.md Is
`CLAUDE.md` is a special Markdown file that Claude Code automatically pulls into context as project memory. It is where a team puts architecture notes, conventions, common commands, and gotchas -- the standing context Claude should have on every turn without being re-told.
The Hierarchy
`CLAUDE.md` is hierarchical and merged from multiple locations, from broadest to most specific:
| Level | Location | Scope |
|---|---|---|
| Enterprise/system | managed centrally | organization-wide policy |
| User | ~/.claude/CLAUDE.md | personal defaults across all of a developer's projects |
| Project | ./CLAUDE.md (checked into the repo) | shared team conventions for that codebase |
| Subdirectory | deeper CLAUDE.md files in the tree | more specific guidance for that part of the code |
More specific files layer on top of broader ones -- a subdirectory `CLAUDE.md` refines, rather than replaces, the guidance inherited from the project, user, and enterprise levels.
Because the project-level `CLAUDE.md is committed to version control, the whole team shares identical guidance -- it is not each developer's individual preference file (that role belongs to the user-level file at ~/.claude/CLAUDE.md`).
Bootstrapping with /init
Run /init in a repo to bootstrap a starter `CLAUDE.md` from the existing codebase -- Claude Code analyzes the project and generates an initial file rather than the developer starting from a blank page.
Common exam traps
- **CLAUDE.md is memory/instructions loaded into context, not executable configuration.** Permissions, hooks, and tool allow/deny lists live in
settings.json, not `CLAUDE.md`. An exam item may offer "store permission rules in CLAUDE.md" as a plausible-sounding wrong answer. - Assuming the user-level `~/.claude/CLAUDE.md` is what a team shares -- it is personal, not committed to the repo; the project-level file is the team-shared one.
- Forgetting that subdirectory-level files layer on top of (not replace) broader levels.
Key Takeaways
- CLAUDE.md is auto-loaded project memory (conventions, commands, context), not executable configuration
- Four hierarchy levels, broadest to most specific: enterprise/system, user (~/.claude/CLAUDE.md), project (./CLAUDE.md), subdirectory
- More specific CLAUDE.md files layer on top of broader ones rather than replacing them
- Project-level CLAUDE.md is committed to version control so the whole team shares the same guidance
- /init bootstraps a starter CLAUDE.md from an existing codebase; permissions/hooks belong in settings.json, not CLAUDE.md
Glossary Terms
A markdown configuration file read by Claude Code at startup that injects persistent context, project conventions, and tool guidance into every session — without re-prompting. Claude Code supports CLAUDE.md files at the global, project-root, and subdirectory levels (see /glossary/path-specific-rules for the hierarchy). Uses @import for modular organization.
The Claude Code settings file that configures tool permissions, hook scripts, environment variables, and behavioral settings. Project-scoped (.claude/settings.json) checked into version control, or user-scoped (~/.claude/settings.json) for personal preferences. Hooks are defined here.
CLAUDE.md files placed in subdirectories that extend or refine root-level configuration for that directory subtree. Enables per-team ownership in monorepos: different rules for tests/, src/auth/, and docs/ without one massive root config. Files compose (stack) from root down to the current directory — they do not replace each other.
Related Concepts
Claude Code's Five Core Component Types
The five core component types are Rules, Skills, Commands, Agents, and Agent Memory
settings.json as the Deterministic Control Surface
settings.json (user: ~/.claude/settings.json, project: .claude/settings.json) configures tool permissions, hooks, env vars, model selection, and MCP servers