The Claude Code Configuration Hierarchy: User, Project, and Directory CLAUDE.md

What the Claude Code configuration hierarchy actually is

The Claude Code configuration hierarchy is the ordered set of CLAUDE.md files that Claude reads before it does any work in a session. Rather than one configuration file, Claude Code deliberately supports several locations, each scoped to a different audience: just you, your whole team, or one corner of a codebase. Knowing which file lives where, and what it can and cannot reach, is the foundation that every other Domain 3 topic builds on.

At session start, Claude assembles its instructions by collecting files from each scope. There are three you are expected to recall for the Claude Certified Architect exam. The user scope is a single file at ~/.claude/CLAUDE.md in your home folder. The project scope is a file committed inside the repository, written as either ./CLAUDE.md at the root or ./.claude/CLAUDE.md. The directory scope is any CLAUDE.md placed inside a subfolder of the project. Each answers a different question: what do I always want, what does this team always want, and what does this particular part of the codebase need.

The three scopes, one by one

Start with the user scope. The file at ~/.claude/CLAUDE.md follows you across every repository you open on that machine. It is the right home for habits that are about you, not about any one project: a preferred tone, a shortcut you always reach for, a personal rule like always running a linter before you call something finished. Nothing in this file is visible to anyone else, because it never leaves your computer.

Next is the project scope, and this is the workhorse of team configuration. A project file can sit at the repository root as ./CLAUDE.md, or tucked inside the project folder as ./.claude/CLAUDE.md; Claude Code treats both the same way. Because the file lives inside the repository, it is committed to git and arrives automatically for every developer who clones the project. Build commands, naming conventions, architectural decisions, and the workflows the whole team relies on all belong here.

Finally, the directory scope narrows things further. A CLAUDE.md placed inside a subfolder, say packages/api/CLAUDE.md, carries instructions that only make sense when Claude is working inside that part of the tree. In a monorepo this is invaluable: the frontend package and the infrastructure package can each carry conventions that would be noise if applied everywhere. These nested files do not all load up front; they are pulled in on demand when Claude actually reads a file in that subdirectory.

How the files load and combine

The mechanism is worth getting exactly right, because the exam likes to probe whether you think the files compete or cooperate. Claude Code walks up the directory tree from wherever you launched it, checking each folder for CLAUDE.md and CLAUDE.local.md, and it also loads your home-folder user file. Everything it finds above the working directory is loaded in full at launch. Everything it finds in subdirectories below is loaded later, the moment Claude opens a file down there.

Crucially, all of these discovered files are concatenated into context, not merged with one winning and the rest discarded. They stack. Content is ordered from the filesystem root downward toward your working directory, which means the instructions closest to where you started Claude are read last. That ordering matters only when two instructions genuinely contradict each other: faced with a real conflict, Claude tends to follow the more specific, later-read file. Most of the time there is no conflict at all, and the scopes simply add up into one combined set of guidance.

Why the hierarchy exists at all

It would be simpler to have one file. The hierarchy exists because the three audiences have genuinely different needs, and collapsing them creates problems. If everything went in a single shared file, your personal stylistic preferences would be forced onto teammates who never asked for them. If everything went in a personal file, the team would have no shared baseline and each developer would effectively run a different assistant. The split lets personal, team, and locality-specific guidance each live where it belongs without stepping on the others.

This is also why the hierarchy is the root knowledge point of task statement 3.1 and a prerequisite for almost everything else in the domain. Once you can place an instruction at the correct scope, the downstream topics follow naturally: what gets shared through version control, how to keep a large configuration modular, how to debug which files are actually loaded, and how to design a configuration strategy for an entire team. None of those make sense until the three scopes are clear.

Reading the hierarchy on a real project

Picture a developer opening Claude Code inside packages/api of a monorepo. Three things load before any prompt is answered. The user file ~/.claude/CLAUDE.md brings that developer's personal preferences. The project file ./CLAUDE.md at the repository root brings the team-wide standards. And packages/api/CLAUDE.md brings the API-specific conventions, because that is the directory Claude started in. If Claude later reads a file in packages/web, the web package's own CLAUDE.md joins the context at that moment. The developer never copied anything; the hierarchy did the routing.

Common misreadings to avoid

The two failure modes below both come from misremembering how the scopes relate. Internalise the corrections and most hierarchy questions become straightforward.

