CLAUDE.md: @ imports and prose paths resolve against different roots, causing silent load failures

Summary

Within a single CLAUDE.md file, two path conventions coexist with
different resolution rules — and one of them fails silently:

• @path/to/file.md imports resolve **relative to the containing

CLAUDE.md file**.

• Plain prose paths (e.g. bullet lists instructing Claude to read

certain files on demand) are interpreted by the agent relative
to the working directory (repo root).

When CLAUDE.md lives at .claude/CLAUDE.md (a common layout that
keeps AI tooling out of the project root), @insights/foo.md
silently does not load — it looks for .claude/insights/foo.md,
which doesn't exist. No error, no warning. /context shows the
import never happened.

Reproduction

1. Place CLAUDE.md at ./.claude/CLAUDE.md.
2. Add @insights/some-file.md — a path written relative to repo root.
3. Start Claude Code, run /context.
4. Memory Files shows only CLAUDE.md (~2k tokens). The imported

file is absent. No error was produced at session start.

Fix: prefix with ../ (making the path relative to CLAUDE.md). Import
then loads correctly.

Why this is a trap

• Silent failure. There's no indication the import didn't resolve.

The file appears in the config, so the user assumes it's loaded.

• Inconsistency in the same file. The @ syntax and prose-path

syntax follow different rules, even though both appear as
"instructions to Claude about which files to load."

• Non-obvious base. Users reasonably expect paths in a project

config to be relative to the project root, not the config file's
own directory — especially when the config is tucked into .claude/.

Suggested fixes (pick one or more)

1. Emit a warning when an @ import path doesn't resolve.

Silent failure is the most surprising behavior.

1. Document the resolution rule prominently in the CLAUDE.md

reference docs — specifically call out the .claude/CLAUDE.md
case.

1. Unify resolution. Either make both conventions relative to

the containing file, or both relative to the working directory.
Two rules in the same file is a wart.

1. Allow a resolution hint (e.g. @@path or a top-of-file

directive) to opt into repo-root-relative imports.

Context

• Observed in Claude Code Opus 4.7 (1M context).
• CLAUDE.md at .claude/CLAUDE.md with ~10 @ imports to

zDev/ and insights/ at the repo root.

• User's project layout keeps AI tooling in dedicated folders

(.claude/, zDev/, insights/) — a clean separation that
this bug punishes.

---

*This issue was drafted and filed by a Claude Code session
(Opus 4.7, 1M context) operating in the affected repository.
The observation and diagnosis are Claude's; the GitHub account
is the repo owner's. Filing under this arrangement was explicitly
agreed — the origin is called out for transparency.*