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

Status Fixed / completed
Maintainer reply None cached
Activity 11 comments · opened Jan 8, 2026 · closed Aug 19, 2026

Preflight Checklist

  • [x] I have searched existing issues and this hasn't been reported yet
  • [x] This is a single bug report (please file separate reports for different bugs)
  • [x] 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
  1. Create a global rule (works correctly):

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

  1. Create a path-scoped rule:

```bash
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
```

  1. Create a matching source file:

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

  1. Start Claude Code: claude
  1. Run /context - observe that only the global rule appears under "Memory files", not the path-scoped rule
  1. Ask Claude to read the matching file: "Read src/api/routes.ts"
  1. 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.

View original on GitHub ↗

10 Comments

github-actions[bot] · 7 months ago

Found 1 possible duplicate issue:

  1. https://github.com/anthropics/claude-code/issues/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 · 7 months ago

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 · 7 months ago

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 · 7 months ago

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

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

MH4GF · 7 months ago

Using brace expansion in a single path entry works:

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

# Works
paths:
  - "{src,lib}/**/*"
abohannon · 7 months ago
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 · 6 months ago

+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!

ryanshepps · 6 months ago

Adding another data point: multiple paths: entries fail for me, single entry with brace expansion works.

Fails:

```
paths:

  • "**/*.rs"
  • "**/Cargo.toml"
  • "**/Cargo.lock"
  • "**/{clippy,rustfmt}.toml"

  Works:

paths:

  • "**/*.{rs,toml,lock}"

My setup uses user-global rules in ~/.claude/rules/ (not project-level), and the rule files are symlinks. The three rules without paths: frontmatter in the same directory load fine. Claude Code v2.1.34, macOS.
jpitchell · 6 months ago
Adding another data point: multiple paths: entries fail for me, single entry with brace expansion works. Fails: `` paths: - "**/*.rs" - "**/Cargo.toml" - "**/Cargo.lock" - "**/{clippy,rustfmt}.toml" ` Works: ` paths: - "**/*.{rs,toml,lock}" `` My setup uses user-global rules in ~/.claude/rules/ (not project-level), and the rule files are symlinks. The three rules without paths: frontmatter in the same directory load fine. Claude Code v2.1.34, macOS.

Confirming that this is the only way I can get path-specific rules to apply for me as well.

Anthropic's docs on this topic are misleading as they show examples with multiple path entries on different lines: https://code.claude.com/docs/en/memory#glob-patterns

alonkashtan · 5 months ago

I have the same problem. In addition to it working only with a single path, it works only within the IDE (vscode in this case) if I have opened at least one file matching the path since I started claude code within the IDE terminal. It doesn't work at all in an external terminal.

Showing cached comments. Read the full discussion on GitHub ↗