[BUG] CLAUDE.md files in subdirectories are not being automatically loaded

[RicSala]

Environment

• Platform (select one):
  • Anthropic API
  • AWS Bedrock
  • Google Vertex AI
  • Other: Claude Code CLI
• Claude CLI version: latest version
• Operating System: macOS
• Terminal:

Bug Description

CLAUDE.md files in subdirectories are not being automatically loaded when accessing files in those directories, contrary to what the documentation states. The memory system only loads CLAUDE.md files from parent directories (recursively up), but not from the current working directory when reading files.

Steps to Reproduce

1. Create a project structure:

• /project/
  • CLAUDE.md
  • src/
    • credits/
      • CLAUDE.md
      • error.ts

2. Add content to /project/CLAUDE.md (root level)
3. Add test content to /project/src/credits/CLAUDE.md (subdirectory level)
4. Ask Claude to review the file /src/credits/error.ts
5. Check Claude's context/memory

Expected Behavior

According to the official documentation, when working in /project/src/credits/ or reading files in that directory, Claude should load:

• /project/CLAUDE.md (recursively up) ✅
• /project/src/credits/CLAUDE.md (current directory) ✅

The docs specifically state: "When reading files in subdirs: /project/src/feature/subdir/CLAUDE.md ✅ (loaded on access)"

Actual Behavior

• Claude only loads the root /project/CLAUDE.md ✅
• Claude does NOT automatically load /project/src/credits/CLAUDE.md ❌
• The subdirectory CLAUDE.md file must be manually attached to the conversation

Additional Context

This behavior contradicts the documented memory loading pattern. The documentation suggests that CLAUDE.md files should be loaded from the directory containing the file being accessed, but in practice, only parent directory CLAUDE.md files are being loaded.

This significantly impacts the ability to use directory-specific context and instructions, which is a key feature of the memory system for organizing large projects.

[EDIT]: Creating this again because it's not solved.

Claude Code team: Please, don't just close bug reports on rapid-fire style... that doesn't solve the issues, just bury them and leave the user (the client) with a pretty bad feeling for the product and company 🙏🏻

[RicSala]

Proof:

[kuroneko0441]

Here's a simple script to reproduce.

TMP_DIR="$(mktemp -d)" # Create a temporary directory
cd "$TMP_DIR"

mkdir test
echo "echo" > ./test/run.sh

echo "My Name is AA" >CLAUDE.md # Project-wide
echo "My Name is BB" > ./test/CLAUDE.md # Directory-specific

claude -p "Print @./test/run.sh. What is my name?" # Should answer "BB", however the result is:
# Here's the content of `./test/run.sh`:
# 
# ```bash
# echo
# ```
# 
# Your name is AA (as specified in the CLAUDE.md file).

claude -p "What is my name?" # Should return "AA"
# Based on the CLAUDE.md file in your project, your name is **AA**.

[bam4564]

Ran similar tests to those outlined above and came to the same conclusion. Any updates here? This is a really critical piece of functionality for monorepo style codebases where you run claude code from the root directory.

My temporary workaround is to simply reference the nested claude.md files within the root claude.md. This loses the dynamic loading functionality (less context efficiency) but for now this is working okay for me.

[zonofthor]

Agree. I am hoping though that the new subagents functionality reduces the need for this.

[mikegreiling]

I want to add some clarity to this ticket.

Claude Code DOES in fact load CLAUDE.md files in subdirectories whenever it invokes the Read() tool to read a file (e.g. if you say "Please inspect ./path/to/file and tell me how many lines it contains").
HOWEVER, if the user uses @path/to/file within their prompt to inject the file into the context, it WILL NOT have the same behavior.

This is unexpected and contrary to what the documentation would suggest and I believe it qualifies as a bug.

I currently get around this by specifically telling Claude to gather sub-directory context where I know it exists. (e.g. "if I ask you about anything in path/to directory, ALWAYS read path/to/CLAUDE.md first if you do not have it in your context window")

[kuroneko0441]

@mikegreiling Thenk you for the analysis. However when I tested the behavior, it does not read the subdirectory CLAUDE.md file whether I mention the file or not.
At least in 1.0.72.

This is the test script I used. I hope this can help CC team to reproduce the issue.

claude --version
# 1.0.72 (Claude Code)

TMP_DIR="$(mktemp -d)" # Create a temporary directory
cd "$TMP_DIR"

mkdir test
echo "echo" > ./test/run.sh

echo "My Name is AA" >CLAUDE.md # Project-wide
echo "My Name is BB" > ./test/CLAUDE.md # Directory-specific


# === Subdirectory CLAUDE.md behavior ===
# Claude should read the ./test/CLAUDE.md file and answer "BB" as the name, but it answers "AA" instead.
# ===

claude -p "Read ./test/run.sh and tell me how many lines it contains. Plus, what is my name?" # WITHOUT mentioning the file.
# The file `./test/run.sh` contains 2 lines.
#
# Your name is AA (as specified in the CLAUDE.md file).

claude -p "Read @./test/run.sh and tell me how many lines it contains. Plus, what is my name?" # WITH mentioning the file.
# The file contains 2 lines, and your name is AA.


# === Root CLAUDE.md behavior ===
# Claude should answer "AA" as the name and it does.
# ===

claude -p "What is my name?"
# AA


# === Test on reading CLAUDE.md explcitly ===
# Just for sure
# ===

claude -p "Read ./test/CLAUDE.md and tell me how many lines it contains. Plus, what is my name?"
# The file `./test/CLAUDE.md` contains **2 lines**.
#
# Based on the main CLAUDE.md file in the root directory, your name is **AA**. However, the test/CLAUDE.md file shows a different name "BB", which appears to be test data.