Claude Code Rules: .claude/rules Files Explained
Claude Code rules explained: how .claude/rules files load, path-specific rules with paths frontmatter, user-level rules, and rules vs CLAUDE.md vs skills.
Josh Pocock7 min read
AI Coding
Rules files
Stride AI Academy
Claude Code rules are markdown files in your project's .claude/rules/ folder, one topic per file, that Claude reads as instructions alongside your CLAUDE.md. A rule with no frontmatter loads at the start of every session. A rule with a paths field loads only when Claude works with files that match it, which keeps instructions for one part of the codebase out of context the rest of the time.
This guide covers how to set up the rules directory, when each kind of rule loads, path-specific rules and their glob patterns, user-level rules in ~/.claude/rules/, sharing rules with symlinks, and when to use a rule, CLAUDE.md, a skill or a hook instead. Everything here was checked against the rules section of Claude Code's memory docs and the .claude directory docs on November 22, 2026. If you haven't written a CLAUDE.md yet, start with our CLAUDE.md file examples.
What .claude/rules files are for
A CLAUDE.md file is loaded in full every session. As a project grows, it fills with instructions that only matter for one area: API conventions, test style, migration rules. The docs recommend keeping each CLAUDE.md under 200 lines, because longer files cost more context and Claude follows them less reliably.
Rules solve that two ways:
- Splitting by topic. Each file covers one subject, so a team can own and review them separately.
- Scoping by path. A rule can load only when Claude touches matching files, so React rules stay out of a backend task.
Like CLAUDE.md, rules are context, not enforcement. Claude reads them and tries to follow them, but nothing blocks an action because a rule said so.
How to set up the Claude Code rules directory
Put markdown files in .claude/rules/ in your project. Give each one a clear name like testing.md or api-design.md:
your-project/
├── .claude/
│ ├── CLAUDE.md
│ └── rules/
│ ├── code-style.md
│ ├── testing.md
│ └── security.mdClaude Code finds every .md file in the folder, including subfolders, so you can group them as rules/frontend/ and rules/backend/. Commit the folder to share the rules with your team.
A rule file is just instructions:
# Testing
- Run `pnpm test` before saying a task is done.
- New features get a test in the matching `__tests__` folder.
- Never mock the database in integration tests.When Claude Code rules load
| Kind of rule | When it loads |
|---|---|
No paths frontmatter, in the project's .claude/rules/ |
At launch, with the same priority as .claude/CLAUDE.md |
With paths frontmatter |
When Claude reads, writes or edits a matching file |
In a subdirectory's own .claude/rules/ |
On demand, when Claude works in that subdirectory |
In ~/.claude/rules/ |
Every project on your machine, before project rules |
A path-scoped rule also loads when Claude views a matching file with a Bash command that counts as a read, such as cat or head on a single file.
Two more loading details from the docs. Project rules are skipped if you leave project out of --setting-sources. And after /compact, path-scoped rules load again on demand the next time a matching file is touched, while the project-root CLAUDE.md is re-read from disk straight away.
Path-specific rules with paths frontmatter
Add YAML frontmatter with a paths field to scope a rule:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation commentsThis rule stays out of context until Claude opens a TypeScript file under src/api/.
paths is the only field Claude Code reads from a rule. Any other field is ignored without an error, and the frontmatter is removed before the rule reaches Claude. If the YAML doesn't parse, Claude Code ignores the frontmatter and loads the rule as if it had no paths, so a typo turns a scoped rule into an always-on one. Run claude --debug to see the parse error.
Glob patterns for paths
Patterns are relative to the folder that contains the rule's .claude folder. The docs' examples:
| Pattern | Matches |
|---|---|
**/*.ts |
.ts files anywhere |
src/**/* |
Everything under src/ |
*.md |
.md files anywhere |
/*.md |
.md files in the top folder only |
src/components/*.tsx |
.tsx files directly in src/components/, not subfolders |
You can list several patterns and use braces for more than one extension:
---
paths:
- "src/**/*.{ts,tsx}"
- "lib/**/*.ts"
- "tests/**/*.test.ts"
---paths also accepts a comma-separated string instead of a list. A [ starts a bracket expression in glob syntax, so a file name with a literal [ needs escaping, as in 'photos \[2024/**'.
User-level rules in ~/.claude/rules
Rules in ~/.claude/rules/ apply to every project on your machine. Use them for personal preferences that aren't tied to one codebase:
~/.claude/rules/
├── preferences.md
└── workflows.mdUser rules load before project rules, so a project rule comes later in Claude's context. Neither overrides the other. If a user rule and a project rule conflict, Claude may follow either, so keep them consistent. Path-scoped user rules match against the session's main working directory.
Share rules across projects with symlinks
The rules folder supports symlinks, so one set of rules can serve several repos:
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.mdA symlink that points outside your working directory is treated like an external import. Claude Code asks you once per project to approve it at the start of a session, and after approval only the linked rules without a paths field load. Links to network paths, such as a \\server\share UNC path, don't load at all. If you want shared rules without the approval step, keep them in ~/.claude/rules/ instead.
Claude Code rules vs CLAUDE.md vs skills
| Use | When the instruction... | Loads |
|---|---|---|
| CLAUDE.md | Applies to the whole project every session: commands, layout, core conventions | Every session |
A rule without paths |
Applies every session but deserves its own file | Every session |
| A path-scoped rule | Only matters for certain files or folders | When matching files are touched |
| A skill | Is a task or procedure you run sometimes | When you invoke it or Claude decides it's relevant |
| A hook or permission rule | Must happen or must never happen, no exceptions | Enforced by Claude Code itself |
The docs say it directly: rules load every session or when matching files open, so for task-specific instructions that don't need to be in context all the time, use skills. And for anything that must run at a fixed point, like before every commit, write a hook, which runs regardless of what Claude decides.
If other agents work in the repo too, the shared instructions may belong in AGENTS.md. Our AGENTS.md vs CLAUDE.md guide covers which tool reads which file. Our guide to working well with Claude Code covers how rules fit into the wider workflow.
Keep rules files small
A path-scoped rule, or a rule in a subdirectory, has a size limit. Over it, Claude receives only the start of the file plus a note to read the rest. The limit is 40,000 characters with a 200K context window, and 150,000 characters with a 1M window on current models. Run wc -m .claude/rules/api.md to check a file. Splitting a long file into several rules works, because each file counts against the limit on its own.
Check your rules are loading
- Log every load. The docs suggest an
InstructionsLoadedhook to record which CLAUDE.md and rules files load, when and why. It's the clearest way to debug path-scoped rules. - Audit for conflicts. Run
/doctor prompt-auditto have Claude check your CLAUDE.md files, rules, skills and subagents for outdated or contradicting instructions. It proposes edits and changes nothing until you ask. It needs v2.1.283 or later. - Check the frontmatter. A rule that loads everywhere when it shouldn't usually has YAML that didn't parse.
claude --debugshows the error. - Make instructions concrete. "Use 2-space indentation" is followed more reliably than "format code nicely."
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
What is the .claude/rules folder in Claude Code?
It's a folder of markdown instruction files, one topic per file, that Claude Code loads alongside CLAUDE.md. Rules without frontmatter load every session. Rules with a paths field load only when Claude works with matching files.
How do path-specific rules work in Claude Code?
Add YAML frontmatter with a paths list of glob patterns, such as "src/api/**/*.ts". The rule loads when Claude reads, writes or edits a file that matches. Patterns are relative to the folder that contains the rule's .claude folder.
Do Claude Code rules replace CLAUDE.md?
No. They load alongside it. Keep project-wide essentials in CLAUDE.md and move topic or folder-specific instructions into rules so CLAUDE.md stays under about 200 lines.
Can I have rules that apply to every project?
Yes. Put them in ~/.claude/rules/. They load in every project on your machine, before project rules, and neither set overrides the other.
What frontmatter fields do Claude Code rules support?
Only paths. Claude Code ignores any other field without an error. If the frontmatter YAML doesn't parse, the rule loads as if it had no paths, so it applies everywhere.
Should I use a rule or a skill?
Use a rule for standing instructions Claude should keep in mind while working on certain files. Use a skill for a task or procedure you run now and then, since skills load only when invoked or relevant.