The @path Import Syntax

A single, ever-growing CLAUDE.md becomes hard to read and burns context tokens on every turn. The @path import syntax lets you split rules into focused files and pull them in by reference.

Instead of pasting 400 lines of coding standards directly, you write one line that imports them. The result: a lean top-level file that stays readable while the details live in dedicated, reusable modules.

An import is just a line beginning with @ followed by a path. When Claude Code loads your CLAUDE.md, it inlines the referenced file's contents at that point.

Use a relative path from the file doing the importing. The example below pulls a shared coding-style module into the project memory.

Paths are resolved relative to the file that contains the import. @./standards/coding-style.md looks for a standards/ folder next to your CLAUDE.md.

• @./standards/coding-style.md — sibling subfolder (most common, VCS-friendly)
• @../shared/rules.md — parent directory
• Keep imports inside the repo so teammates who clone the project get the same modules.

Group related rules into small files under a standards/ directory, then import each one. Each module has a single responsibility, so you can update testing rules without touching style rules.

This mirrors good code design: small, named, composable units beat one giant file.

CLAUDE.md has layers: user-level ~/.claude/CLAUDE.md (personal, NOT shared via VCS), project-level ./CLAUDE.md (shared via VCS), and directory-level files scoped to a subtree.

@path imports work within any of these. Because a user-level file is not shared, new teammates miss it — so put rules that the whole team needs in a project-level file (and its imports), not in your personal one.

The whole point of importing @./standards/coding-style.md from a project CLAUDE.md is that the path and the file both live in version control. Clone the repo, and the standards come with it.

Contrast that with a rule buried in ~/.claude/CLAUDE.md: it only exists on your machine. A teammate's Claude session would never see it. Modular project imports keep guidance consistent across the team.

Anything you @import from CLAUDE.md is part of the context on every turn the file is active. That is great for rules that always apply — naming conventions, commit format, review expectations.

But it also means every imported line costs tokens continuously. Import what is always relevant; for rules that only matter sometimes, there is a better tool (next scene).

If a rule only applies while editing certain files, don't bloat the always-loaded context with it. Use .claude/rules/ files with YAML frontmatter instead.

A paths glob makes the rule load only when you edit a matching file — saving context and tokens versus a monolithic always-on CLAUDE.md.

Two complementary mechanisms:

• @path imports in CLAUDE.md — for rules that should always be in context (project-wide standards). Modularizes the file; everything still loads every turn.
• .claude/rules/ with paths frontmatter — for rules that should load conditionally, only when editing matching files. Saves tokens.

An architect picks based on whether the guidance is universal or file-scoped.

You can import several modules from one CLAUDE.md, mixing concerns cleanly. Keep the top file as an index that explains structure, and let each import carry the detail.

Because imports are plain references, you can reorder, add, or remove a module without rewriting the rest — exactly the maintainability win modular config is meant to deliver.

You don't have to hand-edit memory files. The /memory command edits CLAUDE.md, and those changes persist across sessions — handy for adding a new @import line as your standards grow.

Keep the imported modules themselves under version control so the persisted rules and their references stay in sync for everyone on the team.

Apply what you've learned about @path imports and the CLAUDE.md hierarchy.

Key takeaways:

• @path imports (e.g. @./standards/coding-style.md) modularize CLAUDE.md; paths resolve relative to the importing file.
• Imported content loads on every turn — use it for universal, always-relevant rules.
• Put shared standards in a project-level CLAUDE.md (shared via VCS), not user-level (~/.claude/, personal and missed by teammates).
• For rules that apply only to certain files, prefer .claude/rules/ with a paths frontmatter glob to save context and tokens.
• /memory edits CLAUDE.md and persists changes across sessions.