What goes in CLAUDE.md versus the README?

The README is for humans browsing the project; CLAUDE.md is the working context Claude reads on every task. There's overlap, but CLAUDE.md leans operational — the exact test/lint/build commands, the conventions to follow, and the guardrails on what not to touch — phrased as instructions to an agent doing the work, not an introduction for a new reader. A good rule: if it changes how a task gets done (run this command, follow this pattern, don't touch this), it belongs in CLAUDE.md.

Does Claude read CLAUDE.md automatically, or do I have to point it there?

Automatically — when the repo is open in Claude Desktop (or you launched claude in the project root), Claude reads the CLAUDE.md as part of the project's context for every task, no prompt needed. That's the whole point: you write it once, and every later chat starts grounded in it instead of you re-explaining the basics.

How is this different from the map-the-codebase playbook?

Map-the-codebase is the read — a one-time tour that gives you, the human, a mental model of an unfamiliar repo. This playbook turns that read into a durable asset: a checked-in file that grounds every future task and teammate automatically. The map answers "what is this code?" once; the CLAUDE.md answers "how do we work in this repo?" forever. Run the map first, then distill it into the file.

We're a monorepo with many packages — one CLAUDE.md or several?

Both. Keep a root CLAUDE.md for what's true across the whole repo (shared conventions, the top-level architecture), and add a per-package CLAUDE.md in each package for its local commands and patterns. Claude reads the nearest one to the code it's working on, so a task in one package gets that package's specifics without the noise of the others.

Write the CLAUDE.md that grounds every task

when to reach for this

Every fresh chat re-explains the same things: how you run the tests, the conventions you follow, what's load-bearing and off-limits. Each person paraphrases it slightly differently, so "our conventions" means whatever the last engineer happened to type. A CLAUDE.md checked into the repo is the fix — it's the project memory Claude reads automatically, so "our way" finally points at one real document instead of each person's guess. Build it early. It's the asset that makes the rest of the path sharp: every later playbook (debug, test, refactor, ship, migrate) starts from the same truth instead of relitigating the basics, and a new teammate's first chat is grounded on day one.

gather this first

The repo open in Claude Desktop — open the project's root folder so Claude reads your real files and can draft from what's actually there. (Power Track: claude in the project root from a terminal does the same.)
Your real dev loop: the exact commands you run for tests, lint, type-check, and build — the ones in your head or your shell history, not what the stale README claims.
The conventions and "always / never" rules that live only in people's heads: naming patterns, the parts that are load-bearing, where secrets live, what not to touch.

the workflow

Have Claude draft the CLAUDE.md from what it actually read

Open the folder in Claude Desktop and ask in the chat — no terminal needed. Don't write the file from scratch; let Claude read the repo and draft a first version from what's really there, then you correct it. A draft grounded in your actual tree is far faster to fix than a blank page is to fill.

you ask

Read this repo and draft a `CLAUDE.md` for it: a short architecture map (the top-level modules, the key directories, and how a typical request flows from entry point to data), based only on what you actually found in the files — not a generic version of this framework. Keep it tight; name real files.

what you get back A first-draft CLAUDE.md that describes your repo — real directory names, the actual request path — not a textbook description of your stack. If it reads generic, it didn't read the files; re-point it at the project root.

This builds directly on the map-the-codebase playbook — that read is the raw material, this turns it into a durable, checked-in asset. Correct every claim before you keep it; you're the author of record on this file the same as on any diff.
Capture the real dev loop

The single highest-value thing in a CLAUDE.md is the exact commands to run your tests, linter, type-checker, and build. With those in the file, the agent can run your loop and self-correct against the red instead of guessing whether its change works.

you ask

Add a "Commands" section to the `CLAUDE.md` with the exact commands to run the test suite, the linter, the type-checker, and the build. Here are the real ones we use: <paste your actual commands>. Note which one to run for a quick check versus a full pass.

what you get back A Commands block with your real invocations, so any later task can run the test suite and trust the red — the agent sees its own failures and fixes them instead of declaring victory blind.

Give it the real commands, not a paraphrase. A wrong test command in CLAUDE.md is worse than none — the agent will run it, get a confusing error, and route around your safety net.
Write the conventions and the guardrails

Now encode the rules that currently live only in people's heads: the patterns to follow, what's load-bearing, and the lines not to cross. This is what makes "do it the way we do it" mean something specific.

