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.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