Skip to content

Using `@` Imports in `CLAUDE.md`

If you already keep agent policy in AGENTS.md, Cursor rules, GitHub Copilot instruction paths, or a long README.md, you usually don't want a second copy that drifts out of sync just for Claude Code.

Claude Code loads a project's CLAUDE.md every session. @path/to/file lines in that file can point at other files. At session start, Claude Code resolves those paths relative to the CLAUDE.md that contains them and includes their contents with the rest of the file.

This provides you a bridge to resuse agent context: One body of markdown on disk, while each integration still uses its own documented entrypoint (CLAUDE.md here, Cursor rules there, Copilot's matrix elsewhere).

Same Markdown, Different Loaders

In practice, you may standardize on a few paths (AGENTS.md, .github/copilot-instructions.md, .cursor/rules/, and similar) that more than one tool is allowed to read. The split isn't Markdown syntax. It's which file each integration loads first and whether @ inside CLAUDE.md expands at all.

File Default for Claude Code Typical Use
CLAUDE.md Yes. Loaded every session from the paths Anthropic documents. Session-wide rules plus @path imports that pull in other files.
AGENTS.md No. Claude Code reads CLAUDE.md, not AGENTS.md, unless you import it from CLAUDE.md with a line such as @AGENTS.md. Shared policy other tools often load directly (Cursor rules, Copilot on supported surfaces, other agents).

Anything else you pull in with an @ line (README.md, package.json, a file under docs/) is extra context at launch, not another reserved filename pair like the two above.

Imports Help Organization, Not Context Size

Splitting into @path imports helps organization and review: smaller diffs, clearer ownership, less pressure to keep one giant file tidy. Anthropic is explicit that imports don't reduce how much lands in context at launch. Imported files still load then. If the goal is to avoid hauling in rules you rarely need, use path-scoped rules and tighter prose, not a deeper import chain for its own sake.

Minimal Layout

A common reuse pattern is a thin CLAUDE.md that imports the shared file other tools already read, then adds a Claude-only tail:

@AGENTS.md

## Claude-only
Always run the test suite before you suggest merging.

You can import more than one path and nest imports. Keep the entry file thin so the structure stays obvious when someone opens it cold.

Other Editors and AI Assistants

The @path include lines in CLAUDE.md are Claude Code behavior from Anthropic's docs. Another product can still read the same filenames when it merges instructions. It isn't required to implement the same import grammar.

GitHub Copilot (VS Code, JetBrains, and other hosts): picking a Claude model swaps the model behind a Copilot feature. It doesn't automatically enable Anthropic's @ file expansion inside CLAUDE.md.

Copilot merges custom instructions from GitHub-defined paths such as .github/copilot-instructions.md, path-specific *.instructions.md, and, on some surfaces, agent instruction files such as AGENTS.md, CLAUDE.md, or GEMINI.md. Which filenames apply depends on the Copilot feature and the host IDE, so check GitHub's matrix instead of assuming parity with Claude Code.

Cursor picks up project rules (AGENTS.md, .cursor/rules/, and friends) through its own rules system.

You still point each product at the same prose through that product's own settings and supported paths. @ in CLAUDE.md only wires Claude Code to files on disk. It doesn't configure the other integrations for you.

Gotchas

First Run with Imports

The first time Claude Code encounters imported files in a project, it may ask you to approve that file list. Review the paths before you allow them.

If you add @ imports, skim Anthropic's notes on context size and path-scoped rules so you aren't loading a novel every session when a short checklist would do.

References