Skip to main content
What this unit solves.claude/rules/ splits CLAUDE.md’s always-on constraints into modules that activate only when matching files are touched. When CLAUDE.md grows bloated, cross-domain rules start interfering with each other, or certain rules only make sense for specific file extensions, rules are the right answer. This unit covers the division of labor between rules and CLAUDE.md, the path-scoped loading mechanism, naming and layered organization, and comparisons with equivalent mechanisms in other tools.

​
Learning objectives

  • State the difference between rules and CLAUDE.md, and know when to split something into rules.
  • Use the paths frontmatter to load a rule only when files matching a glob are touched.
  • Split constraints by domain or language into separate rule files, avoiding a single monolithic file.
  • Decide whether a constraint belongs in CLAUDE.md, a standalone rule file, a Skill, or a Hook, and state the deciding criterion.
  • Compare the equivalent mechanisms in OpenAI Codex, Google Antigravity, GitHub Copilot, and Cursor.

​
1. What rules are

Rules are Markdown files placed in .claude/rules/, loaded at the same level as CLAUDE.md (as of 2026-06, per the official memory documentation [1]). Key characteristics:
  • Each .md file is one module, named after its topic (testing.md, api-design.md, python-style.md).
  • Without a paths frontmatter field, a rule is equivalent to CLAUDE.md: loaded in full at every session start.
  • With a paths frontmatter field, the rule is only injected into context when Claude touches a file matching the glob.
  • Like CLAUDE.md, rules belong to the “context layer,” not “enforced execution.” For constraints that must be guaranteed to run, use a Hook (see 04-6 Hooks).
All .md files inside .claude/rules/ are read recursively; you can organize them into subdirectories (frontend/, backend/, ml/) for a layered hierarchy [1].
Rules are “always-on within a scope,” not “called on demand”After adding paths, a rule is still injected into context the moment Claude touches a matching file. This differs from Skills, where the full content is only injected when the user or model explicitly invokes it (see 04-4 Skills). Rules are “always resident within a subset of working sessions,” not “called once like a tool.”

​
2. Division of labor with CLAUDE.md

CLAUDE.md (user-level, project-level, or local layer) holds constraints that apply across tasks, languages, and directories. Rules hold contextual constraints: ones that are only meaningful for a specific path or file extension. There is only one criterion: read this rule aloud to an agent working on an unrelated task — would it cause interference or contradictions? Yes: split it into rules. No: keep it in CLAUDE.md.
How to splitStay in CLAUDE.md:
  • “Responses always in Traditional Chinese, second person”
  • “Never commit .env”
  • “Build command: make build; tests: make test”
  • “Run make lint before every commit”
