CLAUDE.md Template

Most operators write a bad CLAUDE.md first. They treat it like a README — explain the project, describe the architecture, list the team, add a few rules. By the end they have something that resembles documentation. Two weeks of real use later, half of it is dead weight.

The agent knew the tech stack from the codebase. The architecture section is stale. Three of the five team members have changed roles. The rules are phrased as principles and the agent treats them as suggestions.

This is normal. This bundle is the accelerant: the template that gets you to a working CLAUDE.md on the first attempt, the essay that explains the reasoning behind every section, and three worked examples that cover the three operator archetypes where the design decisions diverge.

What CLAUDE.md actually is

A system prompt you maintain. It loads at the start of every Claude Code session — every line costs context-window tokens on every session, whether or not it's relevant to what you're doing right now.

That cost is the only design constraint that matters: every line must earn its place on every session. Not "this might be useful someday." Every line, every session.

The mental model that helps: CLAUDE.md is the briefing you'd give a highly capable contractor on their first day. Not a product spec. Not a style guide. A briefing: who you are, what we're building, what the non-negotiables are, where the files live, and who to check with before doing anything irreversible.

What belongs in it

Project identity. 3-5 sentences. What is this project, what phase, who uses it, what's the stack. Not because the agent can't infer — it can read package.json — but because knowing the stakes shapes every judgment call. An agent that knows it's handling production customer data behaves differently than one working on a side project.

People. Names and roles of people who appear in conversation or files. Keep it to people whose names the agent will encounter and needs to recognize.

Agents. If you're running a multi-agent setup, list each agent, their scope, and their activation triggers. The activation-trigger column is the critical piece — without it, every agent answers every question and specialization collapses.

Rules. Non-negotiables. 5-10 max. Phrased as action constraints, not principles. "Never commit to main without a passing CI run" is a rule. "Be careful with git" is not.

Key terms. Project-specific abbreviations and vocabulary the agent will see in files and conversation. Not domain knowledge a senior engineer already has — your specific shorthand.

Active work. 2-5 bullets on current focus. This section goes stale fastest; keep it short so updating it stays low-friction.

Memory pointers. For structured context files the agent should read on demand — not inline. The pattern: CLAUDE.md holds the pointer, the content lives in memory/. This keeps the main file short and the content files comprehensive.

What NOT to put in it

This is the section every tutorial skips. It's also where most operators lose the most ground.

Things the agent learns from the codebase. File structure, dependency versions, API shapes — the agent reads these. Duplicating them in CLAUDE.md creates content that drifts out of sync and becomes actively misleading.

Generic best practices. "Write clean, well-documented code." Every model is deeply trained on this. Writing it in CLAUDE.md doesn't reinforce it — it just costs tokens.

Full-length reference documents. Don't paste a 30-page architecture doc inline. Pointer in Memory, content in a file. Inline costs tokens every session; pointed content costs tokens only when read.

Implementation details that change sprint-to-sprint. Current branch status, in-progress tickets, sprint criteria — these belong in sprint contracts and progress files, not CLAUDE.md. CLAUDE.md is supposed to be stable.

Aspirational rules you don't actually enforce. If a rule regularly gets violated without consequence, remove it. Rules that aren't enforced train the agent to treat your rules as suggestions.

The load-everything vs. read-on-demand decision

The most important architectural decision in a mature CLAUDE.md setup, and the least discussed.

Everything in CLAUDE.md loads on every session. If you have a 400-line CLAUDE.md, you're spending 400 lines of context on every session regardless of what you're doing. If you're debugging a CSS issue, 350 of those lines are probably irrelevant.

The alternative: move large context into memory/ files and keep pointers in CLAUDE.md.

CLAUDE.md holds orientation: project identity, people, agents, rules, key terms, active work, file structure. Small, relevant to most sessions.

Memory files hold depth: contact directories, financial models, architecture docs, decision logs. Large, relevant to specific sessions, read on demand.

A mature setup: CLAUDE.md under 200 lines, memory/ directory with a dozen focused files. The agent isn't overloaded at session start and depth is always available when needed.

The three examples

The bundle includes three worked examples because the right design decisions differ by operator type.

Solo founder, multiple ventures — wide scope, high reliance on agent memory, the memory-pointer pattern does the most work. The rules section focuses on cross-venture guardrails: no investor comms without review, no cross-venture data bleed.

Five-person startup — the challenge is consistency. Every team member's session starts from the same rules and vocabulary. The CLAUDE.md prioritizes shared discipline over personal customization. Rules are specific, the People section maps roles, the Active Work section coordinates across team workstreams.

Agency with client rotation — the structural challenge is client isolation. The base layer (agency rules, tools, voice) is consistent; per-client context loads from a client-context.md file in each client's repo. The CLAUDE.md establishes the isolation discipline explicitly: never mix client code, credentials, or data. Read client-context.md at the start of every client session.

The audit cycle

The discipline that separates good CLAUDE.md practice from bad: audit it regularly.

After the first week: read every line and ask whether it was relevant to what you actually did. Lines that weren't relevant are candidates for the memory pattern or deletion.

After one month: the structure has settled. Prune what's grown too large or add the memory pattern where context load is real.

After a major pivot: rewrite from scratch rather than patching. The project identity, active work, rules, and sometimes agents all change. CLAUDE.md from the prototype phase is usually wrong for the production phase.

The measure is not whether the file looks complete. The measure is whether sessions feel different. If you're still re-explaining things you've already explained, something's missing. If the agent is consistently overloaded with context that doesn't apply, something needs pruning.

Most operators find their stable shape around the second month of real use. The template gets you there faster.

— Michael, from the lab