Scaling Config: @import and .claude/rules/
When a single CLAUDE.md grows unwieldy, two mechanisms let you split it cleanly: @import for always-relevant content, and .claude/rules/ for domain-specific rules that load conditionally based on file glob patterns. This article covers the syntax, patterns, and when to use each.
Quick Reference
- →@import pulls another file's content into CLAUDE.md at load time
- →.claude/rules/ files have frontmatter with glob patterns — they load only when matching files are in scope
- →@import is best for content that's always relevant (architecture, conventions)
- →.claude/rules/ is best for domain-specific rules that waste context elsewhere
- →Glob patterns in rules frontmatter match against files being edited or discussed
- →Rules files are plain Markdown — same format as CLAUDE.md
- →Splitting config reduces per-session token cost for files Claude isn't touching
- →You can combine both: @import always-on docs, .claude/rules/ for conditional domains
In this article
When to Split Your CLAUDE.md
A 50-line CLAUDE.md covering tech stack and core conventions is fine as a single file. A 600-line CLAUDE.md with separate sections for the API layer, database layer, frontend components, testing patterns, deployment, and security — that file costs tokens on every session, even when Claude is only editing a single CSS file.
Splitting configuration reduces this waste. Domain-specific rules that apply to database migrations should only load when Claude is working on database files. Frontend component rules should only load when Claude is working in the components directory. Claude Code supports two mechanisms for this: @import directives and the .claude/rules/ directory.
The @import Directive
@import is the simpler mechanism. It is a directive in your CLAUDE.md that tells Claude Code to pull the contents of another file into the context at load time. The imported file is loaded unconditionally — it is always in context when your CLAUDE.md is loaded.
At session start, Claude Code reads each @import path and inlines the referenced file's content. From Claude's perspective, it's as if you pasted the entire imported file directly into CLAUDE.md. This means @imported files count against the same token budget — they're just split across files for your maintenance convenience.
@import is the right choice for content that is useful in every session regardless of what files Claude is working on: architecture overviews, general coding standards, security non-negotiables. If the content would only matter for specific file types, use .claude/rules/ instead.
The .claude/rules/ Directory
The .claude/rules/ directory is a more powerful mechanism. Each file in this directory has YAML frontmatter that specifies which files it applies to via glob patterns. Claude Code only loads a rules file when the files being discussed or edited match its glob pattern.
Splitting by Domain
The recommended pattern for large projects is to split CLAUDE.md by domain: one rules file per concern. This keeps individual files short, targeted, and easy to maintain.
With this structure, editing a test file loads testing.md and security.md. Editing a Prisma schema loads database.md and security.md. Editing a React component loads frontend.md and security.md. Each session loads only the rules relevant to the files in scope.
Multiple rules files can apply simultaneously. If a file matches several glob patterns, all matching rules files are loaded. This is a feature — you can have universal rules (security) that always apply alongside domain-specific ones.
Combining @import and .claude/rules/
The most effective setup uses both mechanisms together: @import for always-on context, .claude/rules/ for conditional domain rules.
Best Practices
Do
- ✓Use @import for architecture docs and standards that are always relevant
- ✓Use .claude/rules/ for domain-specific rules that only matter for specific file types
- ✓Name rules files by domain: frontend.md, database.md, testing.md, security.md
- ✓Keep the main CLAUDE.md short and use it as a table of contents to the rules files
- ✓Use broad globs for security rules (**.ts) and narrow globs for domain rules
Don’t
- ✗Don't put rarely-needed content in @import files — always-loaded content always costs tokens
- ✗Don't use overly specific glob patterns that might miss relevant files
- ✗Don't duplicate rules between files — a rule in two places goes stale in one of them
- ✗Don't skip the frontmatter — a .claude/rules/ file without frontmatter loads unconditionally (same as @import)
Key Takeaways
- ✓@import pulls file content unconditionally — use it for always-relevant context
- ✓.claude/rules/ files load conditionally based on glob patterns — use them for domain-specific rules
- ✓Split by domain: frontend, backend, database, testing, security rules files
- ✓Combining both keeps the main CLAUDE.md lean while still providing deep domain context
- ✓Rules files are additive — multiple files can load simultaneously for the same editing context
Video on this topic
Split Your CLAUDE.md with @import and Rules Files
tiktok