CLAUDE.md: The Complete Guide

What Is a CLAUDE.md File?

A CLAUDE.md file is Claude Code's project-memory file: a Markdown document the agent loads automatically at the start of every session so you never have to re-explain your stack, conventions, commands, and guardrails. It functions like a system prompt scoped to one project, except you own it, you version it with git, and you edit it whenever the project changes.

Without a claude md file, every session starts cold. Claude opens your repo with zero context about which package manager you use, how you run tests, or what it must never break. You spend the first few exchanges briefing it, and you do that again tomorrow. With a CLAUDE.md, that briefing is permanent and shared with every teammate who clones the repo.

The mental model that helps most: CLAUDE.md is the contract between you and the agent. It states three things clearly.

• What this project is: the stack, the framework, the deploy target
• How to operate it: the exact build, test, lint, and deploy commands
• What the rules are: the conventions to follow and the lines never to cross

Where CLAUDE.md Lives and How It Loads

CLAUDE.md is read from a few locations, each with a different scope. Knowing which file does what keeps personal preferences out of shared repos and shared rules out of your personal config.

The loading rule is simple: project root and global both load at session start, and nested files apply when Claude is working inside that subtree. A per-package CLAUDE.md overrides the root file for that package, which is exactly what you want in a monorepo where the frontend and the API have different commands.

There is a real cost to remember here. The full contents of every applicable CLAUDE.md are loaded into context on every session and re-loaded after each compaction. The file's length is a recurring token cost, not a one-time setup. That single fact drives most of the Claude Code best practices below.

What to Put in Your CLAUDE.md

A useful CLAUDE.md is short and concrete. Aim for roughly 30 to 80 lines for most projects. Here is a real, annotated example for a statically exported Next.js site, the kind of file that earns its place in context:

# Project Config — Acme Marketing Site

## What this is
A statically-exported Next.js site (output: 'export') for Acme.
Built once, deployed as plain HTML to Hostinger. No server runtime.

