Centralize conventions that cross directory ownership

Learning objective

Prefer path-specific rules over directory-bound CLAUDE.md when convention scope crosses directories.

Core idea

Choose the instruction’s home from the scope of the convention and the team responsible for it. A package’s build and architecture guidance can stay beside that package in a directory CLAUDE.md. A testing convention that applies to files scattered across packages belongs in one .claude/rules/ file with paths selecting those files.

Both mechanisms can defer instructions until relevant work. The reason to prefer a path-scoped rule for dispersed tests is not that directory files always load globally. It is that the convention follows a file pattern across several directory owners. A central rule expresses that shared scope once instead of maintaining copies in every affected folder.

See 3.1.1 for the instruction-file hierarchy, 3.3.1 for conditional loading, and 3.3.2 for glob selection. This lesson uses those mechanisms to choose a maintainable division between repository-wide, directory-owned, and cross-directory guidance.

How it works

Distinguish the instruction’s home from its audience

Anthropic documents per-directory CLAUDE.md files for conventions maintained by directory owners and versioned alongside their code. In a monorepo, that can mean one file per package. In a single application, it can mean one file for src/db/ and another for src/api/.

Path-scoped rules keep the instruction file in central .claude/rules/ while the paths glob selects its audience. Anthropic recommends that choice when you want conventions in one place or when one rule applies to many scattered paths. The rule can therefore select test files under unrelated package directories without requiring a copy in each one.

The following comparison assumes the instruction files are available to the session and have not been excluded:

A root file with headings for each package still loads those sections together. Headings improve organization; they do not create a file-loading condition. Similarly, moving paragraphs into files imported from root CLAUDE.md with @path changes organization without reducing startup context: the imported files load with the importing file. See 3.1.2 for import mechanics.

Preserve a directory’s useful role

Claude Code loads CLAUDE.md files from the working directory and its ancestors at launch. It loads instruction files below the working directory on demand when Claude reads, writes, or edits another file in that subdirectory. Qualifying Bash reads also count. Starting directly inside a package therefore changes which directory instructions are present from launch.

A directory file is useful when its guidance applies broadly to that area’s code: how the package builds, which local architectural constraints it follows, or which package commands developers should run. Keeping that file beside the code lets the package owner review instruction changes with implementation changes.

It is a poor fit for a convention that applies only to tests distributed through many areas. Copying the same testing paragraph into each directory file gives each owner another version to maintain. It also exposes test-specific guidance when Claude accesses non-test files in those directories. A path-scoped rule can select the test suffix while the directory file supplies local package context.

Do not claim directory files are unable to contain testing guidance. They can, and a package-specific test convention may belong there. The deciding question is whether the instruction belongs to that area’s general context or to a shared file class spanning areas.

Combine shared and local guidance without conflicts

Centralization does not require moving every instruction into .claude/rules/. Keep repository-wide guidance at the root, directory-owned constraints beside their code, and one shared cross-directory rule for the convention that needs that scope. A test can then receive both package context and shared testing guidance.

The two instruction sets must agree. Claude Code concatenates discovered CLAUDE.md files into context rather than treating child files as overriding parents. Anthropic also warns that contradictory instructions can lead Claude to choose one arbitrarily. A deeper directory or a narrower-looking glob is not a reliable override mechanism for conflicting prose.

Review the central rule and local files together when moving a shared convention. Remove redundant copies of that shared instruction while preserving package-specific details. If two packages genuinely require different practices, give their instructions compatible scope and wording rather than declaring one universal convention that neither consistently follows.

Key distinctions and trade-offs

Central file versus global loading: A rule stored centrally can still load conditionally. A convention is not global merely because its instruction file lives at the repository root’s .claude/rules/.

Directory ownership versus scattered file scope: A directory CLAUDE.md keeps broad area guidance with its owners. A path rule follows the selected file class across owners. Choose according to the instruction’s audience, not a preference for one filename.

Path rules versus skills: A path-scoped rule loads when matching files are accessed. A skill loads when you invoke it or Claude determines it is relevant to your prompt. Use the rule when a file-type convention must enter context on matching access; see 3.2.6 for the skill-versus-CLAUDE.md decision.

Organization versus context reduction: Splitting a root file into imported documents helps maintenance but does not defer their loading. paths adds a loading condition; a topic heading or import does not.

One shared rule reduces duplicate text and gives cross-directory changes one review location. Local files preserve area ownership and make package context easy to maintain with the code. Combining the two is useful when shared file-type standards and local architectural constraints must both apply.

Architecture / decision scenario

A developer-productivity team uses Claude Code across packages/web/, packages/api/, and packages/shared/. Test files sit beside production files. Each package’s CLAUDE.md repeats the same test-naming and behavior-coverage guidance, but the copies have drifted. The web package also has its own rendering constraints, while the API package has its own persistence constraints.

The team moves the common testing guidance into .claude/rules/testing.md with paths: ["**/*.test.{ts,tsx}"]. It removes the duplicated common paragraphs from package files and keeps the rendering and persistence guidance with the appropriate directory owners. The root CLAUDE.md retains instructions intended for every task.

When Claude accesses packages/web/Button.test.tsx from a root session, the web directory instructions and matching test rule can both load. Access to packages/api/order.test.ts activates the same shared test convention together with the API context. The selector reaches both packages because it follows the test suffix, not one directory name.

A source-only change to packages/web/Button.tsx does not independently match the test pattern, while the web package’s general guidance remains relevant. A session launched inside packages/api/ loads packages/api/CLAUDE.md and the root CLAUDE.md at launch.

The team checks the remaining package instructions for contradictions with the central test rule. It does not rely on directory depth to settle competing prose. The resulting layout has one place to update the shared convention and retains separate ownership for facts that belong to each package.

Common exam traps

• Copying the same cross-directory convention into every folder that contains a test.
• Assuming every directory CLAUDE.md loads at launch from the repository root.
• Moving text into root imports and expecting conditional loading.
• Choosing a skill for a file-type convention that must load whenever matching files are opened.
• Treating central storage as equivalent to global scope.
• Removing useful package guidance because shared tests need one central rule.
• Assuming a child instruction file overrides conflicting parent or rule text.

Where the exam guide differs

What to remember

Keep directory-owned context beside the code and shared file-pattern conventions in one path-scoped rule. Both can load on demand; their audiences and ownership differ. Root headings and imports organize text without creating conditional scope. Ensure shared and local guidance agrees rather than relying on an assumed override order.

Knowledge check

References

• Anthropic, Monorepos and large repos
• Anthropic, How Claude remembers your project
• Anthropic, Claude Certified Architect – Foundations Exam Guide