@path Imports & Composition

A single CLAUDE.md can grow unwieldy. The @path/to/file import syntax lets you compose instructions from multiple files while keeping each file focused. Imported files are expanded and loaded into context at launch, alongside the CLAUDE.md that references them.

Syntax

Reference any file with @ anywhere in a CLAUDE.md:

Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory — a frequent trap. Tilde paths (@~/...) point at your home directory, which is the recommended way to share personal instructions across multiple git worktrees (a gitignored CLAUDE.local.md only exists in the worktree where you created it).

Recursion and the depth limit

Imported files can recursively import other files, with a maximum depth of four hops. So the chain CLAUDE.md → A → B → C → D is valid; a fifth nested hop beyond that is not expanded. Keep import trees shallow: deep chains are hard to reason about and every file in the chain still loads into context.

Security approval

The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, imports stay disabled and the dialog does not reappear. This is a deliberate safety gate — an imported file could otherwise pull in arbitrary instructions.

Imports do not save context

A critical nuance for the exam and for real budgets: imports help organization, not token cost. Every imported file is expanded and enters the context window at launch, exactly as if you had pasted it inline. If your problem is that CLAUDE.md is too large, splitting it into @ imports does not reduce context. The right tool for that is path-scoped rules (.claude/rules/ with a paths: glob) or Skills, both of which load only when relevant.

AGENTS.md interop

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already standardizes on AGENTS.md, create a thin CLAUDE.md that imports it so both tools share one source:

A symlink (ln -s AGENTS.md CLAUDE.md) also works when you have no Claude-specific content to add.

Exam focus: Know the syntax (@path, relative resolves to the importing file, @~/... for home/worktree sharing), the max depth of four hops, the first-use approval dialog, and — most testable — that imports expand at launch and do NOT reduce context; use path-scoped rules or Skills to actually shrink the always-loaded footprint. Use @AGENTS.md to interop with other agent tools.