[BUG] Path-scoped rules in `.claude/rules/` not automatically loaded when working with matching files

[BlondeLegion]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

Rules with paths: frontmatter in .claude/rules/ subdirectories are never automatically loaded into context when reading or editing files that match the specified glob patterns.

Setup:

• Global rules in .claude/rules/general/ (no paths: frontmatter) load correctly
• Path-scoped rules in other subdirectories like .claude/rules/api/, .claude/rules/services/ have paths: frontmatter but never load

Example rule file at .claude/rules/api/api-rules.md:

---
paths: src/api/**, lib/api/**
---

# API Rules

- Always validate request parameters
- Use structured error responses

Observation:
When running /context, only the general rules appear under "Memory files":

Memory files
└ .claude/CLAUDE.md: 3.8k tokens
└ .claude/rules/general/architecture.md: 2.5k tokens
└ .claude/rules/general/coding-standards.md: 535 tokens

The path-scoped rules (e.g., .claude/rules/api/api-rules.md) don't appear at all - not even as "available but not loaded."

When I then read a file that matches the path pattern (e.g., src/api/routes.ts), the path-scoped rule is still not injected into context.

What Should Happen?

When I read or edit a file matching a rule's paths: glob pattern, that rule should automatically be loaded into context. For example:

• Reading src/api/routes.ts should load .claude/rules/api/api-rules.md (matches src/api/**)
• The /context command should show path-scoped rules as available (perhaps with their path patterns)

Error Messages/Logs

No error messages. The rules are silently not loaded.

Steps to Reproduce

1. Create a project with Claude Code initialized

2. Create a global rule (works correctly):

   mkdir -p .claude/rules/general
   echo "# Global Rules\n\n- Always use TypeScript" > .claude/rules/general/global.md

3. Create a path-scoped rule:

   mkdir -p .claude/rules/api
   cat > .claude/rules/api/api-rules.md << 'EOF'
   ---
   paths: src/api/**
   ---
   
   # API Rules
   
   - Always validate input parameters
   - Return structured JSON errors
   EOF

4. Create a matching source file:

   mkdir -p src/api
   echo "export function handler() { return 'hello'; }" > src/api/routes.ts

5. Start Claude Code: claude

6. Run /context - observe that only the global rule appears under "Memory files", not the path-scoped rule

7. Ask Claude to read the matching file: "Read src/api/routes.ts"

8. Expected: The api-rules.md content should now be in context
   Actual: The rule is still not loaded; Claude has no awareness of the API rules

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

No response

Claude Code Version

v2.1.1

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

VS Code integrated terminal

Additional Information

This also does not work in the standard macOS terminal.

[github-actions]

Found 1 possible duplicate issue:

1. [Bug] VS Code Extension: Frontmatter Path Rules Not Working #16171

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[rosskevin]

I can confirm the same behavior (failing to load rules based on frontmatter paths) in the vscode plugin 2.1.3. When I asked cc to reflect on it and the conversation (this has happened repeatedly in many sessions), it responded with:

My Mistakes
I did NOT read .claude/rules/deprecation.md before starting this work, even though:

It has paths: "**/*.{ts,tsx}" which should apply to all the files I was editing
It explicitly lists the deprecation patterns I was trying to fix
It would have given me the correct migration path upfront

I put back deprecated props to "make it work" - a shortcut the user rightfully caught

Why I Didn't Read the Rules
Honestly, I don't have a good excuse. The rules file exists specifically for this scenario. I jumped into implementation without checking for guidance that was already there.

I will also note that after running /context, even after @'ing the file and having it reflect, it is not part of any of the Memory Files.

I also confirmed that deleting frontmatter paths makes it show up in new sessions.

[ynamiki-mediee]

I can confirm this issue. Here's additional data from my testing:

Environment:

• Claude Code: v2.1.7
• Platform: Linux (VS Code dev container)

Test Results:

Rule File (.claude/rules)	paths: Pattern	File Read	Loaded?
config/environment.md	src/config/**/*.ts	src/config/env.ts	Yes
database/drizzle.md	db/**/*.ts	db/schema/users.ts	No
database/drizzle.md	src/repositories/**/*.ts	src/repositories/users.ts	No
testing/jest.md	**/*.test.ts	__tests__/unit/lib/line/client.test.ts	No
i18n/translations.md	src/i18n/**/*.ts	src/i18n/request.ts	No

Only config/environment.md loaded correctly in my session, while other path-scoped rules with similar patterns failed. All rules use properly quoted YAML strings.

[amondnet]

When specifying multiple paths, you must enclose them in quotes.

paths: "src/api/**/*,src/services/**/*": Loaded
paths: src/api/**/*,src/services/**/*: Not Loaded

[MH4GF]

Using brace expansion in a single path entry works:

# Does NOT work
paths:
  - src/**/*
  - lib/**/*

# Works
paths:
  - "{src,lib}/**/*"

[abohannon]

Using brace expansion in a single path entry works:

Does NOT work

paths:

• src/**/*
• lib/**/*

Works

paths:

• "{src,lib}/**/*"

This isn't working for me. I made this change, opened a fresh CC session, opened a file that should be scoped, and it does not show in /context or /memory. When I ask Claude "What rules are in context right now?" it lists AGENTS.md, etc. that should be global but not the scoped paths.

However, when I ask CC to do some work on the file, I can see it pulling in the relevant rules files in the thinking logs (files still aren't listed in context or memory, though).

It would be great if we could have a more reliable way to determine what is being loaded into memory. I work at a large SaaS company with many squads working on the same codebase and being able to scope rules so they don't bloat the context window for all engineers is a must for us. Not being able to reliably debug this is definitely a headache.

[CN-liuzhiyang]

+1 on this issue. We're also experiencing this bug on Windows (Claude Code v2.1.29).

Our setup:

• Rule file: .claude/rules/lua-coding.md
• Path pattern: **/Script/Lua/**/*.lua
• Files being edited: workspace/game_repo/trunk_bjs/code/src/TXM/Package/Script/Lua/*.lua

The rules are never injected into context, even when directly editing files that match the glob pattern. This significantly impacts our workflow since we rely on path-scoped rules for language-specific coding standards.

Would appreciate an update on the timeline for a fix. Thanks!