What it does
CLAUDE.md files can import instructions from other CLAUDE.md files using @filename syntax. This lets you compose project rules from multiple scopes: parent-level instructions (team conventions), user-level guidance (your personal workflow), and project-specific rules (this repo's tech stack). Instead of copying the same rules into every project, you write them once and reference them with @ imports.
When to use it
Three-tier CLAUDE.md hierarchy:
Parent CLAUDE.md (~/.claude/CLAUDE.md) — Team-wide rules that apply to every project: commit message format, code-review standards, linting rules, security baseline.
User CLAUDE.md (~/.claude/projects/CLAUDE.md) — Your personal workflow preferences: model choice, response style, when to ask before pushing, which tools you trust. Persists across all projects you work on.
Project CLAUDE.md (repo/CLAUDE.md) — This specific codebase: tech stack (Next.js 16, Supabase, Stripe), security rules (rate limiting on Claude routes), styling system (CSS tokens, no Tailwind), feature workflow (write TODO.md first). Checked into git so the team sees it.
When a conflict arises (parent says "always ask before push", project says "commit autonomously on content changes"), project wins. Specificity matters — the closer the rule to the code, the higher its priority.
Keep memory tight. Don't import rules you can derive by reading the code. Don't import things that change weekly (sprint goals, deployment state, person assignments). Import only lasting conventions that surprise a reader — the hidden constraints and tradeoffs unique to this codebase.
Try it yourself
Create a parent CLAUDE.md in ~/.claude/CLAUDE.md with your team's standard commit format or code-review rubric. Then in a project CLAUDE.md, add @CLAUDE.md at the top to inherit those rules, and layer project-specific overrides below. Check that Claude Code picks up both sets of rules by asking it a question about the code and watching it cite both tiers.
Gotchas
Import cycles break silently — if parent imports user and user imports parent, the second read is skipped. Resist the urge to share everything; keep the hierarchy one-way: parent → user → project.
Memory bloat — every import adds to context size. If you import a 2KB team CLAUDE.md into 50 projects, that's 100KB of redundant context per session. Instead, import only the essential rules; leave stylistic preferences and explanations in the source file, not imported copies.
@filename with no directory assumes the same folder. To import from parent, use the full path: @/home/user/.claude/CLAUDE.md. Relative imports (@../CLAUDE.md) don't work across the filesystem.
Precedence is literal-read order, then scope. If you import @CLAUDE.md and then write a conflicting rule in the same file, the local rule wins because it's read last. But if project CLAUDE.md conflicts with user CLAUDE.md (via import), project wins by scope.
Try it yourself
Type the command in the fake terminal. Nothing leaves your browser.