# CLAUDE.md Best Practices: What a Good One Actually Looks Like
A good CLAUDE.md gives Claude Code the architecture, the critical rules, and the worktree discipline it needs to work in a multi-agent repo. Here's the anatomy, with real examples.
_Published 2026-07-08._
---
import TLDR from '@/components/TLDR.astro';
import DefinitionBox from '@/components/DefinitionBox.astro';
import FAQBlock from '@/components/FAQBlock.astro';
import Terminal from '@/components/Terminal.astro';
- A CLAUDE.md is the file Claude Code auto-loads into context so the agent knows your project without you re-explaining it every session.
- A good one has four things earning their keep: a project overview, an architecture and data-flow map, numbered critical rules the agent must not break, and worktree discipline for running agents in parallel.
- If several agents share one working directory, they share one `HEAD`, and two commits can land on whichever branch was checked out last. That's how commits leak into the wrong PR. A worktree per agent fixes it.
- The file rides in context every turn, billed at the cheaper cache-read rate while it's stable, plus a re-cache cost whenever it changes. So a bloated CLAUDE.md is a recurring cost, and the tightest file is the cheapest.
- Beyond cost, an over-long CLAUDE.md makes Claude lose the important rules in the noise, so keeping it tight is also what keeps the rules working.
- `tj context` reads your Claude Code session logs and shows how much of your quota goes to re-sending context like this, without ever editing the file for you.
A CLAUDE.md is a Markdown file Claude Code reads automatically at the start of a session and keeps in context as the agent works. It carries the project knowledge an agent needs to be useful: how the code is laid out, what the hard rules are, and how to behave in your repo. Claude Code merges it into the system context on every turn, so it acts as durable, per-project memory rather than something you paste in each time.
## What is a CLAUDE.md and why does it matter?
A CLAUDE.md is project memory for Claude Code. You write down what the agent would otherwise have to rediscover every session, and Claude Code loads it automatically so the agent starts each task already knowing your codebase. Without one, you re-explain the same architecture and the same constraints on every new session, and the agent still guesses wrong.
The reason it matters more than a README is that the README is for humans who read it once. A CLAUDE.md is read by a machine on every turn, and the machine acts on it. A vague line in a README gets skimmed. A vague line in a CLAUDE.md produces a wrong edit. So the bar for a good one is different: it has to be precise, testable, and short enough that the agent can hold all of it while it works.
## What should a CLAUDE.md contain?
The best ones we've seen in production converge on the same four sections. Everything else is optional decoration. If you're starting from scratch, run `/init` inside Claude Code to bootstrap a starter file that scans your repo and drafts a first pass, then tighten it down to the sections below.
The five sections that earn their place. The file rides in context every turn, billed at the cache-read rate while stable, so keep them dense.
### 1. A project overview the agent can act on
One paragraph. What the project is, how it installs, the one command that runs it. Not a pitch. The agent needs to know that the package is called `tokenjam`, the CLI is `tj`, and you install with `pipx install tokenjam`, because if it guesses `pip install tj` it wastes a turn on a command that fails. Concrete names beat description here.
### 2. An architecture and data-flow map
This is the section that most changes agent behavior, and the one most people skip. An agent that doesn't know where code lives edits the wrong file, or reimplements something that already exists two directories over. A good architecture section answers two questions: where does each kind of logic live, and how does a request move through the system?
The data-flow part is what makes it powerful. "Spans enter from two paths and converge at `IngestPipeline.process()`" tells the agent exactly where to put a new ingest feature. It also encodes the rules the layout implies. If `core/` must never import from `cli/`, say so right next to the module list, because that's the moment the agent is deciding where to add an import.
### 3. Numbered critical rules
Rules are the constraints an agent breaks silently if you don't write them down. Number them so you can reference "Rule 14" in a review and so the agent treats them as a checklist rather than prose to skim.
Good rules are testable. "DuckDB only, never import sqlite3" is a rule an agent can obey and you can grep for. "Write clean code" is not a rule, it's a wish. The strongest ones name the exact failure they prevent:
1. DuckDB only — never import sqlite3. Use TIMESTAMPTZ not TEXT
for timestamps; JSON not TEXT for JSON columns.
7. Parameterised SQL only — never f-string SQL.
8. All test spans via factory — never construct NormalizedSpan
directly in tests; use tests/factories.py.
9. Use utcnow() for timestamps — never datetime.now() or
datetime.utcnow(). It returns timezone-aware UTC.
Each line names a specific wrong thing and the right thing to do instead. That's what makes it enforceable, both by the agent reading it and by a linter you add later.
### 4. Worktree discipline for parallel agents
This is the section nobody has until it bites them, so it's worth explaining the failure in full.
Run two Claude Code agents in the same repo directory at once and they share one Git `HEAD`. Agent A checks out `feat/cache`, starts working. Agent B checks out `fix/auth`. Now Agent A finishes a change and runs `git commit`. The commit lands on `fix/auth`, because that was the last branch checked out, and Agent A's work is now sitting in the wrong PR. Nobody did anything wrong. One shared `HEAD` cannot serve two branches.
The fix is a worktree per agent. A Git worktree gives each agent its own checked-out copy of the repo with its own `HEAD`, all backed by the same object store, so commits stay on the branch the agent intended:
$ git worktree add ../repo-cache main
$ cd ../repo-cache && git checkout -b feat/cache
# a second agent, its own HEAD, no cross-talk
$ git worktree add ../repo-auth main
$ cd ../repo-auth && git checkout -b fix/auth
Put the rule in the CLAUDE.md and every agent that reads it does this before it starts. The symptom to name in the file is the one that tips you off: `git log` shows a commit on a branch you didn't intend. When an agent sees that described, it knows to rebase the stray commit off rather than force-pushing over someone else's work.
A fifth section is worth adding once your agents produce anything user-facing: **honesty and claims**. Write down how the agent is allowed to describe results. If your product says "estimated recoverable," the agent should never write "saves you" or "guaranteed." Left unstated, an agent will happily strengthen a hedge into a promise, because confident copy reads better. A rule stops it.
## How long should a CLAUDE.md be?
Long enough to be complete, short enough that every line earns its slot. Anthropic suggests keeping it under roughly 200 lines, which is a useful concrete target: if you're well past it, you're probably paying rent on context the agent doesn't act on.
There's a real cost pushing you toward the short end, and it's easy to miss. There's also a second reason that has nothing to do with tokens: an over-long CLAUDE.md makes Claude lose the rules that matter in the noise. Anthropic warns about this directly. When every line competes for attention, the load-bearing rule ("never import sqlite3") sits next to a paragraph of history and gets the same weight as it. Trim the file and the rules that are left carry more. So keeping it tight isn't only cheaper, it's what keeps the agent actually following your rules.
## Do CLAUDE.md files cost tokens?
Yes, and the way they cost is the part that surprises people. Claude Code loads the CLAUDE.md into context and keeps it there, so it's re-sent to the model on every turn of the session. A 3,000-token CLAUDE.md isn't a one-time 3,000 tokens. It's 3,000 input tokens on turn one, and again on turn two, and on every turn until the session ends, across every session that agent ever runs.
If your prefix is cached, you pay the cache-read rate instead of the full input rate, which is cheaper. You still pay it on every turn, and you re-pay the cache-write cost every time the file changes. A stable CLAUDE.md sits in the cached prefix and stays cheap. A file that keeps changing keeps falling out of the cache and re-paying the write, which is why an over-edited CLAUDE.md quietly costs more than its length suggests. TokenJam's [`cache` analyzer](/docs/cli#tj-optimize) measures this for you: it shows how much of your available caching you're actually getting, so you can see whether your prefix is staying cached or churning. Either way, a bloated CLAUDE.md is a line item that recurs for the life of the project. The same principle that makes a stale [system prompt expensive](/blog/2026-07-07-half-your-system-prompt-isnt-working) applies here, and a CLAUDE.md is arguably worse, because it grows as the project grows and rarely gets pruned.
This is why the tightest CLAUDE.md is also the cheapest. A file that's dense with rules the agent actually uses is worth its tokens. A file padded with three paragraphs of history, aspirational values, and a duplicate of your README is paying rent on context the agent doesn't act on. When you trim a CLAUDE.md, you're not only making it clearer. You're lowering the per-turn floor of every session.
Seeing that cost is its own problem. You can't feel the re-send in a bill that only shows a monthly total. `tj context` reads the session logs Claude Code already writes to disk and shows the composition of your quota: how much went to re-sending context like your CLAUDE.md and conversation history, versus the tokens doing new work. It's read-only and fully local. It points at what's expensive; it never edits your CLAUDE.md for you.
$ pipx install tokenjam
$ tj context
## Common questions
## Further reading
- [Half your system prompt isn't doing any work](/blog/2026-07-07-half-your-system-prompt-isnt-working). The same re-sent-every-turn cost, applied to system prompts, and how to score which tokens carry weight.
- [Where your Claude Code quota goes](/blog/2026-07-03-where-your-claude-code-quota-goes). A breakdown of what actually consumes your session budget, re-sent context included.
- [What is an agent loop?](/blog/2026-06-08-what-is-an-agent-loop). Why an agent re-sends context hundreds of times per task, which is what makes the per-turn cost add up.