CLAUDE.md @ import always inlines content — need a "reference only" mode for lazy-loaded rules

Open 💬 1 comment Opened Jul 15, 2026 by pipe-gale01

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 via paths
  • 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.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