What you will be able to do
- Compare per-directory CLAUDE.md files with path-scoped rules by location, load trigger and best use
- Choose a path-scoped rule when a convention applies to files scattered across many directories
- Write glob patterns that match files by type regardless of directory, such as all test files
- Use claudeMdExcludes to keep another team's CLAUDE.md files and rules out of context
1.Two ways to scope a convention
Claude Code has two mechanisms for conventions that shouldn't apply everywhere, and both load on demand instead of at launch. The first is a CLAUDE.md placed inside a subdirectory. The large-codebases guide describes these as conventions specific to that area's stack: in a monorepo one per package, in a single large tree one per subsystem such as src/db/ or src/api/. The support guide gives the same load behaviour for a subdirectory CLAUDE.md: it is loaded on demand when Claude reads files in that directory, not at session start.
The second is a path-scoped rule. It is a file in the central .claude/rules/ at the repository root, and its paths: glob decides which files it applies to. The large-codebases guide sets the two side by side.
| Approach | File location | Loads when | Use when |
|---|---|---|---|
| Per-directory CLAUDE.md | Inside the directory, alongside its code | At launch when started from that directory, or on demand when Claude reads a file there | Directory owners maintain their own conventions; instructions are versioned with the code |
| Path-scoped rule in .claude/rules/ | Central .claude/ at the repo root | When Claude works with a file matching the rule’s paths: glob | You want all conventions in one place, or the same rule applies to many scattered paths |
The deciding difference is the Loads when column. A subdirectory CLAUDE.md is tied to a location: it applies to one directory tree. A rule is tied to a pattern, so it can apply to any set of files that a glob can describe, wherever those files are.
2.Conventions that cut across directories
Consider the exam guide's standard case, test files. In most codebases tests don't sit in one folder. They sit next to the code they test, in components/, in hooks/, in every feature folder. Suppose you want all of them written with the same testing conventions.
With subdirectory CLAUDE.md files you would need a copy of the test conventions in every directory that holds tests. Each copy would get edited separately, and the copies would drift apart. That model suits a convention owned by one directory and changed together with its code. It doesn't suit a convention defined by what kind of file it is.
A single rule solves this. Put one file in .claude/rules/ and give it a paths glob that matches test files wherever they are. It then loads when Claude works with any test in any folder, and stays out of context for everything else. This is the second half of the documented use case: the same rule applies to many scattered paths.
Sources1
3.Writing globs that match by file type
The paths field takes glob patterns, either as a YAML list or as a comma-separated string. The exam guide uses two shapes, and each does a different job.
The first is a directory-anchored pattern such as terraform/**/*. It starts at one folder, and ** reaches every depth below it, so it matches the whole Terraform tree.
The second is a type-anchored pattern such as **/*.test.tsx. The leading ** matches any directory path, so the pattern selects files by name and extension wherever they sit. This is the form that replaces a pile of subdirectory CLAUDE.md files.
The documentation uses the same wildcards in its own glob examples. In the claudeMdExcludes pattern "**/packages/*/CLAUDE.md", the leading ** matches any path depth, and the single * matches exactly one directory name, meaning each package. The distinction matters when you write patterns. A single * stays inside one path segment, while ** crosses directories.
When a convention covers several file types or areas, list one pattern per entry, and aim for the smallest set that covers the target files without catching unrelated ones. Every extra match loads the rule where it isn't needed, which undoes the benefit of scoping.
A platform engineer maintains a monorepo where test files (matching *.test.ts) are scattered across src/, lib/, packages/*/tests/, and e2e/ directories. The engineer wants testing conventions to load automatically whenever Claude works on any test file, without duplicating the same instructions across multiple subdirectory CLAUDE.md files. Which approach best achieves this?
Correct answer: A — Create a single .claude/rules/testing.md file with paths: ["**/*.test.ts"] in its YAML frontmatter, so the rule loads whenever Claude reads a file matching that pattern anywhere in the repo.
- A. Correct. A single rules file scoped with a recursive glob pattern in the paths frontmatter applies by file type regardless of directory, and loads only when a matching file is opened, avoiding duplication and reducing irrelevant context.
- B. Duplicating a CLAUDE.md per directory means every new test directory needs its own copy, and edits must be kept in sync manually across all copies, which is exactly the maintenance burden path-specific rules avoid.
- C. Placing the conventions in the root CLAUDE.md loads them into every session regardless of whether Claude is touching test files, consuming context on unrelated work instead of loading conditionally.
- D. claudeMdExcludes is used to skip loading specific CLAUDE.md or rules files by path; it does not cause conditional loading of guidance and does not scope a rule to a file-type pattern.
Sources3
4.Keeping other teams' rules out of your context
Rules load from .claude/rules/ in every parent directory as well as your own. In a large monorepo you can therefore pick up conventions that belong to someone else. The claudeMdExcludes setting handles this. It takes glob patterns or absolute paths, and anything matching is skipped. Despite the name, it is not limited to CLAUDE.md files: the memory documentation's own example also excludes another team's rules directory.
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}The large-codebases guide makes the same point with a package-name glob: "**/packages/legacy-*/**" excludes every package whose name matches the glob, including rules. An exclusion is targeted. It removes only what its patterns match, so your own team's path-scoped rules keep loading conditionally as usual. You don't need to edit the other team's files for any of this.
An infrastructure team wants Claude Code to load Terraform-specific formatting and tagging conventions only when Claude edits files under the terraform/ directory, at any subfolder depth. Which YAML frontmatter for a new .claude/rules/terraform.md file correctly scopes the rule to this requirement?
Correct answer: A — --- paths: - "terraform/**/*" ---
- A. Correct. The paths field takes a YAML list, and the double-star glob terraform/**/* matches files under terraform/ at any depth, including nested subfolders.
- B. A single star only matches files directly inside terraform/ and would miss files in nested subfolders such as terraform/modules/network/main.tf.
- C. The frontmatter field recognized for path scoping is paths, not include; a rule using include would not be treated as path-scoped.
- D. The paths field is documented as a YAML list of patterns, not a bare string; while a single pattern is common, it should be expressed as a list item under paths:.
Sources1
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Test-file conventions belong in a CLAUDE.md inside each directory that contains tests.Why is that wrong?
A path-scoped rule in the central .claude/rules/ is the documented choice when the same rule applies to many scattered paths. One rule with a glob replaces many copies that would drift apart.
Covered in Conventions that cut across directories
2.claudeMdExcludes only filters CLAUDE.md files, so another team's .claude/rules/ can't be excluded with it.Why is that wrong?
Its patterns can match rule files as well. The documented legacy-* example excludes whole packages, rules included, and the memory docs exclude another team's .claude/rules/** directly.
3.A subdirectory CLAUDE.md is always loaded at session start, the same as the root file.Why is that wrong?
When you start from the repository root, subdirectory CLAUDE.md files load on demand, only once Claude reads files in that directory.
Covered in Two ways to scope a convention
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.https://code.claude.com/docs/en/large-codebasesOfficial docs
“Per-subdirectory CLAUDE.md: conventions specific to that area’s stack.”
↩︎ Two ways to scope a convention“You want all conventions in one place, or the same rule applies to many scattered paths”
↩︎ Conventions that cut across directories“Directory owners maintain their own conventions; instructions are versioned with the code”
↩︎ Conventions that cut across directories“excludes every package whose name matches the glob, including rules”
↩︎ Keeping other teams' rules out of your context“You want all conventions in one place, or the same rule applies to many scattered paths”
↩︎ Exam trap 1“excludes every package whose name matches the glob, including rules”
↩︎ Exam trap 2 - 2.https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-promptsOfficial docs
“loaded on demand when Claude reads files in that directory, not at session start”
↩︎ Two ways to scope a convention“loaded on demand when Claude reads files in that directory, not at session start”
↩︎ Exam trap 3 - 3.https://code.claude.com/docs/en/memoryOfficial docs
“Glob patterns that scope the rule to matching files. Accepts a YAML list or a comma-separated string”
↩︎ Writing globs that match by file type