paths field in ~/.claude/rules/ frontmatter not working - rules with paths are not loaded

Resolved 💬 3 comments Opened Jan 31, 2026 by ardge-yijyunlin Closed Jan 31, 2026

Environment

  • Claude Code version: 2.1.27
  • Platform: macOS (Darwin 25.2.0)

Expected Behavior

According to the official documentation, rule files with paths frontmatter should be conditionally loaded when working with matching files.

Example from documentation:

---
paths:
  - "**/*.ts"
  - "src/**/*"
---
# TypeScript-specific rules

The documentation states:

"The paths field supports standard glob patterns"

Actual Behavior

Rules with paths frontmatter are completely ignored and never loaded, even when working with files that match the glob patterns.

Steps to Reproduce

1. Create a rule file with paths frontmatter

File: ~/.claude/rules/languages/go-specific.md

---
paths:
  - "**/*.go"
  - "**/go.mod"
  - "**/go.sum"
---

# Go-specific rules
(custom rules content here)

2. Start a Claude Code session in a Go project

cd /path/to/go/project  # Contains .go files matching the paths pattern
claude

3. Work with Go files

Request Claude to modify or work with .go files in the project.

Expected: The rules defined in go-specific.md should be loaded and applied.

Actual: The rules are NOT loaded.

4. Comment out the frontmatter

Modify ~/.claude/rules/languages/go-specific.md:

<!-- ---
paths:
  - "**/*.go"
  - "**/go.mod"
  - "**/go.sum"
--- -->

# Go-specific rules
(same content)

5. Restart the session

Result: The rules ARE NOW loaded successfully.

Test Results

| Rule File | Has paths? | Loaded? |
|-----------|--------------|---------|
| ~/.claude/rules/core/file-operations.md | No | ✅ Yes |
| ~/.claude/rules/languages/go-specific.md | Yes | ❌ No |
| ~/.claude/rules/languages/go-specific.md | Commented out | ✅ Yes |
| ~/.claude/rules/environments/devcontainer.md | Yes | ❌ No |

Pattern: Any rule file with paths frontmatter fails to load.

Workaround

Comment out the YAML frontmatter:

<!-- ---
paths:
  - "**/*.go"
--- -->

This makes the rules load globally (losing the conditional loading feature).

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