Why do parallel Claude Code agents leak commits into the wrong PR?

Because two agents in the same repo directory share one Git HEAD. If agent A commits while agent B was the last to check out a branch, A's commit lands on B's branch. Nobody made a mistake; one HEAD can't serve two branches. Give each agent its own git worktree (git worktree add) so it has an independent HEAD, and the commits stay where they belong.

Is a CLAUDE.md different from a README?

A README is written for humans who read it once. A CLAUDE.md is read by the agent on every turn and acted on directly, so it has to be precise and testable rather than descriptive. A vague README line gets skimmed; a vague CLAUDE.md line produces a wrong edit. You can reference the README from the CLAUDE.md, but don't paste it in and pay for it every turn.

Where does Claude Code look for the CLAUDE.md?

Claude Code reads a CLAUDE.md from your project so its guidance applies whenever you work in that repo. Keep it at the repo root so it's version-controlled alongside the code and every agent (and teammate) that clones the project gets the same instructions. Because it's checked in, updating the rules updates them for everyone at once.

CLAUDE.md Best Practices: What a Good One Actually Looks Like

TL;DR

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.

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.

Anatomy of a good CLAUDE.md: five stacked sections (project overview, architecture and data flow, critical rules, parallel-agent worktrees, honesty and claims), each with a one-line purpose. A footer notes that the file rides in context every turn, billed at the cache-read rate while stable.

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:

critical rules — from a real CLAUDE.md

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:

a worktree per agent

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

install

$ pipx install tokenjam$ tj context

Common questions

What should a CLAUDE.md contain?: Four sections carry most of the value: a one-paragraph project overview with the real install and run commands, an architecture and data-flow map so the agent edits the right file, numbered critical rules the agent must not break (testable ones like 'DuckDB only, never sqlite3'), and worktree discipline if you run agents in parallel. A fifth section on honesty and claims is worth adding once your agents produce anything user-facing.
How long should a CLAUDE.md be?: As short as it can be while staying complete. There's no hard line, but the file is re-sent to the model on every turn, so every line you add raises the per-turn cost of every session. If a paragraph doesn't change how the agent behaves, cut it. Density beats length: rules the agent uses earn their tokens, a duplicated README does not.
Do CLAUDE.md files cost tokens?: Yes. Claude Code auto-loads the CLAUDE.md into context and re-sends it on every turn, so a 3,000-token file costs 3,000 input tokens per turn, not once per session. If the prefix is cached you pay the cheaper cache-read rate, but still on every turn, plus a cache-write cost whenever the file changes. A bloated CLAUDE.md is a recurring line item for the life of the project.
Why do parallel Claude Code agents leak commits into the wrong PR?: Because two agents in the same repo directory share one Git HEAD. If agent A commits while agent B was the last to check out a branch, A's commit lands on B's branch. Nobody made a mistake; one HEAD can't serve two branches. Give each agent its own git worktree (git worktree add) so it has an independent HEAD, and the commits stay where they belong.
Is a CLAUDE.md different from a README?: A README is written for humans who read it once. A CLAUDE.md is read by the agent on every turn and acted on directly, so it has to be precise and testable rather than descriptive. A vague README line gets skimmed; a vague CLAUDE.md line produces a wrong edit. You can reference the README from the CLAUDE.md, but don't paste it in and pay for it every turn.
Where does Claude Code look for the CLAUDE.md?: Claude Code reads a CLAUDE.md from your project so its guidance applies whenever you work in that repo. Keep it at the repo root so it's version-controlled alongside the code and every agent (and teammate) that clones the project gets the same instructions. Because it's checked in, updating the rules updates them for everyone at once.