In the world of coding assistants, there’s a big gap between a chatbot that suggests code and an agent that can enter a repository, understand how it’s organized, run commands, fix issues across files, and verify results with minimal hand-holding. Anthropic’s Claude Code is built around that second idea—and one of the most practical (and underrated) pieces of the system is a plain Markdown file: CLAUDE.md.

This isn’t a decorative doc. Done right, CLAUDE.md functions like an operating manual: a persistent set of rules, project context, and working conventions that Claude Code loads at the start of sessions so it doesn’t have to “guess” how your team builds software. It’s the difference between an agent that improvises and one that behaves consistently over time.

What CLAUDE.md is (and why it exists)

According to Anthropic’s documentation, Claude Code can rely on two kinds of persistent memory:

Automatic memory (auto memory): notes Claude creates while working (useful commands, project patterns, reminders).
CLAUDE.md files: instructions written and maintained by you (or your team) that Claude should follow.

The reason CLAUDE.md matters is straightforward: Claude Code works in an “agent loop” of gather context → act → verify, repeating until it completes the task. Without a stable framework—project conventions, expected commands, definition of done—the agent has to fill in gaps. And in software, gap-filling usually means extra iterations, wrong assumptions, and wasted time.

In short, CLAUDE.md is how you teach Claude Code: “This is how we work here.”

What people use CLAUDE.md for in practice

A strong CLAUDE.md typically covers four categories that dramatically reduce ambiguity:

Project context: what this repo is, what it does, and how it’s structured.
Conventions and decisions: naming, style rules, architecture patterns, approved dependencies.
Repeatable workflows: how to set up the environment, how to run tests, lint, build, and ship.
Verifiable success criteria: what “done” means, what must pass, and what outputs are expected.

That last one is the real multiplier. Agentic systems get better fast when they can self-check. If the doc clearly says “run npm test and all tests must pass,” the agent can validate its own work instead of leaning on you as the QA loop.

Where to put it (and what the levels are)

Anthropic describes memory scopes that apply at different levels. The simplified mental model looks like this:

Org-managed policy: company-wide rules administered by IT/DevOps.
Project memory: ./CLAUDE.md or ./.claude/CLAUDE.md (committed to the repo).
Modular rules: ./.claude/rules/*.md (split by topic: style, testing, security, API rules).
User memory: ~/.claude/CLAUDE.md (your personal defaults for all projects).
Local project memory: ./CLAUDE.local.md (private to your machine, typically not committed).

A key practical point: CLAUDE.local.md is meant for local-only preferences (paths, local env details, personal workflow tweaks). It’s a strong pattern for “useful but not shareable” info. And it also implies a hard rule: don’t put secrets anywhere in this system—neither in CLAUDE.md nor in imported docs.

How it works under the hood: loading, precedence, and imports

Claude Code follows a predictable loading behavior:

CLAUDE.md files above your working directory get loaded at session start.
CLAUDE.md files inside subdirectories can be loaded “on demand” when Claude enters those trees.
Memory is read recursively from the current directory upward (until before the system root).
When instructions conflict, more specific rules win over general ones.

CLAUDE.md can also import other files using an @path/to/file syntax (absolute or relative to the file doing the import). Imports are useful for avoiding duplicated truth—if your repo already has canonical docs, import them instead of rewriting them in multiple places.

How auto memory complements CLAUDE.md

Auto memory typically lives per project, with an entry point like MEMORY.md. One detail that matters operationally: only the first ~200 lines are loaded automatically at session start. The goal is to keep the “index” short and push deep specifics into topic files (e.g., debugging.md, api-guidelines.md).

In real projects, the split tends to work like this:

CLAUDE.md: stable, normative rules—what should not change frequently.
Auto memory: learned notes—what Claude discovers while working and should remember.

How to refine CLAUDE.md: from draft to precision tool

A CLAUDE.md rarely starts perfect. Like a good operations runbook, it improves through use. A practical refinement path looks like this:

1) Start with a draft, then cut aggressively

If you bootstrap an initial version, treat it as a rough draft. Remove fluff. Keep only what’s stable: commands, structure, conventions, and concrete success checks.

2) Make it verifiable

“Make it work” is ambiguous. “All unit tests must pass, lint must pass, and /health must return 200” is not.

3) Modularize when it grows

Once it starts getting long, move topic rules into .claude/rules/ (security rules, testing rules, styling rules). It’s easier to review and less likely to rot.

4) Import existing truth instead of duplicating it

If your README, docs/, or package.json scripts are the canonical truth, import or reference them rather than copying.

5) Design for context compression

Agent sessions have context limits. When context gets condensed, you don’t want essential constraints to vanish. Keep critical rules in CLAUDE.md, not only in chat. Many teams add a short “Preserve these constraints if context is compressed” section.

6) Close the loop after real work

After a session, update CLAUDE.md with what you learned: missing commands, unclear constraints, common pitfalls, or newly standardized patterns.

A practical CLAUDE.md template (starter)

# CLAUDE.md — Project Operating Guide## What this project is
- Purpose in 2–3 lines.
- Target users / runtime environment (web, API, CLI).## Repo structure
- folder X: ...
- folder Y: ...
- key files: ...## Workflows (commands)
- install: ...
- dev: ...
- tests: ...
- lint/format: ...
- build/release: ...## Conventions
- style (naming, imports, types)
- patterns (architecture, modules, APIs)
- do NOT do (forbidden deps, anti-patterns)## Definition of done
- must pass: tests, lint, build
- expected output / functional acceptance criteria## Preserve on context compression
- security constraints + definition of done + standard commands

Common mistakes that turn CLAUDE.md into a liability

Writing an essay instead of rules: too much prose, not enough action.
Mixing personal prefs with team rules: personal defaults belong in ~/.claude/ or CLAUDE.local.md.
Putting secrets in docs: don’t.
No verification path: without checks, you become the manual test runner.
Letting it go stale: an outdated CLAUDE.md can be worse than none, because it causes consistent wrong behavior.

FAQ (short Q&A)

What is CLAUDE.md in Claude Code?
A persistent Markdown guide that defines project rules, workflows, and “definition of done” for the agent.

Is CLAUDE.md required?
No, but it can significantly improve consistency and reduce back-and-forth.

Can a repo have multiple CLAUDE.md files?
Yes. Claude Code can load them recursively, and more specific ones can apply within subdirectories.

What’s the best way to refine CLAUDE.md?
Keep it concise, make success criteria testable, modularize rules, and import canonical docs instead of duplicating them.