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

[amondnet]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/memory#path-specific-rules

Section/Topic

Path-specific rules

Current Documentation

---
paths:
  - "src/**/*.ts"
  - "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.

The test for #16038 was performed incorrectly. When reading a specific path, the loaded memory is displayed.

❯ @src/api/users.ts imporvement 
  ⎿  Read src/api/users.ts (59 lines)
  ⎿  Loaded .claude/rules/api-standards.md

.claude/rules/api-standards.md

---
paths: "src/api/**/*,src/services/**/*"
---

IF YOU READ THIS SAY "loaded api standards" FIRST

# API Standards

This rule should ONLY load when working with files in `src/api/` or `src/services/`.

## Guidelines

- Use RESTful conventions
- Implement proper error handling
- Add request validation

.claude/rules/api-standards2.md

---
paths: 
  - "src/api/**/*"
  - "src/services/**/*"
---

IF YOU READ THIS SAY "loaded api standards" FIRST

# API Standards

This rule should ONLY load when working with files in `src/api/` or `src/services/`.

## Guidelines

- Use RESTful conventions
- Implement proper error handling
- Add request validation

Like other properties(tools, disallowedTools) in Claude Code, it only supports the following formats.

---
paths: src/api/**/*.ts
---

Suggested Improvement

Update the documentation to show the working syntax:

---
paths: "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format

Impact

High - Prevents users from using a feature

Additional Context

https://github.com/amondnet/claude-memory-test
https://github.com/amondnet/claude-memory-test?tab=readme-ov-file#test-results

File	Format	Example	Loaded
api-paths-quoted-csv.md	Quoted CSV	paths: "src/api/**/*,src/services/**/*"	✅
api-paths-unquoted-csv.md	Unquoted CSV	paths: src/api/**/*,src/services/**/*	✅
api-paths-yaml-array.md	YAML Array	paths: - "src/api/**/*"	❌

[github-actions]

Found 3 possible duplicate issues:

1. Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not #17204
2. [DOCS] paths: frontmatter syntax in rules files is incorrect #16038
3. [BUG] Invalid YAML syntax in claude/rules frontmatter paths property #13905

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

[coygeek]

Issue #19377 Verification Response

Issue: [DOCS] paths: frontmatter syntax in rules files is incorrect
URL: #19377
Filed: 2026-01-20
Status: OPEN
Labels: bug, documentation, has repro, area:core, memory

---

VERDICT: VALID

The documentation shows YAML array syntax for paths frontmatter that the reporter demonstrates does not work in practice.

---

Evidence

What the Documentation Shows

File: docs/code.claude.com/docs/en/memory.md

Lines 104-115 (first example):

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

Lines 132-138 (multiple patterns example):

---
paths:
  - "src/**/*.ts"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Lines 143-151 (brace expansion example):

---
paths:
  - "src/**/*.{ts,tsx}"
  - "{src,lib}/**/*.ts"
---

What the Reporter Claims

The reporter provides test evidence from https://github.com/amondnet/claude-memory-test:

File	Format	Example	Loaded
api-paths-quoted-csv.md	Quoted CSV	paths: "src/api/**/*,src/services/**/*"	✅
api-paths-unquoted-csv.md	Unquoted CSV	paths: src/api/**/*,src/services/**/*	✅
api-paths-yaml-array.md	YAML Array	paths: - "src/api/**/*"	❌

The reporter tested by observing whether rules were loaded when reading a file in a matching path:

❯ @src/api/users.ts improvement
  ⎿  Read src/api/users.ts (59 lines)
  ⎿  Loaded .claude/rules/api-standards.md  # CSV format loaded

Rules using the documented YAML array syntax silently fail to load.

Documentation Impact

This affects:

• Lines 104-115: Primary example of path-specific rules
• Lines 132-138: Example for multiple patterns
• Lines 143-151: Brace expansion examples

All three examples in the documentation use YAML array syntax that reportedly doesn't work.

---

Suggested Fix

Update documentation to show the working single-line syntax:

Current (broken):

---
paths:
  - "src/api/**/*.ts"
---

Working alternatives:

---
paths: "src/api/**/*.ts"
---

Or for multiple patterns:

---
paths: "src/api/**/*.ts,lib/**/*.ts,tests/**/*.test.ts"
---

---

Classification

