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:
- Tree lookup (automatic): Claude discovers CLAUDE.md files by walking up the directory tree from your cwd, loading each ancestor file it finds. You do nothing.
- Imports (explicit): inside any CLAUDE.md you write
@path/to/fileto pull another file's contents inline. You choose exactly what gets imported.
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:
- Relative & absolute paths both work. Relative paths resolve against the file containing the import — not your working directory.
- Home-dir imports:
@~/.claude/my-instructions.mdpulls from your home directory. This is the recommended way to share personal instructions across git worktrees (since a gitignoredCLAUDE.local.mdonly exists in the one worktree you made it in). - Recursion is allowed, up to a max depth of 4 hops. An imported file may itself import others, chaining up to four levels deep.
- Code spans and fenced code blocks are skipped. Import parsing ignores text inside
backticks and
```fences — so`@README`stays literal, while@READMEoutside backticks imports the file. - Imports don't save context. Imported files still load in full at launch — imports are for organization, not for reducing token cost.
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
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.
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
@path works inside code blocks." → Import parsing skips
Markdown code spans and fenced blocks. `@README` in backticks is literal; only a bare
@README imports.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.