## 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

Support @include directive for composable CLAUDE.md files

Status Fixed / completed

Maintainer reply None cached

Workaround ✓ Mentioned in thread ↓

Activity 7 comments · opened Dec 10, 2025 · 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.md wastes 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 @include syntax is familiar from CSS/Sass and unambiguous in Markdown context

View original on GitHub ↗

7 Comments

github-actions[bot] · 7 months ago

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

e-fu · 7 months ago

yes, still acute. I am using it in my daily workflow, and it helps a lot

frostblogNet · 6 months ago

Really like this proposal — it addresses a pain we hit constantly across many repos.

We’re in an agency/multi-team setup with repeated stacks (e.g. Magento, PHP 8.4, plus general engineering rules). Today, if we want to roll out an updated Magento rule set across all Magento projects, we either:

duplicate rules into every project ./CLAUDE.md (high drift / high effort), or
bloat ~/.claude/CLAUDE.md with lots of irrelevant stack rules (wastes context and can hurt output quality).

@include solves the “split shared templates + project specifics” problem really cleanly.

One enhancement that would make this pattern even more maintainable for teams: the ability to point includes at a shared, versioned library (central repo) of instruction files, e.g.:

claude_general.md
claude_magento.md
claude_php_8_4.md

So each project could include the relevant profiles without copy-paste, and org-wide updates happen in one place. Pinning to a tag/commit would also make results reproducible.

Also 👍 to “missing files produce a warning but don’t fail” — for collaboration this is huge (people won’t all have the same local paths / dotfiles). Optional includes (include-if-exists) would be a nice refinement, but even warning-and-continue is already a big step forward.

DarrenCibis · 5 months ago

this would be really helpful for our team too so that we can include our engineering standards docs in with the claude.md.

e-fu · 5 months ago

Closing this — native @path/to/file imports solve the use case.

We submitted this issue because we'd built a plugin (md-includes) as a workaround for composable CLAUDE.md files using @include syntax. It worked via a SessionStart hook that expanded directives with a Python script.

Since then, Claude Code added native @path/to/file import syntax (documented at https://code.claude.com/docs/en/memory#import-additional-files), which covers the core use case:

Recursive imports (max 5 hops)
Relative and absolute paths, including @~/ for home directory
Works across all CLAUDE.md files in the hierarchy

Thanks for implementing this!

DarrenCibis · 5 months ago

Closing this — native @path/to/file imports solve the use case. We submitted this issue because we'd built a plugin (md-includes) as a workaround for composable CLAUDE.md files using @include syntax. It worked via a SessionStart hook that expanded directives with a Python script. Since then, Claude Code added native @path/to/file import syntax (documented at https://code.claude.com/docs/en/memory#import-additional-files), which covers the core use case: Recursive imports (max 5 hops) Relative and absolute paths, including @~/ for home directory * Works across all CLAUDE.md files in the hierarchy Thanks for implementing this!

Thank you

github-actions[bot] · 5 months 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.