Claude Code: Architecture of CLAUDE.md

A layered, hierarchical loading system designed to keep context lean, separate concerns, and compound value over time. Explore how it works below.

Virtual File System

On-Demand Loading

CLAUDE.md files in subdirectories are not loaded at launch. They are only included when Claude is actively working in that part of the codebase, keeping the context lean and hyper-relevant.

@imports & Delegation

Use @path/to/import syntax in your markdown. Your root file can stay short and delegate to specialized docs. Example:
- Git workflow: @docs/git.md

The Danger of Bloat

Because root files are loaded every session, bloat causes Claude to ignore your instructions. If Claude ignores rules, your file is too long.

Rule of thumb: Keep CLAUDE.md under 200 lines. Ask yourself: "Would removing this cause mistakes?" If no, cut it.

Quick Reference: The Mental Model

File Path	Scope	Shared via Git?	When loaded

Common Mistakes

Bloating the root file

If Claude keeps ignoring a rule, the file is probably too long. Prune ruthlessly. Move domain rules to subfolder files and team-owned rules to .claude/rules/.

Duplicating rules across files

If the same rule appears in two files, remove it from the less specific one. The hierarchy is additive, not overriding.

Forgetting .gitignore for local files

Add it immediately to prevent leaking your local env config:
echo "CLAUDE.local.md" >> .gitignore

Treating CLAUDE.md as set-and-forget

Treat it like code. Review when things go wrong, prune regularly, and test changes by observing whether Claude's behavior actually shifts.