How to write a CLAUDE.md file as a product manager

What is this file supposed to do for a product manager?

It answers the questions you would otherwise answer again at the start of every session: which document is the current one, what this product is for, and what the agent is not allowed to decide on its own. Claude Code reads CLAUDE.md at the start of every conversation, which makes it the one place where "we already decided that" survives the fact that each session starts with no memory of the last.

Builders Camp's Building your AI Operating System certification material describes the file as a router more than a rulebook: a lightweight index that points at the files holding the real detail, plus the global operating rules that apply everywhere. That framing is what keeps it short. The glossary entry on context architecture covers the wider structure this file sits at the top of.

Where does it go, and which copy wins?

Four locations, each with a different scope.

Location	Scope	Shared with
Managed policy path	Every session on the machine	The whole organisation
~/.claude/CLAUDE.md	All your projects	Just you
./CLAUDE.md or ./.claude/CLAUDE.md	This repository	The team, through git
./CLAUDE.local.md	This repository	Just you, add to .gitignore

They do not override each other. Every discovered file is concatenated into context, ordered from the broadest scope down to the one closest to where you launched the session, so the project file is read after your personal one. Files in subdirectories are found too, but load on demand when Claude reads something in that directory rather than at launch.

The practical consequence is that contradictions are not resolved for you. If your personal file says to write in British English and the project file says American, one of them wins and you will not be told which.

What does a product manager's CLAUDE.md actually look like?

Builders Camp's Building with Claude Code practical challenge asks participants to write one as a project constitution under 30 lines, containing the project purpose, the source-of-truth files, at least one explicit stop line, the git workflow rule and the testing rule. Here is that shape applied to a product repository rather than a service.

## What this is
A subscription billing product for small teams. Self-serve only.
No enterprise contracts, no custom pricing.

## Source of truth
- Current scope: docs/product/this-quarter.md
- Approved specs: docs/specs/ (files here are signed off)
- Metric definitions: docs/metrics/definitions.md
Anything in Slack or a comment thread is not a decision until it lands here.

## Stop lines
- Never change pricing copy, plan names or trial length without human approval.
- Never write a number into a spec that is not in docs/metrics/definitions.md.
- Never mark a spec approved. Only a human moves a file into docs/specs/.

## How we write specs
- Problem, evidence, decision, non-goals, open questions. In that order.
- Every claim about user behaviour cites a ticket ID or a query.
- Open questions stay open. Do not resolve them by guessing.

Every line there is true in every session, which is the test. The quiz for Building with Claude Code puts it as the single constraint on the file: only rules that are always true, project-wide and persistent across sessions, never situational ones.

Notice what is absent. There is no folder listing, no dependency list, no architecture overview. Claude can read those off the repository itself, and Claude Code's own /doctor checkup proposes trimming exactly that category out of a checked-in file while keeping the pitfalls, the rationale and the conventions that differ from what a tool would assume by default.

How do you start one, and how do you know it loaded?

Run /init and Claude reads the codebase and writes a starting file with the build commands, test instructions and conventions it can discover on its own. Treat that output as the half you did not have to write, then add the half it could never infer: the source-of-truth list, the sign-off boundaries, the stop lines. If a file already exists, /init suggests improvements rather than overwriting it.

Verification is a separate step and people skip it. Run /context in a session and check the list under Memory files. A file that is not on that list is not being read, however carefully it was written, and a misplaced file in a monorepo subdirectory is the usual reason. /memory opens the files for editing without leaving the session. If your repository already carries an AGENTS.md for another coding tool, Claude Code does not read it, so import it from CLAUDE.md rather than maintaining two divergent copies.

What quietly makes the output worse?

• Length. Past roughly 200 lines the file costs more context and gets followed less consistently, which is the opposite of what the person adding line 240 believes is happening.
• Situational rules. "When we are close to a release, prefer smaller diffs" is true sometimes, so the agent now has to guess when, and the guess pollutes the rules that were unconditional.
• Restating the codebase. A directory tree in the file is a second copy that goes stale, and staleness in a memory file is worse than absence because it is asserted with the same confidence as the true lines.

The failure is slow, which is why it is hard to notice. Nothing breaks the day you add the fourth conditional rule. Adherence just degrades a little, and six weeks later the file is long, partly wrong, and everyone has quietly stopped trusting it.

Should it be one file or several?

Split it once it grows, but understand what each split buys. An @path import expands and loads at launch, resolving up to four hops deep, so it organises the content without reducing what it costs in context. A file in .claude/rules/ with a paths field in its front matter is different: it loads only when Claude works on files matching that pattern, which genuinely keeps it out of sessions where it is irrelevant.

The rule of thumb that holds up: global operating rules and the router stay in CLAUDE.md, anything scoped to one area moves to a path-scoped rule, and any multi-step procedure moves to a skill, where it loads on demand instead of every time. All three compete for the same budget, which the glossary entry on the context window explains, and the file you load unconditionally is the one paying rent in every session. Personal notes about your own sandbox, your test data or your preferred phrasing belong in CLAUDE.local.md, gitignored, so your teammates never read them.

What CLAUDE.md cannot do

It cannot enforce anything. Anthropic's own documentation is direct about this: the file is context the model reads and generally follows, not configuration the client applies, and a rule that must hold regardless of what the model decides belongs in a PreToolUse hook instead. The glossary entry on automation hooks covers that boundary in full.

So the stop lines in the example above are real instructions with a real effect, and they are still not a control. If "never change pricing copy without approval" is a compliance requirement rather than a preference, the file is where you explain it and a hook is where you enforce it. Writing it in one place and assuming the other is covered is the most common mistake product managers make with this file.

Builders Camp teaches both halves. Building with Claude Code covers CLAUDE.md and context architecture as its first module, taught by Guilherme Salgueiro across 1 week with 2 live sessions and 9 microlessons, then moves into skills, agents, memory and the governance layer. Building your AI Operating System, taught by Inês Lourenço over 2 weeks with 3 live sessions and 11 microlessons, applies the same context layer to product work rather than code: research synthesis, PRD pipelines and the decisions underneath them. Both belong to the AI Agentic Builders Expert Track.

Write the file the day you are annoyed

The best trigger for editing this file is irritation. The moment you catch yourself retyping a correction you typed last week, that correction is a line. Anthropic's guidance says the same thing from the other direction: add to the file when Claude makes the same mistake a second time, when a review catches something the agent should have known, or when a new teammate would need the same context to be useful. Written that way, the file grows out of real friction instead of out of an hour spent imagining what an agent might need, and the difference shows in how much of it is still true a quarter later.

See the Building with Claude Code bootcamp for the context architecture module, or Building your AI Operating System for the product-side version of the same system. The glossary entry on agent memory covers the layer that accumulates on its own, next to the one you write by hand.