How Claude Code Discovers & Loads CLAUDE.md Files

CLAUDE.md isn’t limited to a single file at your repo root — Claude Code looks for it at multiple levels, and understanding that hierarchy is what makes monorepo and personal-preference setups actually work correctly.

The Three Levels

Project root — a CLAUDE.md at the root of your repository, the most common setup, checked into git and shared with the whole team. This is where team-wide conventions, commands, and architecture notes belong.

Subdirectory-level — additional CLAUDE.md files inside specific subdirectories, loaded in addition to the root file when you’re working inside that subdirectory. This is what makes monorepo setups practical: a packages/api/CLAUDE.md can describe API-specific conventions without polluting context for someone working purely in packages/frontend/. Covered in full in Monorepo & Multi-Directory CLAUDE.md Setups.

User-level (home directory) — a CLAUDE.md in your own home directory configuration (not checked into any repository), applying across every project you work on. This is where genuinely personal preferences belong — how verbose you like explanations, your preferred commit message style, habits that are about you, not about any specific codebase.

~/.claude/CLAUDE.md          ← personal preferences, applies everywhere
my-project/
├── CLAUDE.md                ← project-wide conventions, shared with the team
└── packages/
    └── api/
        └── CLAUDE.md         ← API-package-specific notes, loaded alongside the above when working here

How They Combine

These aren’t mutually exclusive alternatives — they layer. Working inside packages/api/ in the example above means Claude Code has the user-level file, the project root file, and the subdirectory file all in context simultaneously. This is additive, not a precedence override where a more specific file replaces a less specific one — each layer contributes its own scope of information.

This has a direct design implication: don’t repeat the same information at multiple levels. If the root CLAUDE.md already states “we use TypeScript strict mode,” a subdirectory file restating it adds nothing and wastes context budget — subdirectory files should contain only what’s genuinely specific to that subtree.

Personal Overrides Without Committing Them

For instructions that are true for you individually working in a shared repo, but shouldn’t be pushed to the whole team’s version of the file, Claude Code supports a CLAUDE.local.md pattern — a gitignored file alongside the committed CLAUDE.md that layers your own personal notes on top without affecting anyone else’s session. This is the right home for things like “I prefer verbose diffs” or environment quirks specific to your own machine, as opposed to genuine project conventions that belong in the shared file.

CLAUDE.local.md

Common Mistakes

Duplicating the same guidance across multiple levels “just to be safe” — this doesn’t make the instruction more likely to be followed, it just burns context budget redundantly on every session.

Putting personal preferences in the committed project-root file, forcing every teammate’s session to carry instructions that were only ever meant for one person — that belongs in CLAUDE.local.md or the user-level home-directory file instead.

Assuming a subdirectory file replaces the root file’s guidance. It doesn’t — both are in context together, so a subdirectory file should assume the root file’s conventions are already known and add only what’s different or additional.

Frequently Asked Questions

What happens if I have no CLAUDE.md at all? Claude Code works fine without one — it just relies entirely on what it can read from your codebase directly and what you say in conversation, without the head start a maintained file provides.

Does Claude Code re-read CLAUDE.md mid-session if I edit it? Generally it’s loaded once at session start; if you edit the file mid-session, starting a fresh session is the reliable way to have the agent pick up the changes.

Can subdirectory CLAUDE.md files exist several levels deep? Yes — the same discovery mechanism applies at whatever depth you’re actually working, not just one level below the root, which is what makes it scale to genuinely large monorepos.

Summary

CLAUDE.md’s file-hierarchy discovery — home directory, project root, and subdirectories — is additive, not overriding: every applicable level layers into context together. Design each level to hold only what’s genuinely scoped to it (personal habits at the user level, team-wide conventions at the root, subtree-specific notes in subdirectories) and avoid restating the same guidance at multiple levels.