Where CLAUDE.local.md and managed policy fit

The three scopes you must recall, user, project, and directory, cover the everyday cases, but two further locations round out the full picture and occasionally surface in scenarios. The first is CLAUDE.local.md, a file you place at the project root for personal, project-specific notes. It loads alongside the project CLAUDE.md and is treated the same way, but the intended pattern is to add it to .gitignore so it never ships to teammates. Think of it as a personal annex to the project scope: physically inside the repository, yet private by convention rather than by location.

The second is the managed policy location, used by organisations that need instructions to apply on every machine regardless of individual settings. On Linux that file lives at /etc/claude-code/CLAUDE.md, with equivalent paths on macOS and Windows. It loads before the user and project files and cannot be excluded by a single developer's own configuration, which is precisely what makes it suitable for company-wide security or compliance reminders. You will rarely configure this yourself, but recognising it as the broadest and most authoritative rung helps when a question describes behaviour that seems to arrive from somewhere above the project.

Neither of these changes the core mental model. They are additional steps on the same ladder, broadest at the top and most specific at the bottom, and the same concatenation-with-conflict-resolution rule governs all of them. When you map an instruction to a scope, you are really choosing how far it should reach: one machine, one developer across every project, one team, one directory, or one whole organisation.

Instructions versus settings: two parallel hierarchies

A trap worth separating cleanly is that CLAUDE.md is not the only thing Claude Code scopes by location. Settings live in their own settings.json files and have their own user, project, and local scopes that superficially resemble the CLAUDE.md ladder. The two systems are distinct in purpose. The CLAUDE.md files carry behavioural instructions, the guidance Claude reads and tends to follow, while settings.json files carry configuration, the permissions, tool behaviour, and policy the client enforces directly. Conflating the instruction files with the settings files is one of the most common conceptual errors this knowledge point exists to head off.

Keep the model simple. When a question is about what Claude should do, naming conventions, build commands, architectural context, you are in CLAUDE.md territory and the three-scope instruction hierarchy applies. When a question is about what Claude is permitted to do, which command may run or which path may be written, you are in settings.json territory, which carries its own scopes and its own precedence order. Both are hierarchical and both are organised by audience, but one shapes behaviour and the other enforces policy, and they never substitute for each other.

A reliable way to remember the scopes

A simple framing keeps the hierarchy straight under exam pressure: name the audience first, then pick the file. If the instruction is about you and should follow you everywhere, it is the user file. If it is about the team and the codebase as a whole, it is the project file. If it only matters inside one corner of the tree, it is a directory file. Because the scopes concatenate rather than compete, you are never really choosing which single file should win; you are choosing which audiences ought to see the instruction at all, and trusting Claude to combine the layers it finds.

That audience-first habit is also what later lets you answer the harder, scenario-style questions quickly. Almost every configuration problem in this domain is, underneath the surface detail, a question about audience that has been dressed up as a question about behaviour. Recognising that a description of 'inconsistent output' is usually a description of mismatched scopes is the single most transferable skill this knowledge point gives you, and it is why the locations are worth committing firmly to memory before you move on.

How this shows up on the exam

Domain 3 (Claude Code Configuration & Workflows) carries 20 percent of the exam, and this knowledge point sits at the very base of it. Questions at the remember level rarely ask you to recite a path in the abstract. Instead they describe a concrete situation, a monorepo, a new hire, a rule that seems to apply in one folder but not another, and ask which scope is responsible. The reliable way to answer is to map each instruction to its audience: is this about me, my team, or one directory? Get the scope right and the rest of the question usually answers itself. From here, the natural next step is understanding exactly which of these scopes travels through version control, which is where the team-consistency story really begins.

Watch and learn

Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.

Official · Anthropic AcademyOpen full lesson in Academy

Adding context

Why watch: Giving Claude Code project context through CLAUDE.md is the configuration mechanism whose scoping hierarchy this KP defines.

More videos for this concept

Adding context

Claude Code in Action · 5:14

Master ALL 7 Levels of Claude Code Memory

Mark Kashef

Claude Code's Memory System: The Full Guide (Most Developers Miss 90% of This)

DIY Smart Code

How to Use CLAUDE.md in Claude Code in 5 Minutes

GritAI Studio