CLAUDE.md, Done Right

CLAUDE.md is the single highest-leverage file in a Claude Code repo — it's loaded automatically at the top of every session, so whatever's in it shapes everything the agent does. This is how to write one that stays useful, and what to do when a whole team shares it.

What it is

A plain Markdown file Claude Code reads at session start. There's no schema — it's instructions in prose. The agent treats it as always-true context, so it's the right place for the facts you'd otherwise re-explain on every task: how to build, how to test, the code style, the shape of the repo.

Where it goes

• Repo root — project-wide context the whole team shares. This is the important one.
• ~/.claude/CLAUDE.md — your personal, global preferences across all projects.
• Subdirectory CLAUDE.md — folder-specific rules that only apply in that part of the tree.

What belongs in it (keep it tight)

The best CLAUDE.md is short and stable. Every line is read on every task, so noise has a real cost. Include:

• Commands first. Install, build, test, lint. The agent should never guess these.
• Conventions, not history. "Use 2-space indent, single quotes" belongs here. "We switched off X last quarter because…" does not.
• Repo layout. Where things live, so the agent navigates instead of searching.
• Hard rules. The handful of things that are always true (never edit generated files, always run the formatter, etc.).

If it's longer than a screen, the durable parts probably belong somewhere shared — read on.

The team problem: drift

Here's where CLAUDE.md alone stops scaling. One developer's file captures their context perfectly. Five developers produce five slightly different files, and the agent gives different answers depending on whose machine it's running on. Worse, a CLAUDE.md can't express why a decision was made or who owns a part of the codebase — it's a flat config file, not a knowledge base.

The fix isn't a bigger CLAUDE.md. It's keeping CLAUDE.md minimal and moving the durable knowledge — decisions, ownership, the reasoning behind conventions — into one shared, owned, versioned source that every agent reads.

Why CLAUDE.md doesn't scale across repos

Drift across developers is one wall. The other shows up the moment your team works in more than one repo. A CLAUDE.md lives inside a single repository, so by design it can't carry a decision that spans services — when you're losing context across 15+ repos, there's no file that every agent in every repo reads. You end up copy-pasting the same conventions into a dozen CLAUDE.md files, and the moment one changes, the rest are stale.

The instinct to "just give one agent all the repos" hits the context window wall fast, and it still doesn't tell the agent why a cross-cutting decision was made or who owns it. Scaling context across repositories is a different problem than keeping one file tidy — it needs a source of truth that lives outside any single repo and that every agent, in every repo, can read.

That's exactly what a shared context tree for agent teams is for: cross-repo decisions and ownership in one owned, reviewed Git repo, with a thin pointer-style CLAUDE.md left in each repository. CLAUDE.md stays per-repo and tight; the durable, cross-cutting knowledge lives once, above all of them.

Anti-patterns

• The dumping ground. Every decision pasted in until no one (and no agent) reads to the bottom. Move history and rationale out.
• Per-developer drift. Five uncommitted CLAUDE.md files. Commit the shared one; centralize the durable parts.
• Stale commands. The build command changed but CLAUDE.md didn't. Treat it like code — keep it current or it actively misleads.

A tight CLAUDE.md plus a shared context tree is the setup behind Claude Code best practices for teams — and it's the memory underneath an orchestration platform where agents also coordinate in chat and pick work off your GitHub issues and PRs, the foundation of running AI agent teams that stay coherent.