[DOCS] paths: frontmatter syntax in rules files is incorrect #16038
Description
Documentation Type
Incorrect/outdated documentation
Documentation Location
No response
Section/Topic
Path-specific rules (paths: YAML frontmatter in .claude/rules/*.md files)
Current Documentation
The docs currently say:
"Rules can be scoped to specific files using YAML frontmatter with the
pathsfield."
With this example:
---
paths: src/api/**/*.ts
---And additional examples showing:
- Brace expansion:
paths: src/**/*.{ts,tsx} - Comma-separated:
paths: {src,lib}/**/*.ts, tests/**/*.test.ts
What's Wrong or Missing?
The documented string syntax does not work. Rules using this syntax silently fail to load.
Tested and verified: Only YAML array syntax works.
Reproduction
- Create
~/.claude/rules/test-string.md:
---
paths: src/**/*.ts
---
# Test String
MARKER_STRING- Create
~/.claude/rules/test-array.md:
---
paths:
- "src/**/*.ts"
---
# Test Array
MARKER_ARRAY- Create test project with matching files:
mkdir -p /tmp/test-project/src
echo "const x = 1;" > /tmp/test-project/src/app.ts- Check which rules load:
cd /tmp/test-project
claude --print "Which MARKERS do you see? MARKER_STRING or MARKER_ARRAY?"Result: Only MARKER_ARRAY loads. The documented string syntax is ignored.
Full test matrix
| Syntax | Loaded? |
|---|---|
paths: src/**/*.ts |
NO |
paths: src/**/*.{ts,tsx} |
NO |
paths: {src,lib}/**/*.ts, tests/**/*.test.ts |
NO |
paths: **/*.test.ts |
NO |
paths:\n - "src/**/*.ts" |
YES |
Suggested Improvement
Update the documentation to show the working YAML array syntax:
---
paths:
- "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response formatFor multiple patterns:
---
paths:
- "src/**/*.ts"
- "src/**/*.tsx"
- "lib/**/*.ts"
---Or fix the implementation to accept the documented string syntax.
Impact
High - Prevents users from using a feature
Additional Context
- Claude Code version: 2.0.76
- Platform: Anthropic API
- OS: macOS (Darwin 25.1.0)
- Terminal: VS Code integrated terminal
- Tested: 2026-01-01
Note: claude --debug shows hooks, skills, and permissions loading, but does not show rules file loading or paths: frontmatter evaluation. Adding debug output for rules loading would help users troubleshoot this.