## Stack
- Next.js 15, App Router, output: 'export' -> static /out
- Tailwind CSS · TypeScript · pnpm
- Forms: Web3Forms (no API routes — static export can't run them)

## Commands
pnpm dev        # local dev at http://localhost:3000
pnpm build      # static export -> ./out
pnpm lint       # ESLint
pnpm typecheck  # tsc --noEmit

## Conventions
- Smallest reasonable diff. Match existing style and naming.
- grep before reading; read specific line ranges, not whole files.
- Images: WebP, explicit width/height, hero loading="eager", rest lazy.
- No secrets in the client bundle (only NEXT_PUBLIC_* reaches it).

## Gotchas
- No API routes / getServerSideProps — static export breaks on them.
- Test against ./out (npx serve out), not the dev server. They differ.

## Deploy method
This project deploys via: pnpm build, then upload ./out to Hostinger
public_html. Never deploy without confirmation. Verify the live URL after.

Notice what is and is not in there. Every command is exact and copy-pasteable. The gotchas are things that have actually broken builds, not generic advice. The deploy method is spelled out so the agent does not invent one. And there is a hard rule about reading behavior that saves tokens on every single task. Each line either changes what the agent does or stops it from doing something wrong.

Here is the checklist of sections worth including, in priority order:

What to leave out matters just as much. No credentials, no API keys, no long explanations of code the agent can read for itself, and no aspirational rules you do not actually enforce. If a section never changes the agent's behavior, it is dead weight loaded into context on every prompt.

CLAUDE.md Best Practices (Token-Saving Rules)

Because CLAUDE.md loads on every session and after every compaction, the most important Claude Code best practices are about keeping context lean. A bloated file does not just waste tokens once. It taxes every prompt for the life of the project. These rules pay off continuously.

1. Tell Claude to grep before it reads

The single biggest token sink is reading whole files to find one function. Add a rule that makes the agent search first, then read only the match. A line like the one below changes default behavior across every task:

## Reading the codebase
- grep/search for the symbol first; do NOT read whole files to find one thing.
- Read specific line ranges around the match, not the entire file.
- Map structure with a search before opening files speculatively.

This is grep-before-read, and it is the highest-leverage rule in any CLAUDE.md. On a large file, reading a 40-line range instead of 2,000 lines can cut a task's context use by an order of magnitude.

2. Prefer pointers over content

Do not paste your full coding standards or a long architecture doc into CLAUDE.md. Point to it. "Detailed standards in docs/STANDARDS.md, read on demand" keeps the long content out of every-session context while still making it reachable when a task actually needs it. The file holds rules and pointers; the rules pull in content only when relevant.

3. Scope instructions to the right file

Personal preferences (your editor, your default package manager, your tone) go in the global ~/.claude/CLAUDE.md. Project rules go in the committed repo file. Mixing them bloats the shared file with things only you care about and pollutes teammates' context. Scope keeps both files short.

4. Make standards concrete and enforceable

"Write clean code" does nothing. "Smallest reasonable diff, match existing naming, run the check and paste the output before claiming a pass" changes behavior. Standards that are specific and verifiable get followed. Vague aspirations get ignored and still cost tokens.

CLAUDE.md Templates by Stack

The sections that matter shift by stack. A static site cares about export rules; a Node API cares about migrations and auth; an agency-client repo cares about deploy safety. Here is what each template emphasizes so you can lift the right starting point:

Two patterns are worth copying regardless of stack. First, the agency-client template treats the live site as the source of truth and leans conservative: confirm before anything outward-facing, back up before risky changes, and never use git to drive a deploy. Second, the monorepo template uses nested CLAUDE.md files so each package overrides the root with its own commands. The root holds only what is true repo-wide.

All six templates ship in the free starter pack, with the deploy-method slot left blank for you to fill per project. They pair naturally with skills and MCP servers, which we cover in our Claude Code skills and MCP servers guides.

CLAUDE.md + Subagents and MCP

CLAUDE.md does its best work as the shared rulebook for a team of agents, not just a single thread. When you run subagents, each one operates in its own context window. The standards in your CLAUDE.md, smallest diff, evidence before claims, stay in scope, confirm before destructive actions, apply to every agent in the chain. The file is the constitution they all follow.

This is also where the token math gets interesting. A researcher subagent can sweep 40,000 tokens of codebase, then hand the orchestrator only a distilled summary. The main thread stays clean, and your CLAUDE.md rules ensure each specialist behaves consistently without you re-briefing it. Memory (CLAUDE.md) plus a team (subagents) is a multiplier, not just a convenience.

Where MCP fits

MCP (Model Context Protocol) servers give the agent tools: a database it can query, a browser it can drive, a deploy API it can call. CLAUDE.md is where you tell Claude which MCP tools this project uses and when to reach for them. A line like "deploy via the Hostinger MCP tool, never bare CLI flags" turns an available capability into a reliable habit.

Together the three layers form a stack: CLAUDE.md is the memory and the rules, subagents are the labor split across clean contexts, and MCP is the set of hands that reach outside the codebase. The agency-client template wires this up explicitly, routing deploys through the shipper agent under the "confirm before outward-facing actions" rule. To build the team side out fully, our free Claude Code agent team starter pack includes the CLAUDE.md plus the agent definitions that read it.

Common CLAUDE.md Mistakes

After writing and auditing a lot of these files, the same mistakes show up over and over. Avoid them and your CLAUDE.md stays an asset instead of becoming a tax.

1. Letting it grow unbounded

The most common failure is a CLAUDE.md that only ever grows. Every incident adds a rule, nothing is ever removed, and a year later it is 400 lines loaded on every prompt. Prune it like code. If a rule has not changed an outcome recently, cut it.

2. Vague rules that change nothing

"Follow best practices" and "write good tests" are noise. They cost tokens and steer nothing. Replace every vague line with a concrete, verifiable instruction or delete it.

3. Putting secrets in the file

CLAUDE.md is committed to git and read into context constantly. Credentials, API keys, and tokens do not belong in it. They belong in a password manager or environment variables. The file should reference where creds live, never contain them.

4. Missing the deploy method

If the file does not state how the project ships, the agent will guess, and a wrong guess on deploy is expensive. Every CLAUDE.md should fill its deploy-method slot with exact steps and a "confirm first" rule for anything outward-facing.

5. Skipping the grep-before-read rule

Without an explicit reading rule, the agent defaults to opening whole files to find one symbol. On a large codebase that quietly burns your context budget all day. One line fixes it. Leaving it out is the most expensive omission in this list.

Frequently Asked Questions