Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix CLAUDE.md: @ imports and prose paths resolve against different roots, causing silent load failures

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

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.

Error Message

which doesn't exist. No error, no warning. /context shows the file is absent. No error was produced at session start.

Root Cause

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.

RAW_BUFFERClick to expand / collapse

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.
  2. Document the resolution rule prominently in the CLAUDE.md reference docs — specifically call out the .claude/CLAUDE.md case.
  3. 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.
  4. 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.

extent analysis

TL;DR

To fix the silent failure of @path/to/file.md imports in CLAUDE.md, prefix the path with ../ to make it relative to the CLAUDE.md file.

Guidance

  • The issue arises from the inconsistent resolution rules for @ imports and plain prose paths in CLAUDE.md, with @ imports being relative to the containing file and plain prose paths being relative to the working directory.
  • To mitigate this, users can prefix @ import paths with ../ to ensure they are resolved relative to the CLAUDE.md file.
  • Emitting a warning when an @ import path doesn't resolve can help prevent silent failures.
  • Documenting the resolution rule prominently in the CLAUDE.md reference docs can also help users understand the expected behavior.

Example

For example, if CLAUDE.md is located at ./.claude/CLAUDE.md and you want to import a file at insights/some-file.md relative to the repo root, you can use the path ../insights/some-file.md instead of @insights/some-file.md.

Notes

This fix assumes that the desired behavior is to resolve @ imports relative to the CLAUDE.md file. If the desired behavior is to resolve them relative to the working directory, a different approach may be needed.

Recommendation

Apply the workaround of prefixing @ import paths with ../ to ensure consistent resolution relative to the CLAUDE.md file. This approach is straightforward and effective, but it may not address the underlying issue of inconsistent resolution rules.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#task chaining#parallel task#integration issue#index setup#retrieval issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING