A single CLAUDE.md at the root works for a single service. It breaks down when you have a frontend, a backend, a shared library, and a deployment configuration that each have their own rules, their own tech stacks, and their own contributors — all in the same repository.
Monorepos amplify every scaffolding problem. The AI working in the frontend package shouldn't need to know the PostgreSQL migration conventions. The AI working on the shared library shouldn't be reading deployment configuration. Context that's always fully loaded is context that competes for attention — the most important constraints get diluted by irrelevant ones.
The solution is a layered context architecture: a root CLAUDE.md that covers cross-cutting concerns, package-level context files that scope rules to where they apply, and a clear protocol for which files the AI loads depending on where it's working. This module builds that architecture.
A three-person team is building a SaaS platform in a monorepo. The structure is straightforward: a React frontend in packages/web, a Node.js API in packages/api, and a shared type library in packages/shared. They started with a single CLAUDE.md at the root and added rules as problems emerged.
Eight months in, the root CLAUDE.md is 340 lines long. It covers TypeScript conventions, PostgreSQL migration rules, Stripe integration patterns, React component architecture, API authentication middleware, deployment configuration, shared library versioning, and seven banned patterns from various incidents. It is technically comprehensive. It is practically useless.
When an AI session starts in the frontend, the first 800 tokens of context are database rules the frontend never touches. When a session starts in the shared library, the AI has Stripe integration details it will never use. The AI doesn't filter context by relevance — it loads everything and tries to honor everything, which means the most important constraints for a given session are buried in noise.
A senior developer on the team tried splitting the file into per-package CLAUDE.mds. Within a week, the root conventions had drifted out of sync with the package files. The TypeScript target version was specified differently in three places. Two packages had contradictory import rules. The fragmentation created new problems without solving the noise problem.
The team needs a layered architecture — not a flat monolith, not an uncoordinated fragment. They need clear ownership: what lives at the root, what lives in each package, and how the layers relate to each other.
The root CLAUDE.md and package CLAUDE.mds should have different jobs. Conflating them is what produces the 340-line monolith. Splitting them without a coordination principle produces the three contradictory files. The solution is clear ownership at each layer.
What belongs at the root: everything that is true regardless of which package you're working in. Naming conventions that apply everywhere. Security requirements that apply to all packages. The deployment configuration. The branch and commit strategy. The shared library versioning policy. Git conventions. If removing a rule from the root and putting it in just one package would create a gap, it belongs at the root.
What belongs in a package CLAUDE.md: everything specific to that package's tech stack, architecture, and constraints. The frontend's component architecture rules. The API's authentication middleware patterns. The shared library's semver constraints. Package-level files should open with an explicit inheritance note: "This file extends root CLAUDE.md. The root file's rules apply here unless explicitly overridden below." That single line prevents drift — any conflict is an explicit override, not an accident.
The architecture only works if there's a consistent protocol for which files are loaded. Write it once in the root CLAUDE.md: "When working in packages/web, load root CLAUDE.md + packages/web/CLAUDE.md. When working in packages/api, load root CLAUDE.md + packages/api/CLAUDE.md." This makes context loading predictable and auditable — you can always answer "what rules was the AI working under?" by reading two files.
The MEASURE function asks how risks are identified, quantified, and tracked. In context architecture, context overload is a measurable risk: when context is too broad, the AI's effective constraint set is smaller than its nominal constraint set. A layered architecture reduces context noise — making the AI's actual constraints more closely match the intended constraints. That's a MEASURE improvement.
MEASURE also requires that risks can be detected when they materialize. Contradictory rules across context files are a risk that must be detectable. The "extends root" convention makes contradictions explicit — they show up as intentional overrides or unintentional drift. Regular consistency audits across the root and package files are the MEASURE practice for context architecture.
A handoff spec describes which context files load for each package and why. It makes the architecture legible to anyone joining the project and auditable when something goes wrong. Write it once in the root CLAUDE.md under "Context Loading."
List every package, its primary tech stack, and its CLAUDE.md path. "packages/web — React 18, TypeScript — packages/web/CLAUDE.md". This is the map. If a new contributor needs to understand the context architecture, they read this section first.
State the protocol explicitly: "Always load root + package context. Never load a sibling package's context unless you are explicitly working on cross-package integration." The "never load sibling context" rule is the most important one — it prevents the API's rules from polluting a frontend session, which is exactly the noise problem the monolith created.
Define how package files may override root rules. Recommended: "Package files may refine root rules (adding detail, adding constraints) but may not contradict them. Any apparent contradiction is an error to be resolved, not honored." This keeps the root authoritative and prevents silent drift.
Add a sync audit trigger: "After any root CLAUDE.md change, verify consistency against all package CLAUDE.mds before committing." This is the consistency check that prevents the fragmentation failure mode from the scenario.