[DOCS] Headless print-mode docs do not explain nested CLAUDE.md and conditional rules loading

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/headless

Section/Topic

Instruction-loading behavior in print mode (claude -p), specifically for nested CLAUDE.md and path-scoped .claude/rules/*.md files.

Current Documentation

Headless docs define print mode usage:

To run Claude Code programmatically from the CLI, pass -p with your prompt and any CLI options.

Memory docs explain instruction/rule loading generally:

CLAUDE.md files in subdirectories load on demand when Claude reads files in those directories.

Rules can be scoped to specific files using YAML frontmatter with the paths field.

What's Wrong or Missing?

Changelog v2.1.69 indicates there was a print-mode-specific bug around conditional .claude/rules/*.md and nested CLAUDE.md loading, but headless docs do not describe how these files should load in claude -p mode.

Users automating with print mode need explicit, mode-specific behavior to reason about instruction application.

Suggested Improvement

Add a "Instruction loading in print mode" subsection in headless docs that states:

• Whether nested CLAUDE.md is loaded during claude -p
• Whether paths:-scoped rules are evaluated in print mode
• What triggers lazy loading in non-interactive runs
• A minimal example showing expected behavior

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/headless | Print mode behavior should be documented here |
| https://code.claude.com/docs/en/memory | Describes nested CLAUDE.md and paths: rules, but not print-mode-specific behavior |

Total scope: 2 pages affected

Source: Changelog v2.1.69

Exact changelog entry:

Fixed conditional .claude/rules/*.md files (with paths: frontmatter) and nested CLAUDE.md files not loading in print mode (claude -p)