Modular Rules
Path-specific instructions
How modular rules work in Claude Code
Modular rules are a way to split your Claude Code instructions into small, topic-focused files instead of one giant CLAUDE.md. Each file lives in the .claude/rules/ directory and owns one area: one for TypeScript, one for React components, one for API routes. The goal is simple — a rule should load only when it is actually relevant, not sit in the context on every request. The folder-structure block below shows the typical layout: a separate .md file per file type.
The core mechanism is path matching. Each file begins with a YAML frontmatter block containing a paths key listing glob patterns. When Claude reads, edits, or creates a file, it checks which rules match that file's path and folds their instructions into the context. The **/*.ts pattern in the examples on this page means "any .ts file at any nesting depth," while a line starting with an exclamation mark — !**/*.test.ts — is an exclusion: the rule applies to every TypeScript file except tests. That keeps production-code instructions from leaking into test files and vice versa.
When and why to use it
Reach for modular rules once a project grows and a single memory file becomes contradictory: backend rules get in the way of frontend work, and half the lines are irrelevant to the current file. A concrete example: a frontend rule says "functional components only" while an API rule says "validate the request body with Zod." Keeping both in one CLAUDE.md wastes context on irrelevant guidance and occasionally misapplies it. Splitting them into react.md and api.md with precise paths gives you targeted delivery. Key pitfalls: patterns that are too broad (a rule catches stray files), forgotten exclusions for generated code, and describing "what to do" without the "why" — without a reason, the model is more likely to break the rule. Commit your rule files to git alongside the project so the whole team shares them.
Modular rules are separate .md files in the .claude/rules/ directory that apply only to specific files.
.claude/rules/ ├── typescript.md # Rules for *.ts, *.tsx ├── react.md # Rules for components ├── api.md # Rules for API routes ├── tests.md # Rules for tests ├── security.md # Security guidelines └── database.md # Database conventions
💡 Rules are automatically loaded when Claude works with files matching the patterns.
Each rule is a Markdown file with YAML frontmatter containing paths:
--- paths: - "**/*.ts" - "**/*.tsx" - "!**/*.test.ts" --- # TypeScript Rules Your instructions here...
Include patterns
**/*.ts— all TS filessrc/components/**— all in components*.config.js— configs at root
Exclude patterns
!**/*.test.ts— except tests!**/node_modules/**— except modules!dist/**— except dist
typescript.md**/*.ts**/*.tsx
--- paths: - "**/*.ts" - "**/*.tsx" --- # TypeScript Rules - Use strict TypeScript settings - Prefer interfaces over types for objects - Always add return types to functions - Use 'unknown' instead of 'any'
react.mdsrc/components/**/*.tsx
---
paths:
- "src/components/**/*.tsx"
---
# React Component Rules
- Use functional components only
- Props interface should be named {ComponentName}Props
- Use memo() for expensive renders
- Prefer composition over prop drillingapi.mdsrc/app/api/**/*.ts
--- paths: - "src/app/api/**/*.ts" --- # API Route Rules - Always validate request body with Zod - Return proper HTTP status codes - Handle errors with try/catch - Log all errors to monitoring
tests.md**/*.test.ts**/*.spec.ts
--- paths: - "**/*.test.ts" - "**/*.spec.ts" --- # Testing Rules - Use describe/it blocks - Mock external dependencies - Test edge cases - Aim for 80% coverage
Best Practices
- 1.Create separate rules for different file types
- 2.Use exclusions (!) for tests and generated files
- 3.Document "why", not just "what"
- 4.Commit rules to git with the project
Frequently asked questions
What are modular rules in Claude Code?
Modular rules are separate Markdown files in the .claude/rules/ directory, each owning one area such as TypeScript, React components, or API routes. Instead of one large CLAUDE.md, instructions are split into topic files that load only when Claude works with matching files.
Where are Claude Code rules stored and how do you scope them to files?
Rules live in the .claude/rules/ folder at the project root. Each file starts with a YAML frontmatter block containing a paths key listing glob patterns like **/*.ts. Claude matches the edited file's path against these patterns and folds only the matching rules into the context.
How do you exclude tests or generated files from a Claude Code rule?
Add a line beginning with an exclamation mark to the paths list to create an exclusion. For example, !**/*.test.ts applies a rule to every TypeScript file except tests, while !**/node_modules/** and !dist/** skip dependencies and build output, keeping production-code instructions out of tests.
Why use modular rules instead of a single CLAUDE.md file?
As a project grows, one memory file becomes contradictory: backend rules get in the way of frontend work and many lines are irrelevant to the current file. Splitting instructions into react.md, api.md, and others with precise paths gives targeted delivery, so Claude sees only relevant rules and doesn't waste context.
This lesson is part of a structured LLM course.
My Learning Path