Directory CLAUDE.md scopes by location. Glob-pattern rules scope by file type. Neither is universally superior. The right choice depends on one question: are the conventions defined by where files live, or by what kind of files they are?
The Decision Framework
| Scope | Mechanism | Example |
|---|---|---|
| Files scattered by TYPE | Glob-pattern rules | Test files in 20+ directories |
| Files concentrated by LOCATION | Directory CLAUDE.md | Backend code in src/backend/ |
| All files | Root CLAUDE.md | Universal coding standards |
Scattered by type: Test files (*.test.ts) exist in every module directory. CSS modules (*.module.css) are throughout src/. Config files (*.yaml, *.json) appear in config/, src/config/, deploy/, .github/workflows/. A single glob-pattern rule (paths: ["**/*.test.ts"]) covers them all with one file.
Concentrated by location: A self-contained backend in src/backend/ with its own models, routes, and middleware. All backend files are here, no backend-specific files elsewhere. A directory CLAUDE.md in src/backend/ is simpler — no glob syntax needed.
Why Directory CLAUDE.md Fails for Scattered Files
A CSS conventions file placed in src/styles/CLAUDE.md loads when editing files in src/styles/. It does not load for src/components/Button.module.css or src/pages/Home.module.css. The conventions are about a file type, but the mechanism scopes by directory.
The fix: paths: ["**/*.module.css"] in a rules file. One file covers every CSS module in the project regardless of directory.
New directories make this worse. A project with src/api/v1/CLAUDE.md and src/api/v2/CLAUDE.md gets conventions for v1 and v2. When a developer creates src/api/v3/, no conventions load. The CLAUDE.md must be manually created — and it is forgotten 30% of the time.
A glob rule with paths: ["src/api/**/*"] auto-covers v3 the moment it exists. No manual setup, no forgetting.
The Duplication Problem at Scale
A project with testing conventions duplicated across 8 directory CLAUDE.md files tracked the maintenance cost over one quarter:
- Testing conventions changed 4 times
- Each change required updating 8 files (45 minutes per change)
- 3 of 4 changes had at least one directory missed
- Inconsistent test generation persisted 2-5 days before discovery
Quarterly cost: 3 hours of updates + 3 inconsistency incidents.
Migrating to a single .claude/rules/testing.md with paths: ["**/*.test.*"] eliminated all three problems. One file to update. One source of truth. Zero missed directories.
Over 18 months, one project grew from 3 directories with 3 CLAUDE.md files to 25 directories with 25 files. Audit found: 60% content duplication, 15% outdated files, 30% of new directories missing CLAUDE.md entirely. The structural fix — glob rules for shared conventions, directory CLAUDE.md only for truly directory-specific content — reduced 25 files to ~10 while eliminating duplication and auto-covering future directories.
Additive Loading: Everything Stacks
Claude Code configuration is additive. When editing src/backend/auth.test.ts:
- Root CLAUDE.md loads — universal standards apply to all files
src/backend/CLAUDE.mdloads — backend conventions apply to files insrc/backend/.claude/rules/testing.mdloads — testing conventions match*.test.*
All three load simultaneously. There is no priority system. No “most specific wins.” No override or cancellation. Each applicable configuration adds to the context.
This additive behavior is the foundation of the layered architecture: universal standards always present, area-specific conventions layered on, cross-cutting patterns added when the file matches.
When Directory CLAUDE.md Is the Right Choice
Glob-pattern rules are not strictly superior. For a bounded directory with no scattered files, a directory CLAUDE.md is simpler:
- No glob syntax to write
- No YAML frontmatter to maintain
- Conventions live next to the code they govern
- Equally effective when the scope genuinely matches a single directory tree
The test: would the conventions need to apply to files outside this directory? If no, directory CLAUDE.md is fine. If yes — if files of this type exist elsewhere in the project — use a glob-pattern rule.
The Enterprise Pattern: Three Layers
For large monorepos with concentrated team areas and scattered cross-cutting types:
Layer 1: Root CLAUDE.md — Universal standards (security basics, code quality). Small, always loaded.
Layer 2: Directory CLAUDE.md — Team-specific conventions. One per team in their concentrated area. No duplication between teams.
Layer 3: .claude/rules/ with paths — Cross-cutting types. Testing conventions (**/*.test.*), config conventions (**/*.config.*), migration conventions (**/migrations/**/*). One file per concern, covering all directories via globs.
This reduces a 45-file directory CLAUDE.md sprawl to ~15-20 well-scoped files, eliminates duplication, and auto-covers new directories as the project grows.
One-liner: Glob-pattern rules scope by file type across the whole tree; directory CLAUDE.md scopes by location — use each where its scope matches, and use both together for layered coverage.