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:

  1. Language-specific rules (e.g., Elixir conventions, Go idioms, Rust patterns) need to be duplicated across every project of that type
  2. Global file bloat - putting all language rules in ~/.claude/CLAUDE.md wastes context on irrelevant instructions (Go rules loaded for Elixir projects)
  3. Project CLAUDE.md can't be split - project-specific info can't coexist with shared language templates without copy-pasting
  4. 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

  1. Symlinks - Don't work because project CLAUDE.md needs both shared AND project-specific content
  2. Build scripts - Extra tooling burden, easy to forget
  3. Slash commands - Require manual invocation each session; don't provide persistent context
  4. 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 @include syntax is familiar from CSS/Sass and unambiguous in Markdown context

View original on GitHub ↗

This issue has 7 comments on GitHub. Read the full discussion on GitHub ↗