CLAUDE.md, Explained: The File That Teaches Claude Code Your Rules

If you’ve watched Claude Code repeat a mistake you corrected yesterday, you’re missing a CLAUDE.md — or you have one and it isn’t earning its keep. This file is the highest-leverage configuration in the entire tool, and it’s also the one most people write badly, because the failure mode is silent: bloated rules don’t error, they just quietly stop being followed. I’ve rewritten mine perhaps a dozen times across projects. Here’s everything that actually matters.

What CLAUDE.md actually is

CLAUDE.md is a plain Markdown file that Claude Code reads automatically when a session starts in your project. Its contents are injected into the model’s context as standing instructions — a persistent system prompt scoped to your repo. Anything in it, Claude knows before your first prompt: your build commands, your conventions, your “never do this” list.

That’s the whole mechanism. No special syntax, no schema — just Markdown that a very capable reader takes as house rules. The craft is entirely in what you put there and what you leave out.

Where Claude Code looks for it (the hierarchy)

Claude Code layers memory files from broadest to most specific:

  1. ~/.claude/CLAUDE.md — your personal, global file. Applies in every project on your machine. Personal preferences live here (“I use zsh”, “prefer TypeScript strict mode”, “commit messages in imperative mood”).
  2. CLAUDE.md at the repo root — the project file. This is the one you commit, so the whole team (and their agents) share the same rules.
  3. CLAUDE.md in subdirectories — scoped rules that load when Claude works with files in that part of the tree. A monorepo’s apps/web/CLAUDE.md can carry frontend-only conventions without polluting the backend’s context.

More specific layers add to broader ones. Your personal file plus the project file plus any relevant subdirectory files are all in play at once — which is exactly why brevity matters everywhere.

Two supporting details worth knowing: you can split a large file with imports (a line like @docs/conventions.md pulls another file in), and while you’re in a session, prefixing a message with # offers to save that instruction to memory, while the /memory command opens the files for editing directly. Those two together mean your CLAUDE.md can grow from real corrections instead of speculative rule-writing.

What belongs in it

Write it like an onboarding note for a sharp new teammate — one who reads code fine but can’t know your project’s invisible decisions:

  • Commands: how to build, test, lint, and run — especially nonstandard ones (make dev, not npm start).
  • Conventions the code can’t show: “we use the result-object pattern, never exceptions, for expected failures”; “all timestamps are UTC in the DB, local only at render”.
  • Landmines: “the legacy/ directory is frozen — never modify it”; “the netlify.toml plugin line is load-bearing”.
  • Hard rules: “never commit directly to main”; “never add a dependency without asking”.
  • Pointers, not prose: link to the doc (@docs/api-design.md) instead of restating it.

What doesn’t belong (and why it backfires)

Every line of CLAUDE.md is spent from the context budget of every session, whether it’s relevant or not. The tax on bloat is paid constantly. Cut ruthlessly:

  • Anything derivable from the code. Claude reads your repo; it doesn’t need the directory structure narrated or your framework identified.
  • Generic best practices. “Write clean, maintainable code” instructs nothing. The model already tries; the line only dilutes the rules that do bind.
  • Long style guides. Ten crisp rules get followed. A 400-line pasted style guide gets skimmed — by humans and models alike. If it must exist, import it and summarize the five rules that matter most.
  • Stale facts. A CLAUDE.md that says npm test after the project moved to vitest is worse than none — it teaches with authority and lies. Treat it like code: review it when things change.

My rule of thumb after much iteration: if a rule has never prevented a mistake, delete it. The best files I’ve seen are under a hundred lines and every line has a scar behind it.

A minimal template that scales

# Project: Acme API

## Commands
- Build: `make build` · Test: `make test` (single test: `make test T=<name>`)
- Never run `make deploy` — CI owns deploys.

## Conventions
- Errors: result objects, never exceptions, for expected failures.
- DB timestamps: UTC only. Convert at the edge.
- New endpoints require an OpenAPI entry in api/spec.yaml.

## Boundaries
- `legacy/` is frozen. Do not modify.
- Never commit to main; branch + PR always.

## Context
- Architecture decisions: @docs/adr/

Start smaller than feels right, and let real corrections grow it — the # shortcut makes that a two-second habit.

Where this sits among Claude Code’s other config

CLAUDE.md is the instructions layer. Mechanical enforcement — which tools Claude may use, which commands are allowed without asking — belongs in settings.json and permissions, and repeatable workflows belong in custom slash commands. A useful division: if breaking the rule should be impossible, use permissions; if it should be understood, use CLAUDE.md. And Claude Code’s newer session memory builds on the same foundations — covered in how Claude Code memory works. If you’re hunting for where these files live on disk, the .claude folder explainer maps both the global and project directories, and the Claude folders and files on Mac guide covers the macOS specifics.

One more thing from the same ecosystem, with the obvious disclosure that we build it: if your CLAUDE.md drafting sessions happen in claude.ai before they reach the repo, NorthLab Folders keeps those planning chats organized and searchable — local-first, across Claude, ChatGPT, and Gemini.

Frequently asked questions

What is a CLAUDE.md file?

CLAUDE.md is a Markdown file that Claude Code automatically reads at the start of every session in your project. It’s where you write standing instructions — build commands, code style, architecture notes, things it should never do — so you don’t repeat them in every prompt. Think of it as a persistent system prompt for your repository.

Where does the CLAUDE.md file go?

Three places, layered: ~/.claude/CLAUDE.md applies to every project on your machine; a CLAUDE.md at your repo root applies to that project (commit it to share with your team); and CLAUDE.md files in subdirectories add rules when Claude works in those folders. More specific files layer on top of broader ones.

What should I put in CLAUDE.md?

The things you’d tell a new teammate on day one: how to build and test, conventions the code must follow, gotchas that aren’t obvious from reading the code, and hard rules (“never commit directly to main”). Keep it short — it’s loaded into every session, so every line spends context. Cut anything Claude could derive by reading the code.

What’s the difference between CLAUDE.md and claude.md rules?

Same thing — people search both. The canonical name is CLAUDE.md (uppercase), and “Claude Code rules” refers to the instructions you write inside it. Rules can also live in ~/.claude/CLAUDE.md for personal, cross-project preferences.