D3 · Claude Code › Cluster 1 · Memory & CLAUDE.md

1.3 · Imports (@path) & Tree Lookup

@-imports & recursive discovery

CONCEPT Two ways CLAUDE.md pulls in more content

A CLAUDE.md rarely stands alone. There are two distinct composition mechanisms — don't confuse them:

CONCEPT The @path import syntax

Write @path/to/import anywhere in a CLAUDE.md and that file is expanded and loaded into context at launch, alongside the CLAUDE.md that references it. The rules that get tested:

⚠️ The first time a project uses external imports, Claude shows a one-time approval dialog listing the files. If you decline, imports stay disabled and the dialog won't reappear.
🔑 CLAUDE.local.md is increasingly superseded by home-dir imports. Instead of a gitignored local file that's stuck in one worktree, import @~/.claude/my-project-instructions.md so your personal notes follow you across all worktrees of the repo.

DIAGRAM Walk-up discovery + import expansion

flowchart TD CWD["cwd: foo/bar/"] --> W["Walk UP the tree"] W --> A["foo/bar/CLAUDE.md"] W --> B["foo/CLAUDE.md"] W --> R["…up to repo root / filesystem root"] A --> IMP{"Contains @path?"} IMP -->|"@docs/git.md"| E1["🟢 Expand inline"] E1 --> D2{"That file imports more?"} D2 -->|"yes, ≤ 4 hops"| E2["🟢 Keep expanding"] D2 -->|"depth 5"| STOP["🔴 Stop — max depth reached"] IMP -->|"`@README` in backticks"| LIT["Literal text, NOT imported"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; classDef mid fill:#e2e3f3,stroke:#6c63ff,color:#2a2a6a; class E1 ok; class E2 ok; class STOP bad; class LIT mid;

CODE Imports in practice

Reference files with @ anywhere in the file; wrap a path in backticks to mention it without importing.

# CLAUDE.md

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

## Additional instructions
- Git workflow: @docs/git-instructions.md   # relative to THIS file
- Absolute path also works: @/opt/team/standards.md

## Individual preferences (shared across worktrees)
- @~/.claude/my-project-instructions.md      # home-dir import

# To MENTION a path without importing it, wrap it in backticks:
Write `@README` in backticks and it stays literal — no import.
Common pattern: a repo that already has AGENTS.md for other tools creates a CLAUDE.md whose first line is @AGENTS.md, then adds Claude-specific notes below — one source of truth, no duplication.

TRADE-OFFS Splitting into imports vs. one flat file

✅ Split with @imports

  • Modular, easier for teams to maintain
  • Reuse shared files (@~/…) across worktrees
  • Keeps the main file readable

⚠️ Reality check

  • Imported files still load at launch — no context savings
  • To actually cut context, use path-scoped rules, not imports
  • External imports trigger a one-time approval prompt

EXAM TRAPS

Trap: "Imports reduce context/token usage." → They do not. Imported files load in full at launch. For context savings use path-scoped rules that load only for matching files.
Trap: "@path works inside code blocks." → Import parsing skips Markdown code spans and fenced blocks. `@README` in backticks is literal; only a bare @README imports.
Trap: "Relative import paths resolve from my working directory." → They resolve relative to the file containing the import, not cwd.
Trap: "Imports can nest infinitely." → Recursive imports are capped at a maximum depth of 4 hops.

PRACTICE

Q1 · How does Claude find CLAUDE.md without you pointing at it?

It walks up the directory tree from your cwd, loading every ancestor CLAUDE.md (and CLAUDE.local.md) it finds, concatenated root-down. Subdirectory files below cwd load on demand when Claude reads files there.

Q2 · Write an import that shares personal notes across all worktrees of a repo. Why this way?

@~/.claude/my-project-instructions.md. A gitignored CLAUDE.local.md only exists in the one worktree you created it in; a home-dir import is reachable from every worktree.

Q3 · You want to mention @config.yml in prose without importing it. How?

Wrap it in backticks: `@config.yml`. Import parsing skips code spans and fenced code blocks, so the text stays literal.