How CLAUDE.md Works in Claude Code

This document explains the mechanics of how CLAUDE.md files function in Claude Code, based on empirical testing and research.

Key Findings

1. Session-Based Content Loading

All CLAUDE.md files are refreshed between sessions - both root and directory-specific files pick up changes when resuming
NOT refreshed during conversation - changes made during an active session aren't visible until a new conversation starts
Resuming a session loads updated content - exiting and resuming Claude Code will pick up all CLAUDE.md changes
Content appears as "claudeMd" context in system prompts
No duplication within conversation - CLAUDE.md content is loaded once at start, not repeated every chat turn

2. Smart Context Injection

✅ Context IS directory-aware and loads dynamically
When Claude's working directory changes, relevant instruction content is injected via system reminders
File-access-aware - reading CLAUDE.md files directly also triggers @ import resolution and context injection
Example: Moving from /repo to /repo/frontend triggers injection of frontend-specific instruction files
Context persists after injection - once directory-specific content is loaded, it becomes part of the conversation and doesn't disappear
Additive context loading - each directory change or file access adds to available context rather than replacing it

3. @ Import Mechanism

✅ The @ syntax successfully imports referenced instruction files
Files referenced with @path/to/file.md syntax are resolved and injected as complete context
Dynamic resolution - @ imports are resolved when accessing files, not just at conversation start
Immediate injection - reading a CLAUDE.md file triggers immediate system reminders with imported content

Example from frontend CLAUDE.md:

@../.github/instructions/frontend.instructions.md
@../.github/instructions/frontend-common.instructions.md

4. Multi-Modal Context System

The system operates through multiple context injection mechanisms:

Session Initialization:

All CLAUDE.md files are loaded fresh when conversation starts
Root CLAUDE.md content appears as "claudeMd" context in system prompts

Dynamic Context Injection:

Directory changes trigger injection of relevant instruction content via system reminders
File access triggers immediate @ import resolution and context injection
Both directory navigation and file reading can add contextual content

Persistent Context:

Once injected, context persists throughout the conversation
New context adds to existing context rather than replacing it
Creates cumulative contextual knowledge as you navigate the codebase

5. File Structure Evidence

Current structure in Sage project:

/home/ubuntu/sage/blue/repo/
├── CLAUDE.md (root level)
├── frontend/
│   └── CLAUDE.md (directory-specific)
└── .github/instructions/ (imported via @ syntax)
    ├── project.instructions.md
    ├── decisions.instructions.md
    ├── frontend.instructions.md
    ├── frontend-common.instructions.md
    ├── frontend-api.instructions.md
    └── frontend-sidebar.instructions.md

6. Context-Aware Instruction Files

Instruction files are organized by domain and feature, with Claude Code's infrastructure handling the context-aware loading based on working directory and file patterns.

How to Use Effectively

For Static Changes

Modify CLAUDE.md between conversations for project-wide guidance
Use @ imports to modularize instruction content
Changes won't be visible until the next conversation session

for Dynamic Context

Create directory-specific CLAUDE.md files for context-aware instructions
Place them in relevant subdirectories (e.g., frontend/CLAUDE.md, backend/CLAUDE.md)
Content will be injected when Claude navigates to those directories

Best Practices

Modular Organization: Use @ imports to break instruction content into focused files
Directory Hierarchy: Create CLAUDE.md files in subdirectories for context-specific guidance
Conversation Boundaries: Remember that file changes require new conversations to take effect
Domain Organization: Organize instruction files by feature/domain for clear context boundaries

What We Cannot Determine

From testing, the following remain unclear:

The exact mechanism that processes CLAUDE.md files (proprietary to Claude Code)
Whether processing happens server-side or client-side
The specific code that handles @ import syntax resolution
How directory-based context targeting is implemented internally

Evidence Sources

Codebase Analysis: Found CLAUDE.md files and @ import patterns
System Reminders: Observed dynamic context injection based on directory changes
Test Modifications: Confirmed static loading behavior (changes during conversation not reflected)
Directory Navigation: Proved context-aware loading when changing working directories

The system combines static preprocessing with dynamic context injection, creating a sophisticated context management system that enables directory-aware instructions and modular context loading.

radleta/How CLAUDE.md Works in Claude Code.md