How Claude Code loads multiple CLAUDE.md files in subdirectories

6 min read.
Tags: AIClaude Code

You can have multiple CLAUDE.md files in one project, and Claude Code reads all of them. A file in a parent directory loads when the session starts, a file in a subdirectory loads once Claude touches a file in that folder, and none of them override each other. Everything gets concatenated into context.

Quick answer

repo/
├── CLAUDE.md                 # loads at launch
├── CLAUDE.local.md           # loads at launch, after CLAUDE.md, not committed
├── .claude/rules/testing.md  # loads at launch, or only for matching files with `paths`
└── apps/web/
    └── CLAUDE.md             # loads when Claude reads or edits a file in apps/web/

Start Claude Code in repo/ and you get the root files right away. The apps/web/CLAUDE.md file joins the context the first time Claude opens something under apps/web/. Start Claude Code inside apps/web/ and both files load at launch, because Claude Code also walks up to the parent directories.

To see which files are loaded right now, run this inside Claude Code and look under Memory files:

/context all

Which CLAUDE.md files load at startup

The memory docs list four scopes, loaded from broadest to most specific:

  1. Managed policy, set by an admin: /etc/claude-code/CLAUDE.md on Linux, /Library/Application Support/ClaudeCode/CLAUDE.md on macOS
  2. Your user file: ~/.claude/CLAUDE.md
  3. The project file: ./CLAUDE.md or ./.claude/CLAUDE.md
  4. The local file: ./CLAUDE.local.md

On top of that, Claude Code reads CLAUDE.md and CLAUDE.local.md from the working directory and every directory above it. Run it in foo/bar/ and it loads foo/CLAUDE.md and foo/bar/CLAUDE.md. The content goes in order from the filesystem root down to where you started, and inside one directory CLAUDE.local.md comes after CLAUDE.md.

CLAUDE.local.md is for your own notes on a shared repo, like a local database URL or a test account. Add it to .gitignore.

If you want a different ~/.claude/CLAUDE.md per account (work and personal), that's a separate config folder per account, covered in multiple Claude Code accounts with CLAUDE_CONFIG_DIR.

When does a subdirectory CLAUDE.md load?

Files below the working directory don't load at launch. Claude Code loads each one the first time Claude reads, writes, or edits a file in that subdirectory. A cat or head through Bash counts as a read too.

So in a monorepo, opening packages/api/src/server.ts pulls in packages/api/CLAUDE.md, and a session that never goes near packages/api/ never pays for those instructions.

That loading has been flaky in the past. Issue #2571 collected reports of nested CLAUDE.md files not loading, including one where they loaded in an interactive session but not with claude -p. A bot closed the issue for inactivity in February 2026 without a fix from the team. If a subdirectory file seems ignored, check /context all after Claude has opened a file in that folder instead of assuming.

What happens when two CLAUDE.md files disagree

Nothing overrides anything. The docs say all discovered files "are concatenated into context rather than overriding each other," and when two instructions contradict each other, "Claude may pick one arbitrarily."

A deeper file doesn't win just because it's more specific. If the root CLAUDE.md says "use npm" and apps/web/CLAUDE.md says "use pnpm," you have a coin flip. Write the subdirectory file as an addition to the root one ("in this package, also run pnpm test:e2e") and keep anything that differs out of the root file.

Split one big file with @ imports

A CLAUDE.md can pull in other files with @path:

# CLAUDE.md

See @README.md for the project overview.

## Workflow
- Git: @docs/git-workflow.md
- Personal setup: @~/.claude/my-project-notes.md

Relative paths resolve from the file that contains the import, not from where you started Claude Code. Imports can nest up to four hops. Paths inside backticks or code blocks aren't imported, so you can still mention a file without loading it.

The first time a project imports a file outside the working directory, Claude Code asks you to approve it. Decline and those imports stay off for that project.

Imports don't make anything cheaper. The imported file loads at launch together with the CLAUDE.md that references it, so this is for organizing the text, not for cutting context.

Load instructions only for matching files with .claude/rules

For instructions that only matter for some files, .claude/rules/ is the better tool. Each Markdown file there is one rule, and a paths list in the frontmatter limits when it loads:

---
paths:
  - "src/api/**/*.ts"
  - "src/**/*.{test,spec}.ts"
---

# API rules

- Validate request bodies with Zod.
- Every handler gets an integration test.

A rule without paths loads at launch like .claude/CLAUDE.md. A rule with paths loads only when Claude reads, writes, or edits a matching file. The globs are relative to the directory that holds .claude/.

Compared with a CLAUDE.md in a subdirectory, a rule can match by file type across the whole repo, which a folder can't. If the YAML is broken, Claude Code ignores the frontmatter and loads the rule everywhere. claude --debug shows the parse error.

User-level rules in ~/.claude/rules/ apply to every project on your machine and load before project rules.

Exclude CLAUDE.md files you don't want in a monorepo

In a big monorepo, other teams' CLAUDE.md files can end up in your context, especially the ones in parent directories. claudeMdExcludes skips them. Put it in .claude/settings.local.json so it only affects you:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

The patterns are globs matched against absolute paths. You can set this in user, project, local, or managed settings, and the arrays merge. A managed policy CLAUDE.md can't be excluded.

CLAUDE.md in directories added with --add-dir

claude --add-dir ../shared-config gives Claude access to another directory but doesn't load its CLAUDE.md by default. Set an environment variable to change that:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

With the variable set, Claude Code loads the added directory's CLAUDE.md, .claude/CLAUDE.md, CLAUDE.local.md, and its .claude/rules/ files that don't set paths.

Check what loaded

/context all lists every memory file in the current context. Run it after Claude has opened a file in a subdirectory and the nested CLAUDE.md shows up there.

/memory lists the CLAUDE.md locations for your user and project, including files that don't exist yet, and opens any of them in your editor.

How big each file should be

The docs suggest keeping each CLAUDE.md under 200 lines, because long files get followed less reliably. That's a good reason to split in the first place.

This blog's repo has a single 615-line CLAUDE.md at the root, covering the Next.js app, Prisma migrations, the content workflow, and the deploy setup. Using the rules above, that could become a short root file with commands and the checklist, apps/henggana-web-t3/CLAUDE.md for the app architecture, and a rule with paths: ["content/**"] for the writing workflow, so a session that only edits a blog post doesn't load the Prisma migration notes.

Final check

Multiple CLAUDE.md files all load and get concatenated: parent directories and ~/.claude/CLAUDE.md at launch, subdirectory files once Claude opens a file in that folder. Nothing overrides, so don't put conflicting instructions in two files. Use .claude/rules/ with paths for instructions that apply to file types, claudeMdExcludes to drop files you don't want, and /context all to see what's actually loaded.