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

Status Fixed / completed
Maintainer reply ✓ Yes — bcherny
Activity 3 comments · opened Jul 15, 2026 · closed Aug 17, 2026
💡 Likely answer: A maintainer (bcherny, collaborator) responded on this thread — see the highlighted reply below.

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 ↗

3 Comments

gwoodard9 · 3 months ago

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.

bcherny collaborator · 1 month ago

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 rules or a backticked path such as ` .claude/rules/100-frontend.md is just text, so Claude sees the index without the content being loaded, and your paths-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

github-actions[bot] · 7 days ago

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.