Placing CLAUDE.md Files Across a Monorepo

Claude Code begins each session with a fresh context window, and CLAUDE.md files are one of the mechanisms that carry persistent instructions across sessions. In a monorepo that holds several projects or packages, where these files sit in the directory tree determines what context Claude Code reads and when. Anthropic’s official documentation at https://code.claude.com/docs/en/memory describes the exact loading behavior.

How Files Load Up and Down the Tree

Claude Code reads CLAUDE.md files by walking up the directory tree from the current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files. Running Claude Code in foo/bar/ loads instructions from foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.

All discovered files are concatenated into context rather than overriding each other. Content is ordered from the filesystem root down to the working directory, so instructions closer to where Claude Code was launched are read last. Within each directory, CLAUDE.local.md is appended after CLAUDE.md.

Subdirectories below the working directory behave differently. Claude Code also discovers CLAUDE.md and CLAUDE.local.md files in those subdirectories, but instead of loading them at launch, it includes them only when it reads files in those directories. This on-demand loading keeps a deeply nested monorepo from pulling every file into context at once.

Scope Determines Placement

The documentation lists several locations, each with a different scope, ordered from broadest to most specific. A project file at ./CLAUDE.md or ./.claude/CLAUDE.md holds team-shared instructions tracked in source control. A CLAUDE.local.md at the project root holds personal, gitignored preferences. User instructions live at ~/.claude/CLAUDE.md, and organization-wide managed policy files sit at platform-specific system locations.

For a monorepo, this means repository-wide standards belong in a root-level file, while package-specific or service-specific conventions can live in nested files that load only when Claude Code works inside those areas.

Keeping Files Small and Modular

The documentation recommends targeting under 200 lines per CLAUDE.md file, because longer files consume more context and can reduce how reliably Claude Code follows them. For larger projects, instructions can be split into topic files under .claude/rules/, where each file covers one topic. Rules can also be scoped to specific file paths using a paths field in YAML frontmatter, so they load into context only when Claude Code works with matching files.

CLAUDE.md files can also import additional files with @path/to/import syntax. Imported files expand into context at launch alongside the file that references them, with recursive imports allowed up to a maximum depth of four hops.

Excluding Files in Large Repos

In a large monorepo, ancestor CLAUDE.md files from other teams may get picked up even when they are not relevant. The claudeMdExcludes setting skips specific files by path or glob pattern, matched against absolute file paths. It can be configured at any settings layer, and arrays merge across layers. One exception holds firm: managed policy CLAUDE.md files cannot be excluded, so organization-wide instructions always apply.

Consistency Across Levels

Because files at multiple levels are concatenated, contradictions between them matter. The documentation warns that if two rules contradict each other, Claude Code may pick one arbitrarily, and it advises reviewing root files, nested files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions. Treating CLAUDE.md placement as part of the monorepo’s structure, rather than an afterthought, keeps that context coherent as the repository grows.