CLAUDE.md @ import always inlines content — need a "reference only" mode for lazy-loaded rules
Problem
@ import in CLAUDE.md always fully inlines the referenced file content at startup. This conflicts with .claude/rules/ paths frontmatter, which is designed for lazy loading (only loads when matching files are accessed).
Using both together causes the same content to be loaded twice — once via @ expansion, once via paths matching.
Use Case
I want to organize project config in three layers:
- Entry layer (CLAUDE.md): project overview + index of available files
- Rules layer (
.claude/rules/*.md): execution guidelines, lazy-loaded viapaths - Memory layer (
memory/*.md): state, experience, preferences
The entry layer should only list references to rules files so Claude knows they exist, then read them on-demand. But @ import defeats this by expanding everything at startup.
Current Behavior
# In CLAUDE.md
@.claude/rules/000-general.md ← Full content inlined at startup
@.claude/rules/100-frontend.md ← Full content inlined at startup
This conflicts with paths frontmatter in the rules files:
# In .claude/rules/100-frontend.md
---
paths:
- "frontend/**/*"
---
Desired Behavior
Support a "reference only" syntax in CLAUDE.md that tells Claude the file exists without expanding it:
## Rules Index
- [000-general.md](.claude/rules/000-general.md) — General rules (language, commands)
- [100-frontend.md](.claude/rules/100-frontend.md) — Frontend rules (paths: frontend/**)
Claude would see the list at startup (lightweight), then read actual file content when needed (via paths matching or manual Read). This is the same pattern as MEMORY.md — an index with one-line descriptions, content loaded on-demand.
3 Comments
Not EXACTLY what your asking but https://norrin.dev is a very cool extension for Claude Code that gives you the ability to see inline diff, accept/ reject per hunk, and track files.
What you describe already works: only
@path(outside backticks or code blocks) imports a file. A plain Markdown link like- [100-frontend.md](.claude/rules/100-frontend.md) — Frontend rulesor a backticked path such as `.claude/rules/100-frontend.mdis just text, so Claude sees the index without the content being loaded, and yourpaths-scoped rules load on demand as usual. So drop the@` from the entries you want as references only. Docs: https://code.claude.com/docs/en/memory#import-additional-files. Closing as available.🤖 Generated with Claude Code
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.