CLAUDE.md: How Claude Code Thinks About Your Project
The one file that changes everything: project memory, conventions, and context strategy.
Claude Code loads CLAUDE.md at the start of every session to build its instruction context. This single file, combined with a layered system of global policies, user preferences, and path-specific rules, programs the agent’s prior beliefs about your repository. It tells the agent how your code is organized, which conventions to follow, and which commands to run.
A misplaced line in CLAUDE.md can cause the agent to ignore a critical security rule. That is because CLAUDE.md is not a suggestion. It is the primary mechanism that shapes the agent’s behavior by becoming part of the model’s system prompt, where instructions carry far more weight than user-level chat text.
How does CLAUDE.md get loaded into Claude Code?
The harness walks the directory tree from your working directory up to the root, loading every CLAUDE.md it finds. It also loads managed policies, user preferences, and local overrides in a fixed order before any user prompt is processed. The result is a single instruction stream that the model sees as its environment.
When you start Claude Code inside services/billing/api/, the loader looks for CLAUDE.md in that directory, then in services/billing/, then in services/, and finally at the repository root. Each file found is concatenated, with the most general content first and the most specific last. The root file describes the overall architecture. The deeper files add stack-specific constraints and local commands.
Subdirectory CLAUDE.md files are not loaded at startup. They are loaded on demand when the agent opens a file in that subtree. If you never touch services/billing/, its CLAUDE.md never enters the context. This scoping keeps the prompt lean and focused on the area you are actually working in.
The loading order, from broadest to most specific, looks like this:
Later instructions do not erase earlier ones. They all coexist in the prompt. However, the model tends to weigh later, more specific content more heavily when resolving conflicts, a pattern known as recency bias. That means a local override can effectively refine a global rule without contradiction, as long as the global rule is not a hard constraint.
The harness also respects an exclusion list. The claudeMdExcludes setting accepts glob patterns that prevent certain CLAUDE.md files from being loaded, even if they exist on disk. This lets you keep legacy or experimental files without polluting every session.
Why does the hierarchy matter for monorepos?
The layered loading lets you put general rules at the root and service-specific rules in subdirectories. Claude Code sees only the instructions that are relevant to the area you are working in. This keeps the effective prompt small and avoids overwhelming the model with irrelevant detail.
Consider a side project with a monorepo structure: services/billing/, services/frontend/, services/api/. The root CLAUDE.md describes the tech stacks, the shared library layout, and the rule that integration tests must pass before pushing. The services/billing/ CLAUDE.md adds billing domain concepts, payment processor dependencies, and the command to run billing tests. The services/api/ CLAUDE.md defines HTTP API (application programming interface) conventions and local run commands.
When you start Claude Code in the repository root, the agent sees only the root CLAUDE.md. It knows the big picture but not the billing specifics. When you navigate into services/billing/ and open a file there, the harness loads that directory’s CLAUDE.md, injecting the billing rules into the context. The agent now knows both the repo-wide rules and the billing-specific ones.
This design means you should scope your sessions to the directory you are actually working in. Running from the root every time forces the agent to work with only the high-level map, which can lead to it missing local conventions entirely. The documentation recommends treating each package as a module with its own CLAUDE.md, placed in the package’s directory. Starting sessions inside that package gives the agent a naturally scoped instruction set.
What happens when you import external documents?
The @import syntax inlines the full content of another file into the instruction context. A plain text reference like “See docs/style.md” does not load the file. The model reads the sentence but never sees the file’s contents. That is a common source of “Claude ignores our guidelines” reports.
The correct pattern is to write @docs/coding-style.md inside CLAUDE.md. The harness resolves the path relative to the project root, reads the file, and concatenates its content into the effective prompt. The model sees the imported text as if it had been written inline. Imported content behaves identically to inline content in terms of the model’s weight and priority.
Import resolution is recursive. An imported file can itself contain @import directives. The harness resolves all of them at session start. This lets you split a bulky CLAUDE.md into smaller, focused documents and include them wherever they are needed. The root CLAUDE.md can import a central coding style guide, while a service’s CLAUDE.md imports that service’s specific runbook.
The @import path can also use ~/ to reference the user’s home directory. This can bring in personal standards or machine-specific settings. However, the harness tracks whether external includes have been approved for the project. A configuration flag in ~/.claude.json may need to be set to allow imports from user-writable locations. The model never accesses the filesystem directly for imports. The harness handles all resolution.
How do path-specific rules interact with CLAUDE.md?
Rules in .claude/rules/ are defined with YAML frontmatter and glob patterns. They inject instructions only when the agent opens a file that matches the pattern. This is a conditional layer on top of the directory-based CLAUDE.md hierarchy.
For example, you can create a rule that applies to all *.test.tsx files. The frontmatter specifies the glob pattern. The rule’s body contains instructions for writing tests. When the agent opens a test file, the harness injects that rule into the context. When it works on a non-test file, the rule is absent. This avoids cluttering every session with test-specific guidance.
Path-specific rules complement CLAUDE.md. The root CLAUDE.md defines universal conventions. Directory CLAUDE.md files add package-level guidance. Path-specific rules add file-type-specific instructions that cut across directories. The agent’s behavior is a composite of all these layers, with the most specific rule winning when conflicts arise.
The key difference from directory CLAUDE.md is that path-specific rules are not tied to a directory location. They follow file types across the whole repository. This makes them ideal for conventions that should apply everywhere, like naming patterns for configuration files or security linting rules for YAML files.
Quick Reference
| Property | Value |
|---|---|
| Managed policy location (Linux) | /etc/claude-code/CLAUDE.md |
| Managed policy location (Windows) | C:\Program Files\ClaudeCode\CLAUDE.md |
| User global preferences | ~/.claude/CLAUDE.md |
| Project root CLAUDE.md | ./CLAUDE.md |
| Project .claude directory | ./.claude/CLAUDE.md |
| Project rules directory | ./.claude/rules/ |
| Local overrides (not committed) | ./CLAUDE.local.md |
| Import syntax | @path/to/file.md |
| Loading order | Managed policy → user global → project root → .claude → directory hierarchy → subdirectory on access → path-specific rules → local overrides |
| Exclusion configuration | claudeMdExcludes (glob patterns) |
Frequently Asked Questions
Q: Can I have multiple CLAUDE.md files in one repository?
Yes, and they stack. The root CLAUDE.md applies to the entire project. CLAUDE.md files in subdirectories apply only when you work in those directories. The harness loads them on demand when the agent descends into that subtree.
Q: What if a rule in a subdirectory CLAUDE.md contradicts the root?
Both are loaded, but the later, more specific content tends to take precedence due to recency bias. For critical constraints, avoid contradictions. Use the root file for nonnegotiable rules and the subdirectory files for additive context.
Q: Does @import work recursively?
Yes. Imported files can themselves contain @import directives. The harness resolves all imports at session start and concatenates the content into a single instruction stream. There is no documented depth limit.
Q: How do I exclude a CLAUDE.md from being loaded?
Use the claudeMdExcludes setting. It accepts glob patterns that specify which CLAUDE.md files to ignore. This is configured outside the CLAUDE.md files themselves, typically in the Claude Code configuration for the project.
Q: What is the difference between CLAUDE.md and .claude/CLAUDE.md?
./CLAUDE.md is the primary project-wide convention file. ./.claude/CLAUDE.md is an additional project-specific configuration that lives inside the .claude directory. Both are loaded. The .claude directory can also contain rules and other settings.
Test yourself
You create a CLAUDE.md in services/billing/ with the instruction: “Always run billing:tests before committing.” But when you ask Claude Code to commit changes, it never runs the tests. You started the session from the repository root. What is the most likely cause, and how would you fix it?
Answer: The services/billing/CLAUDE.md file is not loaded at session start because you started from the root. The harness only loads CLAUDE.md files from the working directory and its parents. It does not load subdirectory CLAUDE.md files until the agent opens a file inside that subdirectory. Since the commit operation does not require opening a file in services/billing/, the agent never sees the instruction. To fix this, either start your session from services/billing/ so that the file is loaded immediately, or move the instruction to the root CLAUDE.md or a path-specific rule that triggers on the files you typically edit. The latter ensures the agent sees the test requirement regardless of where you start the session.
If you want this kind of breakdown every week, how real systems actually work under the hood, subscribe to Internals Decoded at internalsdecoded.com. Next week, we open up Claude Code’s tool use and show exactly how the agent decides to run a shell command, read a file, or spawn a language server.