# CLAUDE.md

> CLAUDE.md is the persistent instruction file coding agents like Claude Code read at the start of every session — project conventions, build commands, and hard-won constraints. What it is, how the memory hierarchy works, and why it's the highest-leverage markdown file in your repo.

Source: https://metavert.io/CLAUDE.md  
Published: 2026-07-04  
Updated: 2026-07-04

**CLAUDE.md** is a [markdown](https://metavert.io/markdown) file, conventionally placed at the root of a repository, that a coding agent reads automatically at the start of every session. It is the agent's standing briefing: what this project is, how to build and test it, which conventions are load-bearing, and which mistakes have already been made once and must not be made again. The convention was established by [Claude Code](https://metavert.io/claude-code), but the idea — a persistent, human-curated instruction file that survives between sessions — has become general across coding agents (Cursor's `.cursorrules`, GitHub Copilot's `copilot-instructions.md`, and the emerging cross-tool `AGENTS.md` convention are siblings of the same species).

### Why a File, Not a Prompt

The difference between a CLAUDE.md and a prompt is persistence and governance. A prompt is ephemeral — typed once, gone with the session. A CLAUDE.md is a versioned artifact in the repository: diffable, reviewable, blame-able, and shared by every human and agent who works on the code. When an agent makes the same mistake twice, the fix isn't to scold it harder in chat — it's to encode the constraint in CLAUDE.md so no future session can repeat it. Over time the file accumulates the project's *negative knowledge*: the invariants that don't appear in any function signature, the deployment gotcha that cost an afternoon, the reason the obvious refactor is wrong.

### The Memory Hierarchy

Agent instruction files compose in layers, from global to local. A user-level file (`~/.claude/CLAUDE.md`) carries personal preferences across every project. The repository root file carries project truths. Subdirectory files (e.g. `frontend/CLAUDE.md`) carry rules that apply only within that subtree, loaded when the agent works there. This mirrors how human onboarding actually works — company handbook, team norms, this-module-specifically — and it is a working example of [context engineering](https://metavert.io/context-engineering): the right knowledge arrives in the agent's context window at the right scope, without wasting tokens on rules that don't apply.

### What Belongs In It

The strongest CLAUDE.md files share a shape: build/test/lint commands the agent should run before claiming work is done; architectural conventions with the *reasons* behind them (agents follow rules better when the rule explains its own why); pointers to deeper documents rather than inlined novels; and explicit statements of what the agent must never do autonomously (drop a database, force-push, commit secrets). The weakest files are either empty ceremony or unmaintained sprawl — both erode the agent's trust-worthiness in equal measure. A practical guide lives at [How to Write a CLAUDE.md](https://metavert.io/how-to-write-a-CLAUDE.md).

### CLAUDE.md as a Reviewed Artifact

Because the file steers every future agent session, an error in CLAUDE.md compounds in a way an error in ordinary documentation does not — it becomes behavior. Teams increasingly review these files with the same rigor as code: inline comments, suggested edits, approval states. This is precisely the workflow [markupmarkdown](https://metavert.io/markupmarkdown) was built for — paste a repo or org URL and its *markdown indexes* give you a filterable library of every CLAUDE.md across your projects (a saved `claude.md` filter tab is a one-click audit surface), with threaded review, [CI-style checks](https://metavert.io/docs-as-code), and one-click push of the approved revision back to GitHub. Fittingly, agents themselves can join that review through MCP — the file that governs agents, reviewed with agents, gated by humans.

## Related Topics

- [How to Write a CLAUDE.md](https://metavert.io/how-to-write-a-CLAUDE.md) — The practical guide
- [Markdown](https://metavert.io/markdown) — Why agent instruction files are markdown
- [SKILL.md](https://metavert.io/SKILL.md) — On-demand procedural knowledge, vs. always-on instructions
- [Claude Code](https://metavert.io/claude-code) — The agent that established the convention
- [Context Engineering](https://metavert.io/context-engineering) — The discipline CLAUDE.md files implement
- [Agentic Memory](https://metavert.io/agentic-memory) — CLAUDE.md as human-curated long-term memory
- [markupmarkdown](https://metavert.io/markupmarkdown) — Review and ship CLAUDE.md files with your team and your agents
- [Docs as Code](https://metavert.io/docs-as-code) — Checks and gates for instruction files

## Further Reading

- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) — Anthropic (canonical CLAUDE.md guidance)
- [Claude Code Memory Documentation](https://docs.claude.com/en/docs/claude-code/memory) — Anthropic
- [AGENTS.md — the cross-tool convention](https://agents.md/)
- [Review your CLAUDE.md files with markupmarkdown](https://mumd.metavert.io)