CLAUDE.md

What Is CLAUDE.md?

CLAUDE.md is the markdown instruction file that Claude Code, Anthropic's coding agent, automatically reads at the start of every session. It carries persistent project context: build and test commands, code conventions, architecture notes, and rules the agent must follow, so the same guidance applies to every task without being repeated in prompts.

Key Takeaways

• It is standing memory, loaded automatically. Anything in CLAUDE.md shapes every session in that project, which makes it the highest-leverage file in a Claude Code workflow.
• It is layered. Claude Code merges files from the user level (~/.claude/CLAUDE.md), the project root, and subdirectories, with more specific files adding to and refining broader ones.
• Every line costs context. The file is prepended to each session, so it competes with code and conversation for the context window, and bloated files degrade results.
• It is Claude Code's counterpart to the vendor-neutral AGENTS.md convention, and teams using multiple agents often maintain one file and reference it from the other.
• Instructions work best as short, imperative, project-specific rules. Generic advice like "write clean code" wastes tokens; "run make lint before finishing any task" changes behavior.

How It Works

When Claude Code starts in a directory, it gathers CLAUDE.md files from several locations: a global file in the user's home directory for personal preferences that apply everywhere, the project root file that is usually checked into git and shared by the team, and optional files in subdirectories that add rules for their part of the tree. The combined content lands at the top of the agent's context before the first user message, functioning as project-level system guidance. A related convention, CLAUDE.local.md or an untracked personal file, holds individual overrides that stay out of version control.

Teams grow the file two ways. The deliberate way is writing it like an onboarding document for a very literal contributor: exact commands, naming conventions, directory boundaries, links to deeper docs. The incremental way is capturing corrections as they happen; Claude Code supports quickly appending an instruction to memory mid-session, so "we use pnpm here, not npm" becomes a permanent rule the moment it is first said. Mature setups also use imports, where CLAUDE.md references other files to pull in shared standards without duplicating them. What lands in these files is fairly predictable: a 2025 empirical study of 253 CLAUDE.md files from 242 repositories found they typically follow shallow hierarchies dominated by operational commands, technical implementation notes, and high-level architecture [1].

What makes the file powerful is the compounding effect. A correction made once in chat helps once. The same correction in CLAUDE.md helps every session, for every engineer on the team, indefinitely. That is why experienced teams review the file in pull requests like any other piece of infrastructure, and why context engineering discussions treat it as the first lever to pull before more elaborate machinery. Real-world usage bears this out: a study of 2,303 agent context files across 1,925 repositories found they evolve like configuration code, through frequent, small additions [2].

Example

A startup's monorepo has a rule that trips up every new engineer and every agent: the API package generates its TypeScript client, and hand-editing the generated code silently breaks the next build. After the agent does exactly that twice, the team adds a root CLAUDE.md: never edit packages/api-client/src/generated/, regenerate with pnpm codegen after schema changes, run pnpm turbo test --filter=...[HEAD] before declaring any task done, and use conventional commit messages. They also add a packages/infra/CLAUDE.md warning that Terraform files are applied by CI and must never be applied locally. Agent sessions stop making the two most expensive mistakes in the repo from that day on.

What People Get Wrong

The classic mistake is treating CLAUDE.md as a dumping ground and letting it swell into thousands of words of style philosophy, stale commands, and pasted documentation. Because the file is loaded into every session, bloat taxes every task, and models follow long instruction lists less reliably than short ones. The discipline that works is the same as for code: keep it minimal, keep it current, delete rules that no longer earn their tokens, and move reference material into linked docs the agent can read on demand. It is also worth keeping expectations honest about what the file can do. A 2026 ablation study of 288 evaluated runs across 17 real repository tasks found that context files like CLAUDE.md did not measurably move correctness on either Claude Code or Codex [3]. The file's value lies in steering conventions, commands, and boundaries, not in making the model solve harder problems.

FAQ

What is the difference between CLAUDE.md and AGENTS.md? Scope of audience. AGENTS.md is a cross-vendor convention read by many coding agents; CLAUDE.md is Claude Code's native file, with extra behavior like hierarchical merging, imports, and in-session memory updates. Teams running several agents typically keep one canonical instruction file and have the other reference it.

Should CLAUDE.md be committed to version control? The project-level file, yes. It encodes team knowledge and should evolve through review like any shared config. Personal preferences belong in the home-directory file or a local variant that stays untracked.

How long should a CLAUDE.md be? As short as it can be while covering the commands and rules the agent actually needs. Many effective files are under a hundred lines. If yours reads like documentation rather than instructions, move the documentation elsewhere and link to it.

Sources

1. arXiv. "On the Use of Agentic Coding Manifests: An Empirical Study of Claude Code, analysis of 253 CLAUDE.md files from 242 repositories." https://arxiv.org/abs/2509.14744. Accessed August 2026.
2. arXiv. "Agent READMEs: An Empirical Study of Context Files for Agentic Coding, evolution patterns across 2,303 context files." https://arxiv.org/abs/2511.12884. Accessed August 2026.
3. arXiv. "Do Context Files Help Coding Agents? A Two-Agent Ablation Study on Real Repositories, 288 evaluated runs across 17 tasks." https://arxiv.org/abs/2607.27250. Accessed August 2026.