Every Claude Code session starts the same way: before you type anything, Claude reads its instructions. Most of those instructions come from one plain Markdown file in your repository — CLAUDE.md. It's the difference between an agent that guesses your package manager, test command and branch conventions, and one that already knows them. We run Claude Code across our own delivery and automation work, and the pattern is consistent: teams with a short, maintained CLAUDE.md get noticeably better output than teams without one, and teams with a long, stale one often get worse. Here's how the file works and how to write one that earns its place.

What CLAUDE.md is

CLAUDE.md is a Markdown file that gives Claude Code persistent instructions — for a project, for your personal workflow, or for a whole organization. Anthropic's docs put it plainly: Claude reads these files at the start of every session (Claude Code memory docs). The content is delivered as context after the system prompt, which matters for how you write it: it's guidance the model follows very reliably when it's clear and specific, not a rule engine that guarantees compliance.

Where it lives — and how the files stack

There isn't one CLAUDE.md; there are scopes, loaded from broadest to most specific and combined rather than overriding each other:

For larger codebases there's also a rules directory (.claude/rules/), where each file can be scoped to path globs so it loads only when Claude touches matching files — the tidy way to keep framework-specific guidance out of everyone's context. And you can pull other files in with @path/to/file imports, up to four hops deep.

What earns a line in it

Anthropic's own best-practices guide gives the test we use in every repo we touch: for each line, ask would removing this cause Claude to make mistakes? If not, cut it. In practice the lines that pass that test are:

And the lines that fail it: anything Claude can learn by reading the code, standard language conventions, tutorials, detailed API docs (link them instead), file-by-file descriptions, and anything that changes weekly.

How to write one that works

Keep it short. Anthropic's guidance is to target under 200 lines per file — longer files consume more context and reduce adherence. The over-specified CLAUDE.md is the most common failure we see: a 600-line wiki dump where the three rules that matter drown in forty that don't.

Be concrete. “Use 2-space indentation” works; “format code properly” doesn't. Use headings and bullets so the file scans, and check that no two instructions contradict each other.

Emphasize sparingly. Marking one critical line IMPORTANT helps it stand out. Marking twenty means none of them do.

Start with /init, then edit hard. The /init command generates a starter file from your codebase (and suggests improvements if one already exists). Treat its output as a first draft to prune, not a finished file. /memory opens your loaded memory files for editing.

Grow it from mistakes. The trigger for a new line is Claude making the same mistake twice, or a code review catching something an instruction would have prevented. Like any good onboarding doc, the file is a casebook of past failures.

Treat it like code. Commit it, review changes to it, and prune it regularly. A stale instruction is worse than none — it's confidently wrong guidance loaded into every session.

CLAUDE.md vs AGENTS.md

This is where teams get tripped up. AGENTS.md is the cross-vendor instructions file now governed by the Linux Foundation, read by GitHub Copilot's coding agent and others. Recent versions of Claude Code can read AGENTS.md too — but by default only when there's no CLAUDE.md in the working directory or above it. If both files exist, Claude reads your CLAUDE.md files only (Claude Code docs).

So if your team uses more than one agent, the clean pattern is: keep the shared substance in AGENTS.md, and make CLAUDE.md a thin file that starts with an @AGENTS.md import and adds only Claude-specific notes underneath. One source of truth, every agent reads it, and nobody maintains two divergent copies of your conventions. (Claude Code also has a project-instructions setting that can load both files; the import is the more explicit choice and survives a fresh machine.) One gotcha worth knowing: under the default setting, adding a CLAUDE.local.md counts as having a CLAUDE.md, which stops AGENTS.md from loading on its own.

CLAUDE.md vs hooks: advice vs enforcement

The most important design decision is knowing what not to put in CLAUDE.md. Instructions are advisory; Anthropic's docs describe hooks, by contrast, as deterministic — they guarantee the action happens. If a rule must never be broken — never edit migrations, always run the formatter, never touch production config — don't phrase it as a request. Enforce it with a hook, a permission rule, or a CI gate, and keep CLAUDE.md for the judgment calls. Multi-step procedures that are only needed sometimes belong in skills, which load on demand instead of costing context in every session.

That split — the file advises, the harness enforces — is the same principle behind every high-performing agentic SDLC team we work with: rules that matter live in gates, not in prose.

A starting template

For a typical service repo, a strong first CLAUDE.md has five short sections: Commands (build, test, lint — the literal invocations), Conventions (only the non-obvious ones), Architecture (a few lines of orientation, plus what's generated and off-limits), Workflow (branches, commits, definition of done), and Gotchas (the things that bit you). If you run several agents, put all five in AGENTS.md and import it. Either way, aim for something a new engineer could read in two minutes — because that's exactly the reader it's for.

Deop helps engineering teams make their repositories agent-ready — instructions files, hooks, review gates and governance — across GitHub Copilot and Claude Code, as a Microsoft partner specialized in Agentic DevOps with GitHub. Read our Copilot vs Claude Code comparison or book a discovery.