Scope CLAUDE.md Rules to Specific File Types with .claude/rules/
Instead of cramming every rule into one big CLAUDE.md, you can split instructions across files in .claude/rules/ — and scope each file to only load when Claude is working on matching paths.
Add a paths frontmatter field to make a rule file conditional:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Rules with paths frontmatter only enter Claude's context when it reads files matching those glob patterns. Rules without paths load unconditionally at session start, just like a regular CLAUDE.md. You can mix both in the same project.
This keeps context lean and focused. An API style guide only appears when Claude is editing API files. A test conventions file only appears when it touches tests.
Organise your rules directory however you like — subdirectories work and files are discovered recursively:
.claude/rules/
├── testing.md # paths: tests/**/*.test.ts
├── api-design.md # paths: src/api/**/*.ts
├── security.md # no paths — always loaded
└── frontend/
└── components.md # paths: src/components/**/*.tsx
You can also symlink shared company-wide rules into your project's .claude/rules/shared/ so teams stay consistent without duplicating files.
Path-scoped rules mean Claude only reads what's relevant — less noise, better instructions.
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.