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.

Источник