claude-code - 💡(How to fix) Fix Documentation ambiguity: CLAUDE.md concatenation order and priority [1 comments, 2 participants]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/memory#how-claude-md-files-load

Section/Topic

How CLAUDE.md files load

Current Documentation

How CLAUDE.md files load

Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files. This means if you run Claude Code in foo/bar/, it loads instructions from foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.

All discovered files are concatenated into context rather than overriding each other. Within each directory, CLAUDE.local.md is appended after CLAUDE.md, so when instructions conflict, your personal notes are the last thing Claude reads at that level.

What's Wrong or Missing?

Description

The memory documentation at /en/memory#how-claude-md-files-load states that Claude Code reads CLAUDE.md files from the current working directory up to root and concatenates them. However, it's unclear which file has priority when there are conflicts.

The docs say files are "concatenated," but don't specify:

• Does the root CLAUDE.md (read last) override earlier files, or do more specific files (closer to CWD) take precedence?
• Is the behavior consistent with CLAUDE.local.md, which the docs say is appended after CLAUDE.md at each level to take precedence?

Expected behavior

More specific files (closer to CWD) should logically have higher priority than root-level files, similar to how .local files work.

Actual behavior

Unclear from documentation.

Steps to clarify

• Explicitly document the priority order when CLAUDE.md files at different levels contain conflicting content
• Confirm whether root or CWD-level files take precedence

Suggested Improvement

Suggested Documentation Improvement

Add a concrete example showing CLAUDE.md concatenation order across multiple directory levels:

Example Directory Structure

/root/ ├── CLAUDE.md (global config) ├── project/ │ ├── CLAUDE.md (project-level config) │ └── src/ │ ├── CLAUDE.md (src-level config) │ └── component.ts (current working directory)

Concatenation Order

When running Claude Code from /root/project/src/, files are read in this order:

1. /root/project/src/CLAUDE.md (most specific, read first)
2. /root/project/CLAUDE.md (read second)
3. /root/CLAUDE.md (least specific, read last)

Priority Behavior

Files read last take precedence in case of conflicts. This means /root/CLAUDE.md (root level) has the highest priority, overriding more specific files.

Note: This differs from intuitive behavior where closer/more specific files should take precedence. Consider using claudeMdExcludes to explicitly control which files load.

Local File Override

At each level, CLAUDE.local.md is appended after CLAUDE.md, allowing local overrides:

• /root/project/src/CLAUDE.md → /root/project/src/CLAUDE.local.md
• /root/project/CLAUDE.md → /root/project/CLAUDE.local.md
• /root/CLAUDE.md → /root/CLAUDE.local.md

Impact

Medium - Makes feature difficult to understand

Additional Context

<img width="1070" height="475" alt="Image" src="https://github.com/user-attachments/assets/b6c2ac5a-b80f-4a70-843a-a58f8e17183e" />