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

Description and use

Splitting CLAUDE.md files in a monorepo reduces context usage and eliminates conflicting instructions, enabling each team to manage its own rules separately.

Problem

In a monorepo, a single CLAUDE.md file grows to hundreds of lines, consuming context and causing contradictory instructions across teams.

Outcome

Splitting CLAUDE.md files reduces context usage, isolates team rules, and prevents instruction conflicts, improving Claude’s reliability in monorepos.

Workflow

• Identify shared instructions and place them in root CLAUDE.md
• Create a directory CLAUDE.md for each team next to its code
• Add path‑scoped rules in .claude/rules/ with a paths field for cross‑cutting concerns
• Use @path imports sparingly, noting they do not reduce context cost
• Configure claudeMdExcludes in .claude/settings.local.json to skip irrelevant ancestor files
• Run /context to verify loaded files
• Run /doctor prompt‑audit to detect contradictions and drift
• Iterate: move procedures into skills and add rules from real mistakes

Evidence

A single CLAUDE.md file works well for one team in one repository. In a monorepo it slowly turns into a problem.

Source

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.

Source

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.

Source

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

Source

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

Source