Title: Docs: Add example for on-demand loading of subdirectory CLAUDE.md files
Labels: documentation, enhancement
Summary
The documentation for the CLAUDE.md memory feature accurately describes the on-demand loading behavior for files in subdirectories but lacks a concrete example. This can make the feature's behavior unclear to users, who might mistakenly believe the context is loaded at startup. Adding a simple example would significantly improve clarity.
Affected Documentation
- Page:
en/docs/claude-code/memory
- URL:
https://docs.anthropic.com/en/docs/claude-code/memory
- Section: "How Claude looks up memories"
- Specific Text:
Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.
The Point of Confusion
The documentation first explains that Claude Code recursively looks up the directory tree for CLAUDE.md files, which implies an initial, eager scan at launch. The very next sentence introduces a different, on-demand loading mechanism for CLAUDE.md files found in subdirectories.
Without an example, this distinction is easy to miss. A user might logically assume that all CLAUDE.md files are discovered and loaded eagerly at startup. When context from a subdirectory's CLAUDE.md isn't applied as expected, they may incorrectly conclude the feature is broken, leading to unnecessary debugging or bug reports.
Proposed Solution
To eliminate this ambiguity, I propose adding a brief, practical example immediately following the text quoted above. This will make the on-demand behavior explicit.
Recommendation:
Add a Note or Tip block with an example like the following:
**Example of On-Demand Context Loading:**
Imagine your project has this structure:
my-project/
├── frontend/
│ ├── CLAUDE.md <-- Contains React-specific instructions
│ └── src/
│ └── Button.tsx
└── CLAUDE.md <-- Contains general project instructions
The instructions from frontend/CLAUDE.md will only be loaded into the session after Claude interacts with a file inside that subtree, for instance, by reading or editing frontend/src/Button.tsx.
This small addition would make the behavior explicit, improve the user experience, and better highlight one of Claude Code's more intelligent context-management features. Thank you.
Title: Docs: Add example for on-demand loading of subdirectory
CLAUDE.mdfilesLabels:
documentation,enhancementSummary
The documentation for the
CLAUDE.mdmemory feature accurately describes the on-demand loading behavior for files in subdirectories but lacks a concrete example. This can make the feature's behavior unclear to users, who might mistakenly believe the context is loaded at startup. Adding a simple example would significantly improve clarity.Affected Documentation
en/docs/claude-code/memoryhttps://docs.anthropic.com/en/docs/claude-code/memoryThe Point of Confusion
The documentation first explains that Claude Code recursively looks up the directory tree for
CLAUDE.mdfiles, which implies an initial, eager scan at launch. The very next sentence introduces a different, on-demand loading mechanism forCLAUDE.mdfiles found in subdirectories.Without an example, this distinction is easy to miss. A user might logically assume that all
CLAUDE.mdfiles are discovered and loaded eagerly at startup. When context from a subdirectory'sCLAUDE.mdisn't applied as expected, they may incorrectly conclude the feature is broken, leading to unnecessary debugging or bug reports.Proposed Solution
To eliminate this ambiguity, I propose adding a brief, practical example immediately following the text quoted above. This will make the on-demand behavior explicit.
Recommendation:
Add a
NoteorTipblock with an example like the following:This small addition would make the behavior explicit, improve the user experience, and better highlight one of Claude Code's more intelligent context-management features. Thank you.