you ask

Add a "Conventions" and a "Guardrails" section. Conventions: our naming, the patterns to follow, how we structure a typical module — infer a draft from the code, and I'll correct it. Guardrails: the parts that are load-bearing and off-limits to change casually, and where secrets and credentials live so they stay out of context. Flag anything you're unsure about rather than inventing a rule.

what you get back Conventions and guardrails stated plainly enough that a later task — or a new teammate — follows them without being told. The secrets line keeps credentials and customer data out of the context window: the open folder is the boundary, and the file says so.

Review this like any diff: don't let it codify a convention you don't actually follow. An aspirational rule nobody keeps trains the agent to write code your team will reject in review.
Check it in and prove it works

Commit the file like code, then verify it actually grounds a fresh chat — the whole point is that the next conversation starts knowing all this without you re-explaining it.

you ask

Stage and commit the `CLAUDE.md` with a message explaining what it covers and why. Then, in a new chat: without me explaining anything, tell me how you'd run this project's tests and the two main conventions you'd follow — using only the `CLAUDE.md`.

what you get back A committed CLAUDE.md, and a fresh chat that already knows your test command and your conventions with zero re-explaining. That silent grounding — every task starting from the same truth — is the whole return on the twenty minutes.

Read the diff before you approve the commit. From here on, every chat in this repo inherits this file automatically — which is exactly why it has to be right.

make it your own

Monorepo: add a per-package CLAUDE.md next to the root one — each package gets its own commands and conventions, and Claude reads the nearest one. The root file holds what's true everywhere; the package files hold the local truth.
Promote your repeated prompts (Power Track): the prompts you find yourself retyping every week are candidates for slash commands or skills — turn them into reusable commands so the whole team runs the same flow, not a hand-typed approximation (see the Features tab).
Version it like code: keep CLAUDE.md under review — changes land as reviewed commits with a clear why, the same as an ADR, so the file stays trustworthy instead of drifting.

watch out for

Review the drafted file like any diff. Claude infers conventions from the code, and the code isn't always the convention you want — don't let it canonize a pattern you're trying to move away from. You're the author of record on this file too.
Keep secrets out of the file itself. Document where credentials live and that they stay out of context — never paste an actual key, token, or connection string into CLAUDE.md. It's checked into the repo; treat it as public to everyone with repo access.
A `CLAUDE.md` nobody updates rots. A stale file is worse than none — it confidently grounds every task in last quarter's truth. Give it an owner and update it when the conventions or commands genuinely change, the way you'd maintain an ADR.

you'll end up with A checked-in `CLAUDE.md` — architecture map, real dev commands, conventions, and guardrails — that Claude reads automatically on every task. The whole team's chats start from the same truth, so every later playbook in the path begins grounded instead of guessing, and a new teammate is productive on day one.

Questions people ask

What goes in CLAUDE.md versus the README?: The README is for humans browsing the project; `CLAUDE.md` is the working context Claude reads on every task. There's overlap, but `CLAUDE.md` leans operational — the exact test/lint/build commands, the conventions to follow, and the guardrails on what not to touch — phrased as instructions to an agent doing the work, not an introduction for a new reader. A good rule: if it changes how a task gets *done* (run this command, follow this pattern, don't touch this), it belongs in `CLAUDE.md`.
Does Claude read CLAUDE.md automatically, or do I have to point it there?: Automatically — when the repo is open in Claude Desktop (or you launched `claude` in the project root), Claude reads the `CLAUDE.md` as part of the project's context for every task, no prompt needed. That's the whole point: you write it once, and every later chat starts grounded in it instead of you re-explaining the basics.
How is this different from the map-the-codebase playbook?: Map-the-codebase is the *read* — a one-time tour that gives you, the human, a mental model of an unfamiliar repo. This playbook turns that read into a *durable asset*: a checked-in file that grounds every future task and teammate automatically. The map answers "what is this code?" once; the `CLAUDE.md` answers "how do we work in this repo?" forever. Run the map first, then distill it into the file.
We're a monorepo with many packages — one CLAUDE.md or several?: Both. Keep a root `CLAUDE.md` for what's true across the whole repo (shared conventions, the top-level architecture), and add a per-package `CLAUDE.md` in each package for its local commands and patterns. Claude reads the nearest one to the code it's working on, so a task in one package gets that package's specifics without the noise of the others.