A CLAUDE.md that keeps growing is one of the first problems people hit: the docs advise about 200 lines per file, since longer files use more context and reduce adherence. One official way out is .claude/rules/: split rules into several files, and make some load only when Claude touches certain files. This is a getting-started walkthrough from the docs. Except where marked, everything is from the official memory page (How Claude remembers your project); I did not run the steps on my own machine, so please try them once yourself to confirm.

Directory layout

your-project/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md      # no paths: loads at launch
│       └── api.md             # has paths: loads on matching files
└── src/api/users.ts

Put one topic in each .md file with a descriptive name (the docs' examples are testing.md and api-design.md); subdirectories such as frontend/ and backend/ are discovered recursively. Rules without paths load at launch with the same priority as .claude/CLAUDE.md.

Step one: a rule that appears only for API files

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

API rules

Validate all input before using it
Return errors in the standard error format

The docs say paths is the only frontmatter field Claude Code reads from a rule; other fields are ignored without an error, and the frontmatter is removed before the rule loads. paths accepts a YAML list or a comma-separated string.

When does it load

A path-scoped rule loads when Claude uses Read, Write or Edit on a matching file; it also loads when Claude views a single matching file with a Bash command the docs count as a read, such as cat or head. So just opening a session without touching a file leaves the rule out of context. A rule without paths loads unconditionally and applies to all files.

Common glob patterns

• **/*.ts: all TypeScript files in any directory
• src/**/*: all files under src/
• *.md: Markdown files in the project root
• src/components/*.tsx: React components in a specific directory
• Brace expansion works, such as src/**/*.{ts,tsx}; a rule's whole paths list shares one budget of 1,000 expanded patterns and 4 MiB, and a pattern that would exceed it is used unexpanded, so its literal braces match no files.

Three pitfalls

• Broken YAML becomes "load always": the docs say that if the YAML in the frontmatter does not parse, Claude Code ignores it and loads the rule as if it had no paths. A rule meant for API files only then loads in every session. Run claude --debug to see the parse error.
• Escape [: glob treats [ as the start of a bracket expression, and a pattern that cannot be read as one (such as photos [2024/) is invalid and matches nothing while the rule's other patterns keep working; to match a literal [, write photos \[2024/.
• Symlinked shared rules: .claude/rules/ supports symlinks so you can link a shared set into several projects, but a symlink whose target is outside the working directory needs external imports approved first, and after that only rules without a paths field load. To share without that approval, keep them in ~/.claude/rules/, which applies to every project on your machine.

How to confirm it actually loaded

What I can confirm from the official docs: an InstructionsLoaded hook can fire when instruction files load, and claude --debug shows frontmatter parse errors. A third-party writeup (claudefa.st) says /memory lists loaded CLAUDE.md and rules files, which I did not verify, so go by your version. A more direct approach (my suggestion, untested): start a new session without touching any file and ask Claude "which API rules apply now"; then have it read src/api/users.ts and ask again; the two answers should differ.

Rules, CLAUDE.md or a Skill

The docs say rules load every session or when matching files are opened; for task-specific instructions that need not be in context all the time, use a skill, which loads only when you invoke it or Claude judges it relevant. My summary: short rules for the whole project go in CLAUDE.md, rules tied to a kind of file go in path-scoped rules, and a whole workflow goes in a skill. A third-party writeup also says that after Compaction, path-scoped rules return only when Claude next reads a matching file; I did not find that in the official docs, so treat it as a possibility.