Documentation: .claude/rules/ frontmatter format incorrect - globs works, paths with quotes/YAML list does not

[dheeraj5612]

Summary

The documentation for .claude/rules/ frontmatter is incorrect or incomplete. After extensive testing, the documented paths: format does not work in several configurations, while the undocumented globs: format works reliably.

Environment

• Claude Code CLI
• WSL2 (Linux on Windows)
• Project with .claude/rules/ directory containing multiple rule files

Testing Methodology

Created multiple test files with different frontmatter formats and checked /memory output:

Format	Loads?
No frontmatter (unconditional)	YES
globs: "**/*.cs"	YES
paths: **/*.cs (unquoted)	YES
paths: "**/*.cs" (quoted)	NO
paths: + YAML list	NO

Expected Behavior

Based on documentation and GitHub issues, this should work:

---
paths:
  - "**/*.cs"
  - "**/Controllers/**"
---

Actual Behavior

Only these formats work:

---
globs: **/*.cs, **/Controllers/**
---

Impact

Users following the documentation will have non-functional path-scoped rules with no error messages indicating why rules are not loading. This is a silent failure that is very difficult to debug.

Suggested Fix

1. Update documentation to show the working format (globs:)
2. Or fix the parser to support the documented paths: formats

Workaround

Use globs: with comma-separated unquoted patterns:

---
globs: pattern1, pattern2, pattern3
---

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] paths: frontmatter syntax in rules files is incorrect #16038
2. [BUG] Invalid YAML syntax in claude/rules frontmatter paths property #13905
3. [BUG] Path-scoped rules in .claude/rules/ not automatically loaded when working with matching files #16853

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

[tazbytes2019]

Tried workaround using globs: with comma-separated unquoted patterns:
Unfortunately all rules files .claude/rules/ are loaded into the system prompt at conversation start, regardless of whether the user is working with files matching those patterns.
Claude CLI in windows env

[amondnet]

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/**/*"	❌

[Johntycour]

Root cause analysis confirms your findings

I've traced the CC binary's rule loading pipeline and can confirm the behavior you documented.

Root Cause (detailed in #19377)

The paths: field is processed by _9A(), a CSV parser that iterates character by character. Three failure modes:

1. YAML Array → _9A() receives a JS Array, iterates elements not characters → broken concatenation
2. JSON inline array ["a", "b"] → same issue
3. Quoted single value → your finding that paths: "**/*.cs" fails while paths: **/*.cs works suggests an additional quoting issue specific to paths: vs globs:

Why globs: works but paths: doesn't with quotes

Both fields go through _9A(), but the paths: field likely has additional processing (path resolution in zKL()) that doesn't handle quoted strings properly. The quotes may be preserved in the path instead of being stripped, causing the glob to literally include " characters.

Proposed Fix

// In Puf(), before calling _9A():
const paths = _9A(Array.isArray(A.paths) ? A.paths.join(",") : String(A.paths));

Plus defensive handling in _9A() itself for non-string inputs.

See full analysis at: #19377 (comment)

[maxjeltes]

Confirmed working format for path-scoped lazy loading (v2.2.x, VSCode extension)

Did some systematic testing using an InstructionsLoaded hook to audit which rule files load and when. Here's what I found:

What does NOT work

Format	Result
paths: as YAML array with quoted strings	Rules either load eagerly at session start or not at all
paths: as YAML array without quotes	Same — does not lazy-load
globs: (comma-separated, unquoted)	Always loads eagerly at session start, even with alwaysApply: false
Simple directory paths (e.g. paths: app/javascript/)	Does not load at all

What WORKS

---
alwaysApply: false
paths: app/javascript/**/*.js, app/javascript/**/*.ts, spec/javascript/**/*
description: "..."
---

Key requirements:

• Use paths: (not globs:) as a single unquoted CSV line — not a YAML array, not quoted
• Include alwaysApply: false
• Both are required — paths: as CSV alone (without alwaysApply: false) still loaded eagerly

Audit log proof

Session start — only always-on rules load:

15:34:04 | Type: Project | Reason: session_start | File: .claude/rules/concerns.md
15:34:04 | Type: Project | Reason: session_start | File: .claude/rules/git-workflow.md
15:34:04 | Type: Project | Reason: include | File: AGENTS.md

After reading a matching .js file — path-scoped rule lazy-loads:

15:49:18 | Type: Project | Reason: path_glob_match | File: .claude/rules/frontend.md | Triggered by: app/javascript/debugtimeline/timeline_box.js | Globs: ["app/javascript/**/*.js", ...]

Audit hook setup

For anyone wanting to reproduce, add this to your ~/.claude/settings.json:

"hooks": {
  "InstructionsLoaded": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "bash ~/.claude/hooks/log-instructions.sh"
        }
      ]
    }
  ]
}

With ~/.claude/hooks/log-instructions.sh:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // "N/A"')
MEMORY_TYPE=$(echo "$INPUT" | jq -r '.memory_type // "N/A"')
LOAD_REASON=$(echo "$INPUT" | jq -r '.load_reason // "N/A"')
TRIGGER_FILE=$(echo "$INPUT" | jq -r '.trigger_file_path // "N/A"')
GLOBS=$(echo "$INPUT" | jq -r '.globs // "N/A"')
TIMESTAMP=$(date +"%H:%M:%S")
LOG_ENTRY="$TIMESTAMP | Type: $MEMORY_TYPE | Reason: $LOAD_REASON | File: $FILE_PATH"
[[ "$TRIGGER_FILE" != "N/A" && "$TRIGGER_FILE" != "null" ]] && LOG_ENTRY="$LOG_ENTRY | Triggered by: $TRIGGER_FILE"
[[ "$GLOBS" != "N/A" && "$GLOBS" != "null" ]] && LOG_ENTRY="$LOG_ENTRY | Globs: $GLOBS"
echo "$LOG_ENTRY" >> ~/.claude/instruction-load-audit.log
exit 0

Then tail -f ~/.claude/instruction-load-audit.log in a separate terminal to watch in real-time.