Imports and the @ Syntax

When One File Is Not Enough

Projects grow. CLAUDE.md files grow with them. What started as a concise list of conventions becomes a sprawling document covering code style, testing procedures, git workflows, API conventions, deployment notes, and environment setup. The file is hard to maintain, easy for team members to add to but rarely pruned, and almost certainly longer than the 200-line threshold where adherence starts to degrade.

The @ import syntax solves the maintenance problem. It lets you split CLAUDE.md into multiple topic-focused files — testing.md, git-workflow.md, api-conventions.md — while keeping a clean root file that references them. But before you reach for it, there is an important caveat to understand: imports do not save context space.

The @ Import Syntax

To import a file in CLAUDE.md, write @path/to/file anywhere in the document. At session start, Claude Code resolves all @imports and expands them inline before the content enters the context window.

A CLAUDE.md that references three topic files looks like this:

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions

- Git workflow: @docs/git-instructions.md

- Personal overrides: @~/.claude/my-project-instructions.md

Imports can appear anywhere in the file, not just at designated import sections. They work inline with regular text.

Path Resolution Rules

Relative paths in @imports resolve from the location of the importing file, not from the current working directory. This means a CLAUDE.md in src/api/ that imports @../shared-rules.md resolves the path relative to src/api/. This matters when you have nested CLAUDE.md files in subdirectories that import shared files — the paths need to be relative to where the importing file lives.

Absolute paths resolve from the filesystem root. Paths starting with ~/ expand to your home directory. Both absolute and home-relative paths are allowed anywhere in CLAUDE.md files.

Import chains are supported up to four hops deep. An imported file can itself import other files, and those can import further files, up to a depth of four. Circular imports are not allowed. This limit prevents runaway import graphs while supporting reasonable modular structures.

What Imports Do (and Don't) Do

The most important thing to understand about @ imports: they do not lazy-load content. Imported files are expanded and loaded into context at session start, alongside the CLAUDE.md that references them. If you import five topic files from your root CLAUDE.md, all five files load into context at launch — you have the same context cost as if you had pasted all their content directly into CLAUDE.md.

This means imports solve the maintenance and organization problem, not the context size problem. For context size, use path-scoped rules (lesson 5), which genuinely load conditionally based on which files Claude is working with.

To mention a path in CLAUDE.md without importing it, wrap it in backticks: `@README` stays as literal text and does not trigger an import. This is useful when you want to reference file paths in instructions without importing their contents.

CLAUDE.local.md for Personal Notes

For personal project-specific information that should never reach your teammates — your local sandbox URL, your personal test database credentials, your preferred test data setup — use CLAUDE.local.md at the project root. This file loads alongside CLAUDE.md and is treated the same way, but it should be added to .gitignore so it is never committed to version control.

Running /init and choosing the personal option automatically creates CLAUDE.local.md and adds it to .gitignore in one step. If you create it manually, make sure to add the gitignore entry — a committed CLAUDE.local.md with sandbox credentials is a security incident waiting to happen.

Cross-Worktree Sharing

A gitignored CLAUDE.local.md only exists in the git worktree where you created it. If you use multiple worktrees of the same repository — a common pattern for running parallel Claude Code sessions — a CLAUDE.local.md in one worktree is invisible to the others.

To share personal instructions across all worktrees, put them in a file in your home directory and import it with an absolute path reference:

# Individual Preferences

- @~/.claude/my-project-instructions.md

The home-directory file is not worktree-specific, so it loads in every worktree that references it.

AGENTS.md Interoperability

Claude Code reads CLAUDE.md, not AGENTS.md. If your repository already uses AGENTS.md for other coding agents like GitHub Copilot or Devin, you have two options for avoiding instruction duplication.

The first option is an import: create a CLAUDE.md that imports the AGENTS.md file and adds Claude-specific instructions below the import. Claude loads the imported file at session start and appends the rest. The second option is a symlink: ln -s AGENTS.md CLAUDE.md makes both tools read the same file with no import needed. On Windows, symlinks require Administrator privileges or Developer Mode, so the import approach is safer there.

Running /init in a repository that already has an AGENTS.md reads it and incorporates relevant parts into the generated CLAUDE.md. It also reads .cursorrules, .devin/rules/, and .windsurfrules if they exist, giving you a migration path from other coding agent configurations.