@import Directive
Claude CodeDefinition
A CLAUDE.md directive that includes the contents of another markdown file. Enables modular CLAUDE.md organization where large configuration is split into focused files (e.g., @import docs/api-conventions.md). Reduces duplication when multiple CLAUDE.md files share common instructions.
Example Usage
Use '@import .claude/security-guidelines.md' in the root CLAUDE.md to include security rules without duplicating them in every directory's CLAUDE.md.
Why It Matters for the CCA-F Exam
The @import directive appears in CCA-F questions about CLAUDE.md organization and modular configuration. Expect scenarios asking when @import is appropriate (shared content, large files) versus when inline text suffices (one-off, short, project-unique). Also tested: path resolution — imports resolve relative to the importing file, not the project root.
In Depth
The @import directive is a CLAUDE.md feature that lets one configuration file include the full contents of another markdown file at load time. When Claude Code encounters @import path/to/file.md inside a CLAUDE.md, it reads that file and treats its contents as if they were written inline at that position.
The primary motivation is modularity. A real project might need:
- Security guidelines shared across every team's project
- API naming conventions specific to the backend service
- Test setup instructions that only apply to the
/testssubdirectory
Without @import, you'd either duplicate this content in multiple CLAUDE.md files (creating a maintenance burden) or cram everything into a single file that grows unwieldy. With @import, you maintain each piece of content once and pull it in wherever needed.
Common patterns:
# Root CLAUDE.md
@import .claude/security-guidelines.md
@import .claude/coding-standards.md
@import docs/architecture.mdPaths are resolved relative to the file containing the @import directive. This means a directory-level CLAUDE.md can import from sibling files in that directory.
What @import is not: it is not a dynamic include or a template system. The imported file is loaded as static markdown at startup — Claude Code doesn't re-read it mid-session or evaluate expressions inside it.
The key architectural insight: @import enables the same compose-not-overwrite philosophy as the CLAUDE.md hierarchy itself. You build up context from modular pieces rather than writing everything in one monolithic file.
From an exam standpoint, the critical detail is that @import resolves paths relative to the importing file. A root CLAUDE.md importing from .claude/security.md resolves differently than a src/api/CLAUDE.md importing the same relative path — the two are resolved from different base directories.
See also: CLAUDE.md for the file hierarchy, Path-Specific Rules for directory-scoped rules.
Related concept: Modular CLAUDE.md with @import.
How It Compares
| Approach | When to use | Downside |
|---|---|---|
| Inline content in CLAUDE.md | Short, project-unique instructions | Grows large; hard to reuse |
@import shared file | Content reused across multiple CLAUDE.md files | One extra file to track |
| Directory-level CLAUDE.md | Rules scoped to a specific folder | Only applies to that folder's sessions |
Global ~/.claude/CLAUDE.md | Personal preferences across all projects | Not shared with team |
Frequently Asked Questions
Are imported paths relative to the CLAUDE.md file or the project root?
Relative to the file containing the @import directive. If `src/api/CLAUDE.md` contains `@import ../../.claude/security.md`, the path resolves from `src/api/`, not from the project root.
Can an imported file itself contain @import directives?
Yes — @import supports nesting. An imported file can import further files, allowing arbitrarily deep modular composition. Be careful to avoid circular imports.
Does @import work in any markdown file or only in CLAUDE.md?
@import is a Claude Code CLAUDE.md feature, not a general markdown standard. It is processed only when Claude Code loads CLAUDE.md files at startup. It has no effect in other markdown documents.