.claude/rules/ and paths: — instructions that load when they are relevant

Your CLAUDE.md has crossed 200 lines and you can see exactly why: forty of those lines are database conventions that only matter under src/db/, and thirty are React rules nobody working on the API will ever need. Lesson 6.2 told you to route an instruction that "only matters for one part of the codebase" somewhere else. This is that somewhere else, and the one thing it asks you to get right is when each file arrives.

One file per topic

.claude/rules/ is a directory of markdown files, each covering one subject. Nesting works, and you register nothing:

.claude/
├── CLAUDE.md          # Main project instructions
└── rules/
    ├── testing.md     # Testing conventions
    └── frontend/
        └── react.md   # Discovered recursively

~/.claude/rules/ is the personal equivalent, applying to every project on your machine. The docs give the ordering — user-level rules are loaded before project rules, "giving project rules higher priority" — but nowhere say that a project rule overrides a conflicting personal one. What they do say is the part to design around: if two rules contradict each other, Claude may pick one arbitrarily (How Claude remembers your project). A personal rule disagreeing with the project rule is a defect in both, not a losing bid.

An unscoped rule is CLAUDE.md under a different filename

This is the sentence people skip:

Rules without paths frontmatter are loaded at launch with the same priority as .claude/CLAUDE.md. — How Claude remembers your project

Splitting a 300-line CLAUDE.md into six tidy rule files buys exactly what @ imports bought in Lesson 6.1: organization, and not one token of context back. Six files with owners beat one file with none, so the maintainability is real — but everything still loads at launch, so if you did this to shrink startup context you have not yet done anything. The savings are in the next section.

paths: and what actually fires it

Add a paths list to a rule's frontmatter and it stops loading unconditionally:

---
paths:
  - "src/api/**/*.ts"
---

- All API endpoints must include input validation
- Use the standard error response format

Rules without a paths field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use. — How Claude remembers your project

Read the second sentence twice. The trigger is Claude reading a matching file — not you mentioning the directory, not the task being obviously about the API. Until a matching read happens the rule is not in the window and cannot influence anything. The documented examples cover the four shapes you will reach for: **/*.ts for every TypeScript file in any directory, src/**/* for everything under src/, *.md for markdown in the project root, src/components/*.tsx for one directory's React components.

Globs that do what you meant

Two edge cases account for most rules that silently do nothing.

Brace expansion multiplies. src/*.{ts,tsx} expands to two patterns and {a,b}/{c,d}/*.{ts,tsx} to eight. A rule's whole paths list shares one budget of 1,000 expanded patterns and 4 MiB, and patterns without braces do not count against it. Blow the budget and the failure is quiet: any pattern that would exceed it is used unexpanded, and its literal braces then match no files.

A square bracket is glob syntax, not a character. Glob reads [ as the start of a bracket expression such as [abc]. A pattern with a [ that cannot be read as one — the docs' example is photos [2024/** — is invalid: it matches nothing, while the rule's other patterns keep working. Escape it as photos \[2024/** when you meant the literal character (How Claude remembers your project).

Both failures are per-pattern and silent, so a rule can be half-live without ever looking broken, and a rule that matches nothing looks identical to a rule Claude ignored. The check is therefore the session, not the glob: read a file in the target directory, then run /context, which the docs name as the way "to check which files actually loaded into the current session" (How Claude remembers your project).

Per-directory CLAUDE.md, or a central rule?

Two ways to target part of the tree, and the docs put the difference in mechanics rather than in subject matter:

Per-directory CLAUDE.md files and path-scoped rules under .claude/rules/ both let you target instructions to part of the tree. They differ in where the file lives and when it loads. — Monorepos and large repos

The deciding row is usually the first: does the convention belong to the team that owns that directory, or to the repository? There is a third factor, and you set it from the shell rather than a file. Where you launch claude decides which files it can read without a further permission grant, which CLAUDE.md files load at startup, and which project settings apply. Start in packages/api/ and that package's file plus every ancestor's loads at launch, with nothing from packages/web/ in context; start at the repository root and only the root file loads at launch, each subdirectory's waiting for a read there (Monorepos and large repos).

Neither answer is a skill. Rules load every session or when matching files are opened; task-specific instructions that need not sit in context at all belong in a skill, which loads only when you invoke it or when Claude judges it relevant to your prompt. Writing one is Level 7 — here it is only the destination.

Excluding what you never work in

The mirror image of scoping your own rules is refusing other people's. claudeMdExcludes skips ancestor and subdirectory files by path or glob:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Patterns match against absolute file paths, and the key is configurable at any settings layer — user, project, local, or managed policy — with the arrays merging across layers rather than overriding. That merge matters: a project-level exclusion adds to your user-level list, it does not replace it.

Keep personal exclusions in .claude/settings.local.json, and mind where you put that file. A root .claude/settings.local.json loads in every session inside the repository regardless of the directory you started in, so launching in packages/api/ still carries your root-level exclusions with you — except where Claude Code does not use the repository root, such as on Windows. Before v2.1.211 it loaded only from the starting directory (Monorepos and large repos).

Two limits. Exclusions reach only user, project and local memory files: managed policy CLAUDE.md cannot be excluded, so organization-wide instructions apply regardless of individual settings (Settings reference). And the one more likely to catch you:

The exclusion list is static, not a per-task switch. To focus on one package today and another tomorrow, start Claude from that package's directory instead of editing exclusions. — Monorepos and large repos

Exclusions are for directories you never work in — vendored subtrees, legacy code, another team's packages. Today's focus is a cd.

The trap: a permanent rule behind a temporary trigger

paths: is such an obvious answer to a long CLAUDE.md that it gets applied to rules which must always hold. Take "never edit a migration after it has merged", scoped to db/migrations/**. It is absent until Claude reads a file there — and then Lesson 3.2's compaction table takes it away again:

Path-scoped rules and nested CLAUDE.md files load into message history when their trigger file is read, so compaction summarizes them away with everything else. — Context window

Right after compaction Claude Code re-reads up to five of the recently modified files and reloads the rules applying to those, so a scoped rule may return. Whether yours does depends on which five those were.

So the routing question is not "does this apply to one directory?" It is "is this a convention for that code, or a constraint on my session?" Conventions scope happily; constraints do not. And a constraint that must hold regardless of what Claude decides was never an instruction file's job at all: a rule is guidance Claude reads, exactly as CLAUDE.md is, and a guarantee comes from a hook or a permission rule (Explore the .claude directory). Lesson 6.2 draws that line.