What CLAUDE.md Is and How to Write an Effective CLAUDE.md File

CLAUDE.md is a persistent briefing document that ensures Claude understands your architecture and norms before you send your first prompt.

Large Language Models (LLMs) are essentially stateless functions. Their weights are frozen; they do not learn from your project over time, so every new session with Claude Code begins with a total loss of project context. Without a CLAUDE.md file, you are forced into a cycle of "onboarding overhead," re-explaining your tech stack and conventions every morning.

This amnesia is a waste of your token budget and engineering time. CLAUDE.md transforms a stateless agent into a teammate that already knows your "unwritten" rules. Stop treating every session as a fresh hire walkthrough: by codifying your project's identity and behavioral constraints into this file, you ensure the AI operates with the same baseline knowledge as a senior engineer on your team.

Conceptual diagram: a CLAUDE.md file at the project root is loaded by Claude Code into every session as persistent memory, giving the AI the project's structure and conventions from the first prompt.

What CLAUDE.md is and why every project should have one

LLMs are stateless functions that only "know" what is currently in the context window. Because they do not learn across sessions, the only way to maintain a consistent developer experience is to provide a persistent source of truth. CLAUDE.md is the only file that automatically enters every conversation context by default.

A high-performance context file defines three core components for your codebase:

WHAT (Tech Map): the tech stack, project structure, and folder purposes. This is critical for monorepos.
WHY (Purpose): the goals of the project and the reasoning behind specific modules.
HOW (Execution): the exact verification steps, build commands, and testing strings required to ship code.

By defining these early, you stop the cycle of repeating "use pnpm, not npm" or "no default exports." You shift the workload from re-explaining to executing.

How Claude Code reads and loads CLAUDE.md

Claude Code uses a bottom-up loading hierarchy through a directory walk. It starts at the filesystem root and moves toward your current working directory, concatenating every discovered file.

The hierarchy and priority follow this path:

Layered diagram of how Claude Code loads files: four stacked scopes from Managed Policy down to User, Project, and Local, walking from the filesystem root to the working directory, where the layer nearest the working directory wins.

Managed/Enterprise Policy: high-priority instructions (e.g. /etc/claude-code/CLAUDE.md on Linux, /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, or C:\Program Files\ClaudeCode\CLAUDE.md on Windows).
User Instructions: personal preferences across all projects at ~/.claude/CLAUDE.md.
Project Instructions: repository-shared rules at ./CLAUDE.md.
Local Instructions: git-ignored personal overrides at ./CLAUDE.local.md.

Because LLMs exhibit recency bias—they follow instructions placed at the end of a prompt more reliably—instructions in your working directory effectively take priority. They appear last in the concatenated context, giving your local project rules more weight than broad enterprise policies.