Claude Code Rules: Scoped Instructions That Load Automatically
By Tyler Cyert
Claude Code rules are scoped instruction files that load automatically when matching files are touched. Instead of putting every coding convention into your CLAUDE.md, you create focused rules that only activate when relevant — keeping your base context lean and your instructions precise.
Rules solve the "CLAUDE.md bloat" problem. As projects grow, your main instruction file accumulates sections for every file type, framework, and convention. Rules let you split that into focused files that load on demand.
How Rules Work
A rule is a markdown file in .claude/rules/ with path-glob frontmatter. The frontmatter specifies a globs field like src/components/**/*.tsx, and the body contains the instructions that apply when matching files are touched.
When Claude touches any file matching the glob pattern, that rule loads into context. When Claude works on other files, it does not load — saving context window space.
Rules vs. CLAUDE.md vs. Skills
| CLAUDE.md | Rules | Skills | |
|---|---|---|---|
| Loaded | Every session | When matching files are touched | On demand via /command |
| Format | Free-form markdown | Markdown with glob frontmatter | Markdown with YAML frontmatter |
| Purpose | Project-wide context | File-specific conventions | On-demand procedures |
| Location | Project root | .claude/rules/ | .claude/skills/ |
The decision framework: if Claude needs it every session, put it in CLAUDE.md. If it is file-type-specific, put it in a rule. If it is a procedure you invoke explicitly, put it in a skill.
The Globs Frontmatter
The globs field uses standard glob patterns:
| Pattern | Matches |
|---|---|
*.ts | All TypeScript files in root |
**/*.ts | All TypeScript files, any depth |
src/components/**/*.tsx | React components in src/components |
*.{ts,tsx} | TypeScript and TSX files |
src/db/** | Everything in the database directory |
**/*.test.* | All test files |
Multiple globs are comma-separated in the frontmatter or specified as a YAML list.
Practical Rule Examples
API Route Conventions
A rule with globs src/app/api/**/*.ts that enforces: keep route handlers thin with business logic in src/lib/, validate request bodies with zod, return consistent error format, log all 500 errors with request context, and never expose internal error messages to clients.
Database File Rules
A rule with globs src/db/** that enforces: all queries go through the db client in src/lib/db.ts, never write raw SQL (use the Drizzle query builder), schema changes require running npx drizzle-kit generate, never modify files in drizzle/migrations/ directly, and add seed data for new tables.
Test File Conventions
A rule with globs <strong>/*.test.{ts,tsx}, </strong>/*.spec.{ts,tsx} that enforces: use describe blocks grouped by function or component, write test names as sentences ("it should return 404 when user not found"), mock external services but not internal modules, keep each test file scoped to one module, and use factory functions for test data.
Styling Rules
A rule with globs <strong>/*.css, </strong>/*.scss that enforces: use Tailwind utility classes whenever possible, limit custom CSS to animations and complex gradients, avoid !important, and keep CSS variables in a centralized file.
Documentation Rules
A rule with globs <strong>/*.md, docs/</strong> that enforces: use sentence case for headings, specify language on code blocks, use relative paths for internal links, and keep paragraphs under 4 sentences.
How Rules Load in Practice
When Claude reads or edits a file, it checks all rules in .claude/rules/ for glob matches. Multiple rules can activate simultaneously — if Claude edits both a component and a test file in the same session, both the component rule and the test rule load.
Rules are additive. They layer on top of your CLAUDE.md, not replace it. If your CLAUDE.md says "use TypeScript strict mode" and a rule says "use named exports for components," both apply when Claude works on component files.
Organizing Rules
A typical project might have 3-7 rules, organized by domain:
- components.md — React component conventions
- api-routes.md — API handler patterns
- database.md — Schema and query rules
- testing.md — Test file conventions
- security.md — Security-sensitive file handling
Name rules by domain, not by glob pattern. components.md is clearer than tsx-files.md.
Creating Rules with DotBox
Each rule needs valid glob syntax in the frontmatter and focused instructions in the body. DotBox provides a rule editor where you define the glob pattern, write the instructions, and see which files in your project structure would match — then export the complete .claude/rules/ directory as part of your configuration package.