Move to .claude/rules/python-style.md (path-scoped to **/*.py):
  • “Python requires type hints; public functions must not accept Any”
  • “pytest fixtures go in conftest.py; do not define cross-file fixtures inside individual test files”
  • “Public API functions must have a docstring (Google style)”
Move to .claude/rules/api-design.md (path-scoped to src/api/**):
  • “Every endpoint must be registered in the OpenAPI spec”
  • “Input validation is done at the handler boundary, not inside internal functions”
  • “Error responses always use the {code, message, details} structure”
These three blocks do not interfere with each other: writing React does not load the Python style rules; writing Python does not load the API design rules. The token budget per session is an order of magnitude smaller than stuffing everything into CLAUDE.md.

​
3. Path-scoped rules: the loading mechanism

.md files in .claude/rules/ can use the paths field in YAML frontmatter to restrict when they load. Claude Code only injects the rule into context when a file matching the glob is read during the session [1]. Basic syntax:
Glob syntax (similar to .gitignore style): Multiple patterns can be listed together, or brace expansion used to match multiple extensions at once [1].
Path-scoped rules only load when a file is readA path-scoped rule does not load on every tool call that touches matching files — it loads when Claude reads a file matching the glob. This means: if Claude is asked to edit a file before it has read any file matching the glob, the rule is not in context. Behavior may be inconsistent before that point in the conversation.

​
4. Naming and layered organization

Naming principle: use specific semantic names, not specific behavioral descriptions (not do-not-touch.md, but api-migration-safety.md). Common layering:
.claude
CLAUDE.md
rules
common
code-style.md · general language style
testing.md · testing principles
security.md · security prohibitions (path-scoped to src/)
frontend
react-style.md · React conventions
a11y.md · accessibility
backend
api-design.md · API design
db-migrations.md · database migrations
ml
experiment-tracking.md
Single rule file length: the official recommendation for SKILL.md is under 500 lines (a guideline for skills, but the same spirit applies to rules). Beyond that length, consider splitting further or upgrading to a Skill. .claude/rules/ supports symlinks, so you can maintain a shared rule set in ~/shared-claude-rules/ and link it into multiple projects [1]:
Circular symlinks are detected and bypassed; there is no infinite recursion [1]. On Windows, creating symlinks requires Administrator privileges or Developer Mode. If symlinking is not available, importing ~/shared-*.md via @path inside .claude/rules/ is an alternative.

​
6. User-level rules

Rules placed in ~/.claude/rules/ apply to all projects, with a load order after the user-level CLAUDE.md and before project-level rules [1]:
~/.claude/rules
preferences.md · personal coding preferences
workflows.md · personal common workflows
Common uses: personal tool shortcuts, editor setting preferences, response style conventions that apply across all projects. Project rules override user rules when a file of the same name exists in both.

​
7. The boundary with Skills and Hooks

The three mechanisms have non-overlapping responsibilities: Quick decision tree:
  • Model needs to judge when to insert it: Skill
  • User needs to trigger it explicitly: Command
  • Must run after every occurrence of an action (regardless of model judgment): Hook
  • Always resident, loaded every session, applies across tasks: CLAUDE.md
  • Always resident, loaded only for specific paths: rules (path-scoped)
  • Recording facts rather than instructions: auto memory

​
8. Tool comparison

Rule file mechanisms differ considerably across tools in path-scoped support and frontmatter details (as of 2026-06):
Naming clarifications
  • OpenAI Codex “rules” are executable policy files written in Starlark (allowlists/blocklists controlling agent behavior), not Markdown rule files. Semantically they are closer to Hooks than to the CLAUDE.md modularization discussed here.
  • Cursor uses the .mdc extension (.md does not work). The frontmatter fields are description, globs, and alwaysApply [3]. alwaysApply: true means unconditional loading; globs set means auto-load only on matching files; description only means the model decides by semantic relevance; nothing set means manual @-mention only.
  • GitHub Copilot .instructions.md uses applyTo to restrict to a glob, and can add excludeAgent: "code-review" or "cloud-agent" to exclude specific agents from loading it [4].

​
9. Hands-on exercises

1

Split one rule

Move the Python coding style section from CLAUDE.md wholesale into .claude/rules/python-style.md, adding paths: ["**/*.py"].
2

Verify loading

In the same session, run /memory and confirm python-style.md appears with its path annotation.
3

Test the no-load scenario

Ask Claude to edit a *.md file (outside the **/*.py glob) and then ask about Python style rules. It should not reference python-style.md.
4

Cross-project sharing

Create ~/.claude/rules/preferences.md; start sessions in two different projects and confirm it is loaded in both.

​
10. Common pitfalls

Anti-pattern list
  • Stuffing all constraints into CLAUDE.md: cross-domain rules interfere with each other, every session loads everything, token budget spikes, and long rules are prone to “attention drift” where the model quietly ignores sections.
  • Copying someone else’s rules configuration: constraints that another repo does not need — or actively should not have — get applied by your model.
  • Writing “guaranteed execution” as an imperative sentence in a rule: a rule is context only. The model can miss it in a multi-step task. Anything requiring a deterministic guarantee must go through a Hook.
  • paths set too broadly: using **/* as the paths value is the same as not scoping at all. The rule loads fully on every session startup, wasting the mechanism entirely.
  • Confusing rules and Skills on trigger timing: a rule is injected when Claude reads a matching file; a Skill is invoked when Claude judges it semantically relevant (see 04-4 Skills). Writing “run ruff every time a Python file is edited” as a rule is correct; writing it as a Skill means it waits for an explicit invocation.

​
Self-check

The bar for passing this unit
  1. Can you state the difference between rules and CLAUDE.md, and explain when to split something into rules?
  2. Can you write a correct paths frontmatter and use glob patterns to scope the loading range?
  3. Can you decide, given a requirement, whether a constraint belongs in CLAUDE.md, a standalone rule file, a Skill, or a Hook?
  4. Can you fill in the rule file mechanism for your primary tool on the five-tool comparison table?

​
Sources and further reading

Factual claims are grounded in official documentation; fast-changing items are annotated as of 2026-05.