Rules that load only when needed.
Most people dump everything into one CLAUDE.md. 3% know about .claude/rules/ — a folder where each file can have its own path filter. API rules only load when you touch API files.
The problem with one big CLAUDE.md
Why splitting rules into a folder beats a single file
the wrong way
One CLAUDE.md with 500 lines. API style guides, test conventions, DB rules, frontend patterns, security policies, all at once.
Problem: every rule loads on every file. Context bloat. Reduced adherence. Irrelevant instructions taking up tokens.
the right way
Split into .claude/rules/. Each file has a paths: filter. API rules only load when src/api/** is touched.
Result: Claude gets exactly the rules it needs. Nothing extra. Better adherence. Lower token cost.
Example structure
Click any file to see the rule content
← click a file to see the rule
How path scoping works
The frontmatter syntax
# code-style.md # no frontmatter = loads for every file Use 2-space indentation. Always use TypeScript. Prefer const over let.
--- paths: - "src/api/**/*.ts" - "src/routes/**/*.ts" --- # api-design.md — loads ONLY for API files All endpoints need input validation. Return 422 for validation errors. Never expose internal stack traces.
Real rule examples
Common patterns you can use today
---
paths: ["**/*.test.ts", "**/*.spec.ts"]
---
Use vitest, not jest.
No mocking the database.
Always test both success and error paths.---
paths: ["src/components/**"]
---
Use functional components only.
No prop drilling beyond 2 levels.
All components must have TypeScript props.---
paths: ["prisma/**", "**/*.sql"]
---
Never modify existing migrations.
Always add indexes for foreign keys.
Soft-delete instead of hard-delete.---
paths: ["workflows/**/*.json"]
---
Always add error handling nodes.
Use Set node for data transformation.
Document every workflow with a sticky note.