What is .claude/rules?
Per the official memory docs it is the .claude/rules/ directory in a project, where each .md file covers one topic (for example testing.md or api-design.md) and files are discovered recursively, so subdirectories work. The personal version lives in ~/.claude/rules/ and applies to every project on your machine.
Why does it exist?
The docs advise about 200 lines for a single CLAUDE.md, since longer files use context and reduce adherence. Splitting into several rule files makes them easier for a team to maintain, and path scoping keeps rules relevant to only part of the code from occupying context in every session.
How does it work?
Rules without paths load at launch with the same priority as .claude/CLAUDE.md. Rules with paths (a YAML list or comma-separated string of globs) load when Claude uses Read, Write, Edit or a Bash command that counts as a read, such as cat or head on a single file, on a matching file. paths is the only frontmatter field read, and the frontmatter is removed before loading.
So what does this mean for me?
Watch three things: if the frontmatter YAML fails to parse, the rule loads as if it had no paths, unconditionally (run claude --debug to see the error); a [ in a glob must be written [; and a symlink pointing outside the working directory needs external imports approved first, after which only rules without paths load.
The docs' example: a rule file with paths: ["src/api/**/*.ts"] saying all API endpoints must validate input, use the standard error format and carry OpenAPI comments, which enters context only when Claude touches a TypeScript file under src/api.
Pros: modular rules that take context only when relevant. Cons: one more load timing to keep track of, and broken YAML silently turns into unconditional loading.