- In short
- Claude Code glob patterns are the wildcard expressions in a rule's paths frontmatter, such as **/*.test.tsx, that match files anywhere in a repository. They let one rule govern files scattered across many directories, whereas a directory-level CLAUDE.md applies only to the single folder it sits in and the subdirectories beneath it.
How Claude Code glob patterns differ from a directory CLAUDE.md
Claude Code glob patterns and directory-level CLAUDE.md files solve the same problem from opposite directions. A glob pattern scopes a convention by the shape of a file path: a rule whose paths frontmatter says "**/*.test.tsx" reaches every test file in the repository, no matter which of fifty directories it lives in. A directory-level CLAUDE.md scopes a convention by location: drop a CLAUDE.md into packages/billing/ and it governs that folder and the files beneath it, and nothing else. Deciding between them is the analyse-level skill this knowledge point assesses, because the right answer depends entirely on how the files you want to govern are distributed.
The two are not interchangeable, and the exam likes to present a case where one is clearly correct and the other quietly fails. If your convention is "all React test files use this assertion style," the governed files share a shape but live everywhere, so a glob is the natural fit. If your convention is "everything in the payments package follows PCI logging rules," the governed files share a location, so a directory CLAUDE.md sitting in that package is the cleaner expression. The analysis always starts with the same question: are these files defined by what they are, or by where they are?
- Directory-level CLAUDE.md
- A CLAUDE.md file placed in a subdirectory. Claude loads it on demand when it reads a file in that directory, and its scope is the directory and its subtree. It is the location-based counterpart to a path-specific rule, which scopes by glob across the whole repository.
What a directory-level CLAUDE.md actually scopes to
It is worth being precise about how nested CLAUDE.md files load, because the mechanics shape when they are the right tool. Claude walks up the directory tree from the working directory and loads CLAUDE.md files along that path in full at launch. Files in subdirectories below the working directory are handled differently: they are pulled into context on demand when Claude reads a file inside them. So a CLAUDE.md in packages/billing/ becomes active when Claude touches something under packages/billing/, and its influence stops at that subtree boundary.
That boundary is the whole point of the directory approach, and also its limit. A directory CLAUDE.md cannot reach a file two packages over, because that file is outside its subtree. It does not care what kind of file it is governing, only where the file sits. This makes it excellent for package-local conventions and useless for conventions that follow a file type across the codebase.
How multiple CLAUDE.md files combine: concatenation, not override
Because Claude walks up the tree and can load several CLAUDE.md files at once, it helps to know how they merge. They are concatenated, not overridden: a project-root CLAUDE.md and a nested one each contribute their full text to context, and a more specific file does not replace a more general one the way a subclass overrides a method. Claude reads them in order from the filesystem root down toward the working directory, so instructions nearer the launch directory are appended later, and within a single directory a CLAUDE.local.md is appended after its CLAUDE.md.
The consequence to internalise is that conflicting instructions accumulate rather than cancel. If the root says "use tabs" and a package CLAUDE.md says "use spaces," both end up in context and Claude has to reconcile them on its own. A nested CLAUDE.md therefore narrows where its extra instructions apply, but it never silently supersedes what an ancestor file already said, which is a frequent and costly misreading when teams treat the hierarchy as an override chain.
Where glob patterns win: cross-cutting conventions
Now consider the conventions that do not respect folder boundaries. Test files, API route handlers, database migrations, and infrastructure manifests all tend to be scattered: a test file lives next to the component it tests, an API handler lives in whichever feature owns it. A convention about "all test files" or "all API handlers" therefore touches dozens of directories at once. A glob pattern matches on path shape, so a single rule with "**/*.test.tsx" or "**/routers/**" blankets every one of those files regardless of where it sits.
To express the same thing with directory CLAUDE.md files, you would have to place an identical CLAUDE.md in every directory that happens to contain a test, then keep all those copies in sync as the codebase grows. That is exactly the situation where the glob is not merely more convenient but structurally correct: the convention is defined by file shape, and only a shape-matching mechanism can capture it without duplication.
The maintenance cost of the directory approach
The duplication is not just an aesthetic problem; it is a correctness and drift problem. Every copied CLAUDE.md is a place the convention can fall out of step. Add a new feature folder and you have to remember to add the CLAUDE.md too, or its tests silently escape the convention. Update the assertion style and you must edit dozens of files instead of one. The official guidance even calls for periodically reviewing CLAUDE.md and rules files to remove conflicting instructions, and the more copies you maintain, the more surface area there is for two of them to disagree.
A single glob rule collapses all of that into one reviewable file. There is one source of truth, one place to edit, and no chance that a new directory is missed, because the glob matches by shape and a new test file matches automatically. The contrast is starkest when the codebase is actively growing: every sprint that adds feature folders adds maintenance burden to the directory approach and zero burden to the glob, so the gap between the two widens precisely as the project scales. That asymptotic difference, constant effort for the glob versus linear effort for the directory copies, is the quantitative heart of the analysis, and it is why "fewer files today" understates the real advantage. When you analyse a scenario and see "this convention applies to files of type X wherever they live," the maintenance argument is what tips it decisively toward the glob.
Worked example
A large frontend codebase has test files (*.test.tsx) sitting beside the components they cover, spread across more than fifty feature directories. The team wants Claude to apply one consistent set of testing conventions to every test file. An engineer proposes adding a CLAUDE.md with the testing rules into each feature directory.
Analyse the distribution first. The governed files are defined by their shape, the .test.tsx suffix, not by their location; they are deliberately scattered next to their components. That single observation predicts that a location-based mechanism will fight the grain of the problem.
Trace the proposed directory approach to its consequences. Fifty-plus directories means fifty-plus copies of the same CLAUDE.md. Each copy loads only when Claude reads a file in its own folder, so coverage depends on every folder having a current copy. The first time someone adds a new feature directory without the file, its tests drift. The first time the assertion style changes, fifty edits must land together or the codebase holds two conflicting conventions at once. The approach technically works on day one and decays from there.
Now the glob alternative. One file, .claude/rules/testing.md, with frontmatter paths: ["**/*.test.tsx"], expresses the convention once. It matches every test file in the repo today and every test file added tomorrow, with no per-folder bookkeeping. When the convention changes, you edit a single file. This is the canonical case the task statement is built on: a cross-cutting, shape-defined convention belongs in a path-specific rule with a glob, and the directory-CLAUDE.md proposal should be rejected precisely because the files are not organised by directory. The directory mechanism would only have been right if the convention were genuinely local to one package.
Common misreadings to avoid
Both errors below come from reaching for the wrong scoping mechanism rather than from misunderstanding either one in isolation.
Misconception
A directory-level CLAUDE.md and a glob rule are basically two syntaxes for the same thing, so either works for any convention.
What's actually true
Misconception
To apply a convention to every test file, you must put a CLAUDE.md in each directory that contains tests.
What's actually true
Sharing and reuse: another axis the glob wins on
There is a second, less obvious reason cross-cutting conventions favour the rule mechanism: shareability. The .claude/rules/ directory supports symlinks, so a team can maintain one canonical rule set in a shared location and link it into many repositories, and Claude resolves those symlinks and loads the rules normally, even detecting and handling circular links gracefully. That makes a glob rule a natural unit of reuse: the same testing.md can govern test files across several projects from a single source of truth. A directory-level CLAUDE.md offers no comparable story, because its meaning is bound to its position in one repository's tree; you cannot meaningfully share "the rules for the billing folder" with a project that has no billing folder.
For an analyse-level question this adds a tie-breaker. When a convention is not only scattered by type within a repo but is also meant to apply consistently across multiple repos, the symlink-friendly rule file is the only mechanism that expresses both at once. The directory CLAUDE.md is inherently local; the glob rule is portable.
When the directory approach is genuinely the better call
It would be a mistake to read all of this as "globs always win." The analysis cuts both ways, and a directory-level CLAUDE.md is the cleaner expression whenever a convention is truly local to one part of the tree. A payments package with money-handling and audit-logging rules that apply only inside it is better served by a CLAUDE.md sitting in that package: the rules load on demand when Claude works there, the scope is self-documenting from the file's location, and nobody outside that subtree carries instructions that do not concern them. Forcing such a package-local convention into a repo-wide glob would either over-match or require a contrived pattern that mirrors the directory anyway.
Monorepos sharpen the point. When ancestor CLAUDE.md files from other teams get pulled into your sessions, the claudeMdExcludes setting lets you skip specific files or whole rules directories by path or glob, keeping unrelated teams' conventions out of your context. The judgement the exam rewards is reading the distribution honestly: shape-scattered conventions to a glob rule, location-bound conventions to a directory CLAUDE.md, and a willingness to exclude what does not apply.
How this shows up on the exam
Because this knowledge point is assessed at the analyse level, questions hand you a distribution of files and a proposed mechanism and ask you to judge the fit, or to choose between the two approaches. The tell is always how the target files are organised. Scattered by file type across many folders points to a glob; concentrated in one package points to a directory CLAUDE.md. The classic trap is the test-conventions scenario above, where creating a CLAUDE.md per directory is offered as a plausible-sounding answer and is wrong because it duplicates a shape-based convention into location-based files. If you can articulate why the glob is structurally correct, not just that it is fewer files, you are answering at the level the exam wants.
A team needs Claude to follow the same database-migration conventions for every migration file. Migrations are named like 20260607_add_users.sql and live in a single, dedicated db/migrations/ directory; no migrations exist anywhere else in the repo. Which scoping mechanism fits best, and why?
People also ask
When should I use glob patterns instead of a directory CLAUDE.md?
Are nested CLAUDE.md files loaded automatically?
Can one rule apply across many directories in Claude Code?
Watch and learn
Official Anthropic Academy lessons first, then hand-picked walkthroughs. Videos load only when you press play.
How to Use CLAUDE.md in Claude Code in 5 Minutes
Why watch: Explains how CLAUDE.md files load by directory and where instructions should live, grounding the contrast between directory-scoped files and broader rule scoping.
More videos for this concept
References & primary sources
Master this concept with Archie
Practice it inside an adaptive study session. Archie, your Socratic AI tutor, tracks your mastery with Bayesian Knowledge Tracing and schedules the perfect next review.