CLAUDE.md Hierarchy Explained: User, Project, and Directory Scope in Claude Code

When I first began using Claude Code for my projects, I thought there was only one CLAUDE.md file. And I was very wrong, and when I learned about the differences, it completely changed my way of thinking about setting up my project's instructions. In today's post, I want to walk you through a Claude Code tutorial on the different CLAUDE.md files available for use in your projects. Let's get started.

Claude Code uses the CLAUDE.md file to provide context and instructions to the model about your project. It can be created manually inside of Claude Code (prompt: create a new CLAUDE.md file), or you can simply use the /init command to create a new one, or update an existing one.

Project Scope

By default, the CLAUDE.md file is created at the project root (this is called project scope) in .claude/CLAUDE.md (with a caveat - see footnote at the bottom of this post) or ./CLAUDE.md, which means it will be included in source control since this file would ideally contain instructions that should be shared with anyone else working on the project. Some examples of project-based prompts may include:

• Always run tests and ensure they all pass before merging code into the Dev branch.
• All API endpoints must have rate limiting.
• All environment-specific variables must come from .env files and should not be hardcoded into the project.

But there are two other levels of scope for the CLAUDE.md file. One is user scope and the other is directory scope.

User Scope

User scope is limited to the user, and can, and probably will, contain instructions and references that are applicable to the user across all their Claude Code projects. A user scope file is stored in ~/.claude/CLAUDE.md. But what are some examples of user scope instructions?

• Add my name, date, and title automatically to all commit messages.
• Prefer block comments over single-line comments.
• Keep code change explanations brief.

Those are all user preferences that don't affect the project output, and may not be considered part of the team coding standard, so they're stored in the user scope. The CLAUDE.md file in the user scope is not checked into version control.

Directory Scope

Directory scope is one of the more interesting possibilities with the CLAUDE.md file, because it allows you to have a CLAUDE.md file in every folder and subfolder in your project, each providing guidance. Suppose you have a folder in your project for documentation. You could include a CLAUDE.md file in that folder that includes the following prompts:

• All documentation should only include acronyms or jargon if they're defined in the same file.
• Ensure all documentation is written in markdown format instead of Word or plaintext.

This serves a couple of purposes. One, it allows you to keep your main CLAUDE.md file from being too bloated, and two, it allows you to segregate your prompts to make them specific to your individual project folders instead of adding every instruction to a single project-level CLAUDE.md. file.

Real World Scenario

Now think about a scenario for a minute where a new team member is onboarded. They clone a project being worked on by other members of the team, but realize they don't have the same coding standards that are followed by others. What is a situation where this could occur, and what is a way in which it can be fixed?

One plausible answer is that the coding standards are in each team member's user scope (~/.claude/CLAUDE.md) file instead of in the project scope (.claude/CLAUDE.md).

Conclusion

CLAUDE.md can be used in three different types of scope: user, project, and directory, each with their own uses. User scope can maintain your individual preferences across all your projects and is not added to source control. Project scope is added to source control and will be applied to anyone modifying the project. And directory scope is also checked into source control and is applied only to the contents of each directory rather than an entire project.

Footnote About Project Scope Location

The official Anthropic Claude Code documentation says Claude Code project scope include the CLAUDE.md file at .claude/CLAUDE.md or ./CLAUDE.md. When I ran the /init command, the CLAUDE.md was created in project root (e.g. ./CLAUDE.md), not in .claude/CLAUDE.md. I asked Claude Code for the reason behind it, and here's what it said. Before accepting what Claude Code says is true, it's worth investigating if things don't seem quite right.

If the screenshot is difficult to read, here is the pasted text from the session:

❯ Why did you create the CLAUDE.md in project root instead of in .claude/ ?                                                                                                           
● The /init command creates CLAUDE.md in the project root by design. That's the standard location — it's meant to be checked into version control so all collaborators  
  (and future Claude Code sessions) share the same project instructions.                                                                                                                                                                     
  The .claude/ directory serves a different purpose: it holds user-specific local settings and configuration, not project-level guidance.                               

  The hierarchy is roughly:                                                                                                                                             
  - ~/.claude/CLAUDE.md — global, user-level instructions across all projects                                                                                         
  - CLAUDE.md (project root) — project-level instructions, shared via version control                                                                                   
  - subdir/CLAUDE.md — directory-specific instructions for subdirectories

Preparing for the CCA exam? Start with our overview: What Is Anthropic's Claude Certified Architect Exam?