[DOCS] `paths:` frontmatter syntax in rules files is incorrect

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 paths field."

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

1. Create ~/.claude/rules/test-string.md:

---
paths: src/**/*.ts
---
# Test String
MARKER_STRING

1. Create ~/.claude/rules/test-array.md:

---
paths:
  - "src/**/*.ts"
---
# Test Array
MARKER_ARRAY

1. Create test project with matching files:

mkdir -p /tmp/test-project/src
echo "const x = 1;" > /tmp/test-project/src/app.ts

1. 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 format

For 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.