Claude Code in a monorepo: how to split CLAUDE.md files across teams

A single CLAUDE.md file works well for one team in one repository. In a monorepo it slowly turns into a problem. The payments team adds its rules, the frontend team adds theirs, the platform team adds a deployment section, and soon every session starts by loading three hundred lines of instructions, most of which have nothing to do with the task.

That costs more than context space. The Claude Code documentation recommends keeping each CLAUDE.md under 200 lines, because longer files consume more context and reduce how reliably Claude follows them. It also warns that when two instructions contradict each other, Claude may pick one arbitrarily. A file that four teams edit is where contradictions come from.

The fix is to stop treating instructions as one file and start treating them like code: split by owner, loaded only where they apply.

How Claude Code finds instruction files

Three loading rules matter for a monorepo.

Files above you load at launch. Claude Code loads CLAUDE.md (and CLAUDE.local.md) from the directory you start it in and every directory above it. Start a session in services/payments/ and you get services/payments/CLAUDE.md, services/CLAUDE.md and the root CLAUDE.md. They are concatenated, not overridden, ordered from the root down, so the most specific file is read last.

Files below you load on demand. CLAUDE.md files in subdirectories don't load at launch. Each one loads the first time Claude reads, writes or edits a file in that subdirectory. Start at the root and touch only the frontend, and the payments instructions never enter the session.

Rules can be scoped to paths. Markdown files in .claude/rules/ can carry a paths field in their frontmatter. A scoped rule loads only when Claude works with a file that matches one of its patterns:

---
paths:
  - "services/payments/**/*.ts"
---

# Payments rules

- Amounts are integers in minor units. Never use floating point for money.
- Every new endpoint needs an idempotency key.

Rules without a paths field load at launch like the root CLAUDE.md.

A layout that scales

Put that together and a monorepo can look like this:

repo/
├── CLAUDE.md                     # shared: build, test, git workflow, ownership
├── .claude/
│   ├── settings.json             # shared permissions and hooks
│   └── rules/
│       ├── security.md           # no paths field: always loaded
│       └── migrations.md         # paths: "db/migrations/**"
├── apps/
│   └── web/
│       └── CLAUDE.md             # frontend team: components, styling, state
└── services/
    ├── payments/
    │   └── CLAUDE.md             # payments team: money handling, idempotency
    └── search/
        └── CLAUDE.md             # search team: indexing, query conventions

What goes where:

• Root CLAUDE.md: only what is true everywhere. How to install, build and test. The branch and commit conventions. A short map of the repository and which team owns which directory. Keep it short, because every session loads it.
• Directory CLAUDE.md files: each team's conventions, owned and reviewed by that team. Payments rules load when Claude touches payments code and stay out of the way otherwise.
• Path-scoped rules: concerns that cut across directories, such as database migrations, API contracts or test files, which no single team folder owns.
• Unscoped rules: the few things that must always be in context, such as security requirements. Use these sparingly; they cost context in every session.

Add the per-directory files to your CODEOWNERS so each team reviews changes to its own instructions, the same way it reviews its code.

Imports: tidy, but not cheaper

A CLAUDE.md can pull in other files with @path/to/file, for example @docs/git-workflow.md. Paths are relative to the file that contains the import, and imports can nest up to four levels deep.

Imports are useful for reusing a document that already exists rather than copying it. But the documentation is explicit that they don't reduce context cost: imported files load at launch along with the file that imports them. If the goal is a smaller session, use directory files and scoped rules, not imports.

When other teams' instructions get in the way

Because files above your working directory always load, someone working deep in the tree still gets every ancestor file. If an ancestor file carries instructions that don't apply to your work, the claudeMdExcludes setting skips files by path or glob pattern:

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

Patterns match absolute paths, which differ from one machine to the next, so the documentation's example puts this in .claude/settings.local.json, the uncommitted personal settings file. Treat it as a personal escape hatch. If many people are excluding the same file, the real fix is to move that content down into the directory it belongs to.

One thing can't be excluded: an organization's managed CLAUDE.md, deployed by IT to a fixed system path. Company-wide policy stays in force regardless of individual settings.

Repositories that already have AGENTS.md

Many monorepos already carry an AGENTS.md for other coding tools. Recent versions of Claude Code read AGENTS.md as project instructions, but by default only when there is no CLAUDE.md in your working directory or above it. Once you add a CLAUDE.md, Claude reads that instead.

If you want one source of truth, the simplest option is a CLAUDE.md that imports it: put @AGENTS.md in your CLAUDE.md and add any Claude-specific instructions below the import.

Keeping it healthy

• Check what actually loaded. Run /context in a session; the list under Memory files shows which instruction files are in context.
• Audit for drift. Newer Claude Code versions include /doctor prompt-audit, which looks for contradictions, references to files that no longer exist, and outdated instructions across your CLAUDE.md files, rules and skills, and proposes edits without changing anything until you approve.
• Move procedures out. A multi-step procedure that only matters sometimes, like cutting a release, belongs in a skill that loads when it is needed, not in a file that loads every session.
• Add rules from real mistakes. The documentation's advice for when to add something is practical: when Claude makes the same mistake twice, when code review catches something Claude should have known, or when a new teammate would need the same context.

The short version

One root file for what is true everywhere. One file per team, next to that team's code. Scoped rules for the concerns in between. Each file small enough that its owner can read the whole thing in a minute.

Most teams already have this knowledge, spread across READMEs, onboarding guides and wiki pages. That is what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds, using your own Anthropic API key. There's one free trial workspace, no card required, and our free templates are a good starting point for the root file.