Modular CLAUDE.md with @import

Core

Configure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization · Difficulty 2/5

claude-mdmodularimportorganization

Prerequisites

As projects grow, a single monolithic CLAUDE.md becomes unwieldy. The @import syntax and .claude/rules/ directory provide two complementary strategies for modular organization.

@import Syntax

Reference external files to keep CLAUDE.md modular:

@import ./standards/testing.md
@import ./standards/api-conventions.md

This lets each package's CLAUDE.md selectively include only the standards files relevant to its domain. Maintainers choose which standards apply based on their domain knowledge.

Splitting into .claude/rules/

Break a large CLAUDE.md into focused topic-specific files:

.claude/rules/
  testing.md           # Testing conventions
  api-conventions.md   # API patterns
  deployment.md        # Deployment procedures

When to Use Each

Strategy	Best For

|----------|----------|

Single CLAUDE.md	Small projects with few conventions
@import	Monorepos where packages share some but not all standards
.claude/rules/	Large projects needing topic-specific, conditionally loaded rules

Key Benefit

Modular organization prevents context bloat -- Claude only loads the conventions relevant to the current task, reducing irrelevant context and token usage.

Key Takeaways

✓@import lets each package selectively include relevant standards files
✓Split large CLAUDE.md into topic-specific files in .claude/rules/
✓Modular organization prevents context bloat and reduces token usage

Related Concepts

Path-Specific Rules (.claude/rules/)

Use .claude/rules/ with glob patterns for file-type-specific conventions