[Bug] Path-based rules in ~/.claude/rules/ only match files under primary working directory

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

User-level rules with paths: frontmatter in ~/.claude/rules/ only match files that are children of the primary working directory (the directory from which Claude Code was launched). Files in other directories — including those added via --add-dir — are silently ignored by the path matching mechanism.

This affects both the main agent and teammates (agents spawned via Task with team_name) equally — it is not specific to agent teams.

Context

• User has rules in ~/.claude/rules/ with paths: patterns (e.g., *.vue, **/*.ts, **/SKILL.md)
• Working across multiple repositories in a single Claude Code session
• Using agent teams (teammates) that read/write files in different repositories

Full Reproduction

1. Setup — Create a rule and two repos

# Create a simple path-based rule at user level
mkdir -p ~/.claude/rules/
cat > ~/.claude/rules/vue-component.md << 'INNEREOF'
---
paths:
  - "*.vue"
---
# Vue Component Convention
Always use <script setup lang="ts"> and never use Options API.
INNEREOF

# Create two separate repos
mkdir -p ~/repo-a && cd ~/repo-a && git init
mkdir -p ~/repo-b && cd ~/repo-b && git init

2. Test A — Launch from repo-a, create .vue in both repos

cd ~/repo-a
claude

Then in Claude Code:

Create a file ~/repo-a/test.vue with <template><div>Hello</div></template>

Expected: Rule vue-component.md loads via system-reminder on Read.
Actual: Rule loads correctly.

Then:

Create a file ~/repo-b/test.vue with <template><div>Hello</div></template>

Expected: Rule vue-component.md loads via system-reminder on Read.
Actual: No rule loaded. The file is outside the primary working directory.

3. Test B — Launch from home, both repos work

cd ~/
claude

Then in Claude Code:

Create a file ~/repo-a/test.vue with <template><div>Hello</div></template>

Rule loads.

Create a file ~/repo-b/test.vue with <template><div>Hello</div></template>

Rule loads. Both repos are children of ~/, so both match.

4. Test C — --add-dir does not fix it

cd ~/repo-a
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/repo-b

Then:

Create a file ~/repo-b/test.vue with <template><div>Hello</div></template>

Expected: Rule loads (repo-b is an additional directory).
Actual: No rule loaded. --add-dir loads CLAUDE.md from additional dirs but does not extend rule path matching.

5. Test D — Bash cd does not fix it

cd ~/repo-a
claude

Then in Claude Code:

Run: cd ~/repo-b
Create a file ~/repo-b/test.vue with <template><div>Hello</div></template>

Expected: Rule loads (shell CWD is now repo-b).
Actual: No rule loaded. Bash cd is decoupled from rule matching.

Cleanup

rm -rf ~/repo-a ~/repo-b
rm ~/.claude/rules/vue-component.md

Test Results Summary

All tests below were run with both the main agent and teammates — results are identical for both.

Basic path matching — CWD = ~/projects/config-repo/

| Test | File Location | Rules Loaded |
|------|--------------|--------------|
| 1 | ~/projects/config-repo/components/Button.vue (in CWD) | 2 (vue-component + project CLAUDE.md) |
| 2 | ~/work/frontend/src/views/Home.vue (external) | 0 |
| 3 | ~/projects/config-repo/skills/example/SKILL.md (in CWD) | 2 (skill-authoring + project CLAUDE.md) |
| 4 | ~/work/frontend/src/app.controller.ts (external) | 0 |

Bash cd has no effect

| cd Before Read/Write | File Location | Rules Loaded |
|---------------------|--------------|--------------|
| cd ~/work/frontend/src/ | ~/work/frontend/src/views/Home.vue | 0 |
| cd ~/ | ~/work/frontend/src/views/Home.vue | 0 |
| cd ~/projects/config-repo/rules/ | ~/projects/config-repo/components/Button.vue | 2 |

--add-dir does not extend rule matching

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ~/work/frontend

| Additional Dir | File Location | Rules Loaded |
|---------------|--------------|--------------|
| --add-dir ~/work/frontend | ~/work/frontend/src/views/Home.vue | 0 |
| --add-dir ~/work/frontend | ~/projects/config-repo/components/Button.vue | 2 |

Note: CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 does load CLAUDE.md from additional directories, but does not extend the scope for path-based rule matching.

Workaround — Launch from ~/ (home)

| File Location | CWD at Launch | Rules Loaded |
|--------------|---------------|--------------|
| ~/projects/config-repo/components/Button.vue | ~/ | 2 |
| ~/work/frontend/src/views/Home.vue | ~/ | 3 (2 user rules + frontend CLAUDE.md) |

When launched from ~/, all files are children of CWD → all rules match everywhere.

Key Observations

1. Path-based rules only match files under CWD at launch time — files in other directories are silently ignored
2. Bash cd has no effect — shell CWD is completely decoupled from rule matching
3. --add-dir does not extend rule matching scope — it loads CLAUDE.md from additional directories but not path-based rules
4. Hooks (PreToolUse) fire correctly everywhere — only rules are affected
5. Affects both main agent and teammates equally — not specific to agent teams
6. No error or warning — rules fail silently, so users have no idea conventions are being ignored

Expected Behavior

User-level rules in ~/.claude/rules/ with paths: patterns should match on any file read/written by Claude Code, regardless of which directory the file is in. These are user-level rules, not project-level — they should apply globally.

Alternatively, --add-dir should extend the rules path matching scope to include files in additional directories.

Impact

• Cross-repo workflows broken — when working across repositories, user-level rules are silently ignored for files outside the primary CWD
• Agent teams lose conventions — teammates working on external repos have no path-based rules active
• Silent failure — no warning that rules are not matching, conventions violated without any feedback
• Poor workaround — launching from ~/ makes rules work everywhere but loses project-level focus

Suggested Fix

1. (preferred) User-level path-based rules should match globally, regardless of file location. These rules are explicitly placed at user level (~/.claude/rules/), not project level — the user intent is for them to apply everywhere.
2. --add-dir should extend the rule matching scope to additional directories. If a directory is explicitly added via --add-dir, path-based rules should match files in that directory tree, not just CLAUDE.md discovery.
3. New env variable CLAUDE_CODE_GLOBAL_RULES_MATCHING=1 (or CLI flag --global-rules) to opt into global matching for user-level rules, for users who want cross-repo rule matching without launching from ~/.
4. At minimum, emit a warning when a rule would have matched a file's path pattern but was skipped due to CWD scoping. Silent failure is the worst outcome — users have no way to know their conventions are being ignored.

Environment

• Claude Code CLI v2.1.41 (latest)
• macOS (likely affects all platforms)

---

Thanks to the Claude Code team for the incredible work on rules, hooks, and agent teams — these features are game-changers. This bug report comes from a place of heavy usage and appreciation. Keep it up! 🙏