How CLAUDE.md File Hierarchy Works: User, Project, Subtree, Local

June 23, 2026 · How Claude Actually Works (part 16)

▶ Watch on YouTube & subscribe to The Stack Underflow

Every Claude Code project can carry instructions in CLAUDE.md files, but there is not just one file — there is a four-tier stack. Each tier targets a different scope, and when the same rule appears at multiple levels, the most specific one wins. Understanding the stack is the difference between rules that reliably fire and rules that silently do nothing.

This tutorial walks through each tier, explains exactly when a file loads, and shows how to diagnose the “why does Claude ignore my rule?” problems that trip up nearly everyone.

The one-sentence version: Claude merges CLAUDE.md rules from four tiers — user, project, subtree, and local — and the most specific applicable tier always overrides the more general one.

The Four Tiers

Think of the four files as a stack of cards, from most-general at the top to most-specific at the bottom:

~/.claude/CLAUDE.md          ← user    (your machine, every project)
<repo-root>/CLAUDE.md        ← project (checked in, whole team)
<repo-root>/frontend/CLAUDE.md ← subtree (scoped to a folder)
<repo-root>/CLAUDE.local.md  ← local   (git-ignored, just you)

User tier

Lives at ~/.claude/CLAUDE.md. It applies globally — every project you open on your machine inherits these rules. Use it for personal defaults that are always true regardless of which repo you are in: your preferred comment style, a cloud provider preference ("use Azure, never AWS"), or keybindings.

Project tier

Lives at CLAUDE.md in the repository root and is committed to version control. This is the team’s source of truth: workflow conventions, required scripts, linting rules, PR checklist items. Because it is checked in, every developer cloning the repo gets the same baseline. Put things here that are true for the whole project — "use pnpm and run pnpm ci before every commit".

Subtree tier

Lives inside any subdirectory — for example frontend/CLAUDE.md. It scopes its rules to files within that folder. Crucially, subtree files only load when the agent is actively editing files inside that subtree. The moment the agent touches a file under frontend/, the subtree card “lights up” and its rules are in scope. If the agent is working inside backend/ instead, the frontend/CLAUDE.md stays dark — it simply does not load.

This makes subtrees the right place for folder-specific technology context: "this folder is React and Tailwind" in frontend/CLAUDE.md ensures that rule never pollutes backend work.

Local tier

Lives at CLAUDE.local.md in the repo root and should be listed in .gitignore. This is your personal override file — experiments, debugging flags, a different formatter setting you want to test — anything you do not want to push. It applies to the whole repo but only for you.

How Precedence Works

When the same concern is addressed at multiple tiers, the resolution rule is simple:

The most specific applicable rule wins.

Consider this conflict:

• User says: indent 4 spaces
• Project says: indent 2 spaces
• Frontend subtree says: prettier decides

If the agent is editing a file inside frontend/, the subtree rule wins. The project and user rules are overridden — they fade. If the agent is in backend/, the subtree file never loads, so project wins over user.

Most general                         Most specific
  User  →  Project  →  Local  →  Subtree (when in scope)
             overrides ↑              always wins ↑

(Local sits between project and subtree in specificity. Subtree wins over local when both are in scope for the same folder.)

Placing Rules in the Right Tier

A useful heuristic: ask “how broadly is this rule true?”

• "use Azure, never AWS" — true for every project you touch. User tier.
• "use pnpm and run pnpm ci before commit" — true for this repo. Project tier.
• "this folder is React and Tailwind only" — true for one subdirectory. Subtree tier.
• "verbose debug logging while I investigate issue #412" — true only for you, temporarily. Local tier.

Getting this placement wrong is the most common reason a rule appears to be ignored.

Common Misconceptions

• “My rule is being ignored.” More often, it is in the wrong tier or in a subtree that never loaded. A rule in infra/CLAUDE.md does nothing when the agent is editing files under web/ — the infra subtree file simply is not in scope.

• “The project CLAUDE.md overrides user settings.” Yes, intentionally. The project file is more specific than the user file. This is a feature: team conventions should beat personal defaults on team code.

• “CLAUDE.local.md is the same as CLAUDE.md but secret.” Close, but not quite. It is git-ignored and personal, but it applies at the whole-repo level — it does not scope to a subtree. For folder-specific personal overrides you would need a subtree file, which would be checked in.

• “All CLAUDE.md files load at startup.” Subtree files do not. They load on demand, only when the agent works within their directory. If you add a rule to a subtree file and test it by running a command that only touches another directory, the rule will never fire.

Frequently Asked Questions

Can I have more than one subtree CLAUDE.md?

Yes. You can have a CLAUDE.md in any number of subdirectories. Each one loads independently when the agent operates inside that folder. A monorepo with frontend/, backend/, and infra/ can have a separate CLAUDE.md in each, with none of them polluting the others.

Does local (CLAUDE.local.md) override project or only user?

Local overrides both user and project, but is overridden by an in-scope subtree file. The ordering from least to most specific is: user → project → local → subtree (when loaded).

What happens if I put a subtree CLAUDE.md in the repo root?

That is just a project-level CLAUDE.md. The subtree scoping behavior applies because the file is inside a subdirectory. A file at the repo root applies to the whole project regardless of which directory the agent is in.

How does this interact with Claude’s skills, sub-agents, and hooks?

The instructions in whichever CLAUDE.md files are in scope at a given moment steer all of Claude’s behaviors — not just the main chat, but also the sub-agents spun up for parallel tasks and the hooks that run before or after tool calls. That is covered in the next videos in this series.

Where this fits in the series

This tutorial is part of How Claude Actually Works, a developer-focused course that starts from how Claude reads tokens and builds up through context windows, tool use, and agent orchestration. The CLAUDE.md hierarchy is the configuration layer that ties everything together — the rules you set here steer the skills, sub-agents, and hooks covered in the episodes that follow.

Browse all tutorials to see the full sequence.