The short version
Inheritance bugs in a CLAUDE.md tree show up about three months into a rollout, the moment a sub starts quietly contradicting its parent. Two-level hierarchy, locked. Read-only library for governance, separate read-write library for working files. Seven-check audit on every new file.
- Every level beyond two multiplies the "which file governs this" question - 2 levels has 1 conflict pair, 4 levels has 6
- The biggest OSS monorepos that publish a CLAUDE.md (Next.js, LangChain) ship one file each, root only
- The audit is small and the cleanup is smaller; doing this once a quarter holds the line
Six months into a Microsoft 365 Claude rollout I was asked to look at, the CLAUDE.md tree had grown to four levels. Company root. Division root. Team root. Sub-team root. Each layer inherited from the layer above via @-imports. Each redefined some bit of the parent’s rules. A few teams had pushed further and dropped CLAUDE.md files into individual project folders. Nobody could tell you, with a straight face, which rules were live in any given session.
The instinct to keep adding levels is hard to resist. Every team wants a place for its own context. Every sub-team wants the same. Three months in, the tree looks like an org chart, which feels right and is in fact wrong.
Conway’s Law warned about this back in 1968. Organisations design systems shaped like their own communication structures. So a CLAUDE.md tree drifts toward your reporting structure by default, and your reporting structure was never designed for inheritance.
The fix is small.
Why two levels and not three (or four)
The mental model goes like this. Hierarchies look free. They are not.
Every additional level adds a new pairwise question: when this level conflicts with that level, which one wins? With two levels the answer is one decision - parent versus sub. Three levels and you have three pairs. Four levels, six pairs. Five levels, ten. The pairs are not theoretical. They surface in support tickets a few weeks into the rollout, every time the model picks the wrong rule and a user wants to know why.
Look at the most-starred OSS monorepos that publish a CLAUDE.md today. Both Next.js (138K+ GitHub stars; dozens of npm packages plus Rust crates plus examples plus docs) and LangChain (128K+ stars; libs for core, classic, v1, plus partner integrations for OpenAI, Anthropic, Ollama, and a dozen others) ship exactly one CLAUDE.md. Root only. No team-level sub-files. The Next.js root is symlinked to AGENTS.md, so the same content reaches every AI coding agent the team uses without duplication.
That isn’t laziness. It’s the design discipline that comes from running a real monorepo. Push the depth into REFERENCE files that @-imports pull in on demand. Keep the tree shallow.
A two-level cap fits most real companies. Parent at the org library root holds firm-wide rules: glossary, products, AI policy, voice. Sub at the team subfolder holds team-specific overlays: per-team people, per-team active projects, per-team carve-outs from the parent rules. No grandchildren. Anything that looks like it wants a third level wants a REFERENCE file instead.
Split the libraries: read-only for rules, read-write for work
The second instinct that breaks a rollout is putting everything in one place. CLAUDE.md files next to agent code next to scratch markdown next to datasets, all in the same SharePoint library, all synced to every user’s OneDrive. If you have not yet sorted out where files live for AI on the document side, start there - the inheritance pattern in this post sits on top of that setup.
Microsoft’s own service description advises syncing no more than 300,000 files per OneDrive library before performance starts to suffer, and the 300K soft limit applies across every library a user syncs, not per library. A mid-size company that pours team scratch work, agent outputs, and datasets into the same library it uses for governance files will cross that line in the first quarter. OneDrive starts complaining. Sync conflicts pile up. The library that was meant to be tidy ends up messy.
The fix is to use two libraries.
Library A is for governance. Call it Documents/. It holds the parent CLAUDE.md, the team subs, and a REFERENCE/ folder full of supporting markdown the CLAUDE.md files import via @. It’s small (text only), permission-locked read-only at the library level, and synced via OneDrive to every Claude Code user so the parent walk finds it.
Library B is for working content. Call it Working/. Per-team read-write. Holds agent code, Python skills, datasets, working artifacts, outputs. Not synced. Users open it on demand via the SharePoint UI or map it as a network drive. The footprint here can grow without affecting OneDrive quotas at all.
SharePoint’s permissions inheritance model propagates the read-only flag from the library down to every CLAUDE.md and REFERENCE file inside it. Edit access lives with one designated editor per library. Everyone else reads. Sync conflict renames disappear because there is no second writer to conflict with.
On Google Workspace the equivalent pattern is two shared drives - one read-only for governance, one read-write for working files. On a pure git rollout, two repositories. The principle is the split. The platform is incidental.
Three loaders, one canonical source
A CLAUDE.md hierarchy is useless if nothing reads it. Three loaders pull from your two-level structure, one per Claude surface, and a companion post on this site walks through the full deployment plumbing across all four Claude surfaces (Code, Desktop, web, Cowork).
The short version goes like this. Claude Code walks parent directories from the working directory upward and concatenates every CLAUDE.md it finds, root-most first - so a user running Claude Code from inside a synced subfolder of Documents/ picks up parent plus team sub automatically. Claude Desktop and CLI-invoked Claude share that same path. Claude on the web and Cowork do not parent-walk anything - they read Organization Instructions you paste once at claude.ai/admin (the cap is 3,000 characters, so this is a condensed summary of the parent, not the parent file itself). For machines that need belt-and-suspenders coverage regardless of where the user runs Claude Code from, drop the parent file at the system-policy path via Intune, Jamf, or Group Policy. That copy can’t be overridden by user settings.
Three loaders. One canonical file. The library split sits behind all three.
Seven checks that keep this from rotting
A hierarchy left alone rots. Teams add a glossary that should have been a REFERENCE file. Subs quietly contradict the parent. A 200-line file balloons to 1,400 lines over six months. Nobody reads the long one. The model still loads all of it. Which is the bit that bites.
Turns out the audit is small. Seven checks. Run it on every new sub-CLAUDE.md before it lands. Run it on the parent quarterly.
| Check | What it verifies | Common failure mode |
|---|---|---|
| Scope clarity | The file declares what it governs (org-wide vs which team) in the first five lines | Reader cannot tell from the file what its role is |
| Length budget | Parent at or under 400 lines, sub at or under 200 lines. Anthropic recommends 200 as the strict target (Memory docs). Overflow moves into REFERENCE files imported via @ | One file holds the glossary, the playbook, and the policy in 2,000 lines |
| Single source of truth | Sub does not restate parent rules. Parent does not restate Anthropic platform docs or generic Claude knowledge | Same rule appears in three files; updates land in one and not the others |
| Inheritance respect | Conflicts with the parent are stated up front (“the Finance carve-out from rule X is…”) rather than introduced silently | Sub redefines a rule from the parent without flagging it; the model picks one arbitrarily |
| Read-only discipline | No employee names with judgment attached, no commercial info, no draft-quality content. Reads like a published policy, not a working doc | File contains “John is the manager who keeps asking us to bypass approval” |
| Practical reading test | A normal employee reading the file for 60 seconds can answer “what does Claude help with on my team?” and “what should I not ask Claude to do here?” | File is dense, abstract, or full of jargon nobody at the company uses |
| No-orphan rule | Every line is one of: a thing to do, a pointer to where to find more, or a guardrail. No aspirational filler | ”We value original thinking” sits in a file that is supposed to govern AI behaviour |
Failures concentrate at checks three and four. Most teams catch their own scope-clarity and length-budget problems on the first read. The harder ones are the inheritance bugs. A sub that quietly contradicts a parent rule. A single source of truth that diverged six months ago because two teams edited their copies in parallel. A REFERENCE file two team subs both define, with different content. Catching those needs the audit run by someone who is not the file’s owner. The owner reads what they meant to write. A fresh reader sees what is on the page.
A check that fails is a small edit. A check left unrun is the start of the rot.
If you already have a deeper hierarchy
The migration path is dull, and that’s the point. No clever moves. Three patterns turn up every time.
The first is the grandchild. A sub-sub-team CLAUDE.md three levels under the parent. Collapse it up. Whatever it covers either belongs in the team sub above it (most often the case) or, if it really is specific to a project, lives in a project-local REFERENCE file the team sub imports via @. Either way the third level disappears. The behaviour stays the same because the content reaches the model through the parent walk regardless of which file holds it.
The second is the bloated parent. A 4,000-line root CLAUDE.md that has become a one-file knowledge base. This is scope creep in its purest form. Extract the glossary into REFERENCE/glossary.md. Extract the product catalogue into REFERENCE/products.md. Extract the people directory into REFERENCE/people.md. The root file keeps the high-level rules and the @-imports. Each REFERENCE file is a separate document that loads when imported. The model’s context budget stays small. Adherence improves because the rules are no longer buried in a thousand lines of reference data.
The third is the silent carve-out. A team sub that quietly redefines a parent rule. The sub itself rarely calls attention to the redefinition - the team that wrote it usually believes their version is the right one and that the parent is wrong. Fix it one of two ways. Either make the conflict explicit (“Finance does X instead of the org rule for compliance reasons under SOC 2”) or delete the carve-out and update the parent if the team’s version is the better answer. Anything halfway is rubbish.
Most rollouts I help with hit all three patterns inside a quarter of accumulated drift. In building Tallyfy I have lived the same kind of thing in our internal docs - the fix is fiddly the first time and then takes about an hour a quarter.
Where to start: print the existing hierarchy as a tree. Count the levels. If the number is greater than two, you have your first piece of work. Run the seven-check audit on whatever you find. Lock at two levels from there.
If your team is rolling out CLAUDE.md across departments and the tree already looks like an org chart, this is the kind of architecture work Blue Sheen does. The discipline is small. The cleanup is smaller. Getting it right the first time saves the rebuild.
Amit Kothari is a managing partner at Blue Sheen, and writes at amitkoth.com about AI in operations and the work of getting it into real organisations.
