Support @include directive for composable CLAUDE.md files
Resolved 💬 7 comments Opened Dec 10, 2025 by e-fu Closed Mar 10, 2026
Problem
Currently, Claude Code supports two levels of instructions:
- Global:
~/.claude/CLAUDE.md - Project:
./CLAUDE.md
This creates a maintenance problem for developers working across multiple projects with shared patterns:
- Language-specific rules (e.g., Elixir conventions, Go idioms, Rust patterns) need to be duplicated across every project of that type
- Global file bloat - putting all language rules in
~/.claude/CLAUDE.mdwastes context on irrelevant instructions (Go rules loaded for Elixir projects) - Project CLAUDE.md can't be split - project-specific info can't coexist with shared language templates without copy-pasting
- Update burden - when best practices change, you must update every project individually
Example scenario:
~/.claude/CLAUDE.md # 2000 lines of Elixir + Go + Rust rules
project-a/CLAUDE.md # Elixir project - only needs Elixir rules
project-b/CLAUDE.md # Go project - only needs Go rules
Proposed Solution
Add an @include directive that merges content from referenced files:
<!-- project CLAUDE.md -->
@include ~/.claude/languages/elixir.md
@include ~/.claude/patterns/phoenix-1.8.md
## Project-Specific Instructions
This project uses PostgreSQL and handles payments via Stripe...
Behavior:
- Includes are resolved at load time, before instructions are processed
- Paths can be absolute or relative to the including file
- Circular includes are detected and error
- Missing files produce a warning but don't fail
Alternatives Considered
- Symlinks - Don't work because project CLAUDE.md needs both shared AND project-specific content
- Build scripts - Extra tooling burden, easy to forget
- Slash commands - Require manual invocation each session; don't provide persistent context
- MCP servers - Overkill for static text injection
Additional Context
- Related to #13032 (hierarchical skills) - same motivation of context efficiency
- Per #13003, avoiding frontmatter syntax since that's reserved for Claude Code features
- The
@includesyntax is familiar from CSS/Sass and unambiguous in Markdown context
This issue has 7 comments on GitHub. Read the full discussion on GitHub ↗