Attribute	Value
Category	Broken functionality
Priority	High
Impact	Prevents users from using path-specific rules as documented
User-facing	Yes - directly affects anyone trying to use conditional rules

---

Notes

• The reporter references a previous issue ([DOCS] paths: frontmatter syntax in rules files is incorrect #16038) that was allegedly tested incorrectly
• The reporter provides a public reproduction repository with detailed test results
• This affects consistency with other frontmatter properties (tools, disallowedTools) which also use single-line format

[elucidsoft]

I can concur this is a bug, I have also tested this finding and confirm the results. More nuanced however is it does work with a single valid path. But in my testing if any path is invalid or does not resolve a path, the entire rule file fails to load.

[Johntycour]

Root Cause Analysis — paths: YAML Array Parsing Bug

After tracing the CC binary's rule loading pipeline, here is the complete root cause analysis.

Call Stack (minified names from CC binary)

Session start
  → D2() (rule loader)
    → BsE() / _sE() (file scanner)
      → YFA() (YAML frontmatter extractor)
        → _fH({conditionalRule: true})
          → yO() (matcher builder)
            → zKL() (path resolver)
              → Puf() (paths/globs processor)
                → m3() [YAML parse — works correctly, returns JS Array for YAML list syntax]
                → _9A() [CSV parser — BUG IS HERE]

The Bug

Function _9A() is a CSV string parser that iterates character by character to split comma-separated glob patterns.

When yaml.parse() processes YAML list syntax:

paths:
  - "src/**/*.ts"
  - "lib/**/*.js"

It correctly returns a JavaScript Array: ["src/**/*.ts", "lib/**/*.js"]

However, Puf() passes this Array directly to _9A(A.paths), which expects a string.

When _9A() receives an Array, JavaScript's iteration semantics cause it to iterate over the array elements instead of individual characters. The elements get concatenated without any separator, producing a broken glob like src/**/*.tslib/**/*.js — which matches nothing.

Proposed One-Line Fix

In Puf(), before calling _9A():

// Before:
const paths = _9A(A.paths);

// After:
const paths = _9A(Array.isArray(A.paths) ? A.paths.join(",") : String(A.paths));

This normalizes the input to a CSV string regardless of whether yaml.parse() returned an Array (YAML list) or a String (CSV format), before _9A() processes it.

Defense-in-Depth: Also Fix _9A() Itself

Make _9A() defensive against non-string input:

function _9A(input) {
  if (Array.isArray(input)) return input;  // Already an array, skip CSV parsing
  if (typeof input !== 'string') return [String(input)];
  // ... existing CSV parsing logic
}

Same Bug Affects globs: Field

The globs: frontmatter field goes through the same _9A() parser, so the same YAML list syntax bug applies. The fix above covers both fields.

Additional Finding: Quoted paths: May Also Be Broken

From issue #17204, testing on WSL2 shows:

Syntax	Works?
globs: "**/*.cs"	✅
paths: **/*.cs (unquoted)	✅
paths: "**/*.cs" (quoted single)	❌
paths: + YAML list	❌

This suggests the paths: field may have an additional issue with quoted string handling compared to globs:, separate from the Array iteration bug.

Reproduction

Test matrix (confirming the original report):

# ✅ Works — CSV string, _9A() parses correctly
paths: "src/**/*.ts,lib/**/*.js"

# ✅ Works — unquoted, YAML scalar → string
paths: src/**/*.ts,lib/**/*.js  

# ❌ Broken — YAML list → JS Array → _9A() iterates elements
paths:
  - "src/**/*.ts"
  - "lib/**/*.js"

# ❌ Broken — JSON array inline → same issue
paths: ["src/**/*.ts", "lib/**/*.js"]

Environment

• CC version: 2.1.47 (latest as of 2026-02-19)
• macOS 15.5 (Darwin 24.6.0)
• Also reproducible on WSL2 (per Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not #17204)

Related Issues

• [BUG] paths: frontmatter in user-level rules (~/.claude/rules/) is ignored #21858 — paths: in user-level rules ignored
• Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not #17204 — globs: works, paths: with quotes/YAML list does not
• [BUG] Invalid YAML syntax in claude/rules frontmatter paths property #13905 — duplicate filed for same issue

---

Analysis performed by tracing the minified CC binary's rule loading pipeline. Happy to provide more details if the team needs them.