[BUG] paths: frontmatter on a USER-level rule (~/.claude/rules/) silently disables it — loads at neither session_start nor path_glob_match
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report
- [x] I am using the latest version of Claude Code
What's Wrong?
A paths: key on a rule in ~/.claude/rules/ (user scope) causes the rule to be silently dropped entirely. It lands in a dead zone:
- It is not loaded at
session_start, because thepaths:key marks it conditional. - It is never loaded by
path_glob_match, because user scope appears not to be evaluated for glob matching at all.
The result is a rule file that exists, is syntactically valid, and has zero effect — with no warning, no error, and no indication in /context.
Project-level path-scoped rules work correctly. This is specific to user scope.
Repro
- Create
~/.claude/rules/python.md:
---
paths:
- "**/*.py"
---
# Python conventions
- line-length = 100
- Create
~/.claude/rules/_loadtest.mdwith nopaths:key and any content. - Register the
InstructionsLoadedhook in~/.claude/settings.json:
{
"hooks": {
"InstructionsLoaded": [
{ "hooks": [ { "type": "command",
"command": "jq -c '{file:.file_path,scope:.memory_type,why:.load_reason,globs:.globs}' >> /tmp/instructions-loaded.log" } ] }
]
}
}
- Restart Claude Code, then read any
.pyfile inside a project.
Observed
session_start events — only the rule without paths: loads:
User session_start /Users/robsherman/.claude/CLAUDE.md
User session_start /Users/robsherman/.claude/rules/_loadtest.md
~/.claude/rules/python.md appears nowhere in the log, under any load_reason.
The same log, from the same session, shows project-scoped path matching working correctly on the very same file read:
Project path_glob_match <repo>/.claude/rules/database-policy.md
globs=["src/db/**/*.py","src/models/**/*.py","src/repositories/**/*.py","src/schemas/**/*.py","alembic"]
Nine Project loads, two User loads, zero User + path_glob_match. Reading alembic/env.py matched a project rule's globs and fired; the user rule's **/*.py and a second user rule's **/alembic/** matched the identical path and did not.
What Should Happen
Either:
paths:works at user scope, and the rule loads on a matching file read (this is what the docs imply — see below); orpaths:is unsupported at user scope, in which case the rule should load unconditionally rather than vanishing, and ideally warn.
Silently loading at neither end is the worst of the three outcomes — the user believes a convention is in force when nothing is.
Documentation conflict
https://code.claude.com/docs/en/claude-directory lists rules/*.md with scope "Project and global" and description "Topic-scoped instructions, optionally path-gated" — pairing global scope with path-gating in a single row, which reads as support.
Meanwhile https://code.claude.com/docs/en/memory documents paths: entirely under "Place markdown files in your project's .claude/rules/ directory", and its "User-level rules" section never mentions paths: at all. So the behavior is neither documented as supported nor as unsupported, while one table implies it works.
Additionally, /context under Memory files does not appear to list rules at all, so there is no way to notice the rule is missing without the InstructionsLoaded hook. debug-your-config says to "Run it first to confirm whether your CLAUDE.md, rules, or skill descriptions are present at all" — but rules don't show up in that list.
Related but distinct
- #16853 — same symptom at project scope with nested subdirectories. Project-level path matching works in my testing (evidence above), so this is a different case.
- #16299 — the inverse symptom (path-scoped rules loading globally when they shouldn't).
Neither covers user scope.
Environment
- Claude Code 2.1.233
- macOS (Darwin 25.5.0)
--setting-sourcesnot set (defaults touser,project,local)- No
claudeMdExcludesconfigured
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