CLAUDE.md

CLAUDE.md is a 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, 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: 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.

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 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, 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.