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

说明与用途

在单体仓库中拆分 CLAUDE.md 文件可降低上下文消耗并消除冲突指令，使每个团队能够单独管理其规则。

问题

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

结果

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

工作流

• 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

证据

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

来源

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.

来源

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.

来源

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

来源

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

来源