Claude Code gives you two different ways to pull extra context into a session automatically, and I assumed they composed. They don’t.
The Setup
@imports - reference a file with@path/to/file.md, and Claude auto-loads the full contents of that file into context.- Path-scoped rules - a rule file with frontmatter that targets specific paths, so the rule only applies when you’re actually working in a file covered by that path.
Combine the two and you’d expect to get the best of both: a rule that’s conditionally loaded based on where you’re working, that also pulls in a full reference doc via @ when it fires. That’s exactly what I wanted - a way to attach a complete doc to context, but only when it’s relevant.
The Gotcha
It doesn’t work that way. An @ import is unconditional - it loads every time, full stop, regardless of whether the path-scoped rule it’s sitting inside of would have matched or not. The path scoping on the rule doesn’t extend to anything you @ import inside it. So the moment you add an @ import to a path-scoped rule, you’ve quietly made that content load everywhere, all the time, which defeats the entire reason you scoped the rule in the first place.
Nothing warns you about this. The rule’s frontmatter still looks like it’s doing its job, and it’s easy to assume the @ import inherited the same scoping.
The Workaround
The only way I’ve found to get conditional, full-doc inclusion is to skip rules entirely and drop a CLAUDE.md file directly in the folder you want it scoped to, with the @ import inside it. Claude Code loads CLAUDE.md based on which directory you’re actually working in, so the import effectively becomes scoped by folder structure instead of by rule frontmatter.
It’s not quite as flexible as a glob-based path rule, but it’s the only version of “load this doc, but only in this part of the codebase” that currently works.