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

Still relevant as of 2026-03-28 after re-checking the current docs. This issue is partially resolved, but the remaining documentation gap is still present.

---

Issue #30941 Verification

Title: [DOCS] Headless print-mode docs do not explain nested CLAUDE.md and conditional rules loading
Issue Date: 2026-03-05
Verification Date: 2026-04-01
Status: PARTIALLY RESOLVED

---

Issue Summary

This issue reports that the claude -p documentation still does not explicitly explain how nested CLAUDE.md files and paths:-scoped .claude/rules/*.md files load in print mode, what triggers those lazy loads, or show a minimal example.

---

Verification Results

Claim 1: Headless docs now give mode-specific guidance about instruction loading in claude -p

Status: PARTIALLY RESOLVED

At https://code.claude.com/docs/en/headless, line 39: "Without it, claude -p loads the same context an interactive session would, including anything configured in the working directory or ~/.claude."

At https://code.claude.com/docs/en/headless, lines 39-41: "Add --bare to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, claude -p loads the same context ... Bare mode is useful for CI and scripts..."

Verdict: The headless page now explicitly states that standard claude -p runs use the same context as interactive mode, and that --bare disables automatic instruction discovery. That addresses part of the print-mode behavior question.

---

Claim 2: Current docs explicitly document nested CLAUDE.md loading, paths: rule evaluation, lazy-load triggers, and a print-mode example on the headless page

Status: UNRESOLVED

At https://code.claude.com/docs/en/memory, lines 123-125: "Claude Code reads CLAUDE.md files by walking up the directory tree ... Claude also discovers CLAUDE.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories."

At https://code.claude.com/docs/en/memory, lines 167-182: "Rules can be scoped to specific files using YAML frontmatter with the paths field. These conditional rules only apply when Claude is working with files matching the specified patterns... Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use."

At https://code.claude.com/docs/en/hooks, lines 755-757: "This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested CLAUDE.md or when conditional rules with paths: frontmatter match."

At https://code.claude.com/docs/en/changelog, line 690: "Fixed conditional .claude/rules/*.md files (with paths: frontmatter) and nested CLAUDE.md files not loading in print mode (claude -p)"

At https://code.claude.com/docs/en/headless, lines 65-67: "These examples highlight common CLI patterns. For CI and other scripted calls, add [--bare](#start-faster-with-bare-mode) so they don't pick up whatever happens to be configured locally."

Verdict: The general memory and hooks pages explain nested CLAUDE.md loading and paths: rule triggers, and the changelog confirms that print mode supports them. However, the headless page still does not explicitly connect those behaviors to claude -p, explain the lazy-load triggers in print mode, or provide the requested print-mode example.

---

Current State

| Claim | Status |
|-------|--------|
| Headless docs say standard claude -p uses the same context as interactive mode unless --bare is used | PARTIALLY RESOLVED |
| Headless docs explicitly explain nested CLAUDE.md loading in print mode | UNRESOLVED |
| Headless docs explicitly explain paths:-scoped rule loading triggers in print mode | UNRESOLVED |
| Headless docs include a minimal print-mode instruction-loading example | UNRESOLVED |

---

Suggested Fix

Before: the headless page says that claude -p loads the same context as interactive mode unless --bare is used, but it does not explicitly describe nested CLAUDE.md loading, paths:-scoped rule triggers, or a minimal print-mode example.

After: add a short "Instruction loading in print mode" subsection to https://code.claude.com/docs/en/headless that states that standard claude -p runs use the normal instruction-loading model, nested CLAUDE.md files load when Claude reads files in those subdirectories, paths:-scoped rules load when matching files enter context, and --bare disables that automatic loading; include a minimal example that demonstrates the behavior.

---

References

• URL: https://code.claude.com/docs/en/headless
• Lines 39-41: Standard claude -p loads the same context as interactive mode unless --bare is used.
• Lines 65-67: The examples section covers general CLI patterns, but no instruction-loading example is present.
• URL: https://code.claude.com/docs/en/memory
• Lines 123-125: Nested CLAUDE.md files in subdirectories load when Claude reads files in those subdirectories.
• Lines 167-182: paths:-scoped rules apply when Claude works with matching files and trigger when Claude reads matching files.
• URL: https://code.claude.com/docs/en/hooks
• Lines 755-757: Lazy loads occur for nested CLAUDE.md traversal and paths: frontmatter matches.
• URL: https://code.claude.com/docs/en/changelog
• Line 690: Print mode bug fix for nested CLAUDE.md and conditional .claude/rules/*.md loading.

---

Conclusion & Recommendation

Primary Concern: The headless print-mode docs still do not explicitly document how nested CLAUDE.md files and paths:-scoped rules load during claude -p runs.

Resolution Status: PARTIALLY RESOLVED

Recommendation: KEEP OPEN

The current headless page partially addresses the issue by stating that claude -p uses the same context as interactive mode unless --bare is used. It still lacks explicit print-mode documentation for nested CLAUDE.md, conditional rule triggers, and a concrete example, so the documentation gap remains open.

---

Checked against the latest docs mirror — this issue is still unresolved as of 2026-04-27.

Issue #30941 Verification

Title: [DOCS] Headless print-mode docs do not explain nested CLAUDE.md and conditional rules loading
Issue Date: 2026-03-05
Verification Date: 2026-04-29
Status: RESOLVED

---

Issue Summary

This issue reports that the print-mode documentation did not explain whether claude -p loads nested CLAUDE.md files and paths:-scoped .claude/rules/*.md files, or what triggers those instructions to load in non-interactive runs.

---

Verification Results

Claim 1: The docs did not state whether claude -p loads the normal Claude Code instruction context

Status: RESOLVED

At https://code.claude.com/docs/en/headless, lines 39-41: Add --bare to reduce startup time by skipping auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md. Without it, claude -p loads the same context an interactive session would, including anything configured in the working directory or ~/.claude.

Verdict: The headless documentation now explicitly states that non-bare claude -p sessions load the same context as interactive sessions, including working-directory and user-level instruction sources.

---

Claim 2: The docs did not explain how nested CLAUDE.md files load for claude -p

Status: RESOLVED

At https://code.claude.com/docs/en/memory, lines 137-142: Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory... and Claude also discovers CLAUDE.md and CLAUDE.local.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.

At https://code.claude.com/docs/en/hooks, lines 907-909: Fires when a CLAUDE.md or .claude/rules/*.md file is loaded into context. This event fires at session start for eagerly-loaded files and again later when files are lazily loaded, for example when Claude accesses a subdirectory that contains a nested CLAUDE.md...

Verdict: The current docs now describe both eager loading for files along the current directory tree and lazy loading for nested CLAUDE.md files, which covers the expected behavior when claude -p uses the normal session context.

---

Claim 3: The docs did not explain whether paths:-scoped rules are evaluated in print mode or what triggers their lazy loading

Status: RESOLVED

At https://code.claude.com/docs/en/memory, lines 185-200: Rules can be scoped to specific files using YAML frontmatter with the paths field. and Rules without a paths field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use.

At https://code.claude.com/docs/en/hooks, lines 907-920: This event fires at session start for eagerly-loaded files and again later when files are lazily loaded... when conditional rules with paths: frontmatter match. The same section defines load_reason values including session_start, nested_traversal, and path_glob_match, and notes that globs is present for path_glob_match loads.

Verdict: The current docs now explain both the evaluation rule for paths:-scoped files and the lazy-load trigger conditions, including the path_glob_match reason used when those rules match.

---

Current State

| Claim | Status |
|-------|--------|
| The docs did not state whether claude -p loads the normal Claude Code instruction context | RESOLVED |
| The docs did not explain how nested CLAUDE.md files load for claude -p | RESOLVED |
| The docs did not explain whether paths:-scoped rules are evaluated in print mode or what triggers their lazy loading | RESOLVED |

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/headless
• Lines 39-41: States that non-bare claude -p loads the same context as an interactive session and that --bare skips CLAUDE.md and related auto-discovery.
• URL: https://code.claude.com/docs/en/memory
• Lines 137-142: Explains eager loading from the current directory tree and lazy loading for nested subdirectory CLAUDE.md files.
• URL: https://code.claude.com/docs/en/memory
• Lines 185-200: Explains paths:-scoped rules and says they trigger when Claude reads matching files.
• URL: https://code.claude.com/docs/en/hooks
• Lines 907-920: Describes eager and lazy instruction loading, explicitly naming nested CLAUDE.md, conditional paths: rules, and path_glob_match / nested_traversal load reasons.

---

Conclusion & Recommendation

Primary Concern: The issue reported that print-mode documentation did not explain whether and when nested CLAUDE.md files and path-scoped .claude/rules/*.md files load.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current documentation now states that non-bare claude -p uses the same context as interactive sessions, and the memory and hooks pages explain the lazy-loading behavior for nested CLAUDE.md files and paths:-scoped rules. The reported documentation gap is now covered.

---

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.