[BUG] paths: frontmatter on a USER-level rule (~/.claude/rules/) silently disables it — loads at neither session_start nor path_glob_match

Status Open
Reported on v2.1.233
Maintainer reply None cached
Activity 1 comment · opened Aug 16, 2026

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 the paths: 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

  1. Create ~/.claude/rules/python.md:
---
paths:
  - "**/*.py"
---
# Python conventions
- line-length = 100
  1. Create ~/.claude/rules/_loadtest.md with no paths: key and any content.
  2. Register the InstructionsLoaded hook 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" } ] }
    ]
  }
}
  1. Restart Claude Code, then read any .py file 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:

  1. paths: works at user scope, and the rule loads on a matching file read (this is what the docs imply — see below); or
  2. paths: 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-sources not set (defaults to user,project,local)
  • No claudeMdExcludes configured

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