Skip to content

5.2 CLAUDE.md: Your Project's Brain

One file changes everything: CLAUDE.md, sitting in your project root, read by Claude Code automatically at the start of every session. It's your project's standing orders — the briefing that makes session #47 start as smart as session #46 ended. This lesson writes yours, tests it, and teaches the iteration habit that keeps it earning.

What you will learn

  • Explain what CLAUDE.md is, when it's read, and what belongs (and doesn't belong) in it.
  • Write an effective CLAUDE.md for your real project using the five-section pattern.
  • Iterate it like the living document it is — including making the agent maintain it.

Builder principle

If you've said it to your agent twice, it belongs in CLAUDE.md. If it's in CLAUDE.md, never say it again.

What it is, mechanically

At session start, Claude Code can discover CLAUDE.md in supported locations and add applicable instructions to context. Treat the file as durable guidance, then verify that the current tool version found and followed the guidance for the task.

The five-section pattern

There's no mandated format — it's your document. But this shape has earned its keep across thousands of projects:

# ProjectName

## What this is
One paragraph. What the project is, who it's for, what stage it's at.

## Layout
Where things live — the 5–10 paths that matter and what each is:
- index.html — the whole site (single page)
- assets/ — images, favicon
- SHIPPING.md — current goal and scope (read at session start)

## Conventions
How we do things HERE:
- Style: match existing card pattern for any new section
- Voice in copy: warm, direct, no corporate speak
- Mobile first: verify at 375px before calling anything done
- Commits: small, one logical change each

## Commands
How to run/check things (exact commands, copy-pasteable):
- Preview: open index.html
- Deploy: push to main → GitHub Pages

## Boundaries
What NOT to do:
- Don't add frameworks or build tools — plain HTML/CSS/JS only
- Don't touch assets/logo.svg (client-provided, final)
- Don't create new top-level files without asking

Notice the character of every line: short, factual, actionable. This file is instructions, not documentation prose. Every token is spent from your context budget every single session — make each one earn the slot.

What does not belong

  • Long histories and essays — that's your second brain's job (5.4); link, don't inline.
  • Anything secret — CLAUDE.md gets committed with the repo. Same rule as always (3.5).
  • Wishes disguised as facts — "code should be well-organized" instructs nothing. "New CSS goes at the end of the style block, commented with its section name" instructs.
  • Stale truth — a wrong CLAUDE.md is worse than none; the agent believes it. Iteration (below) is part of ownership.

Keep v1 short and plain. The value is testable: project instructions such as "match the Services cards" become available in a fresh session without being restated. Recheck and update the file when the project changes.

Treat it like the highest-traffic doc in the repo, because it is. High-value entries beyond the basics: build/test/lint commands with flags, architecture decisions with a one-line why (agents honor reasons better than rules), the tricky module map ("payments logic lives in services/, NOT in api/ — legacy split"), and links to deeper docs by path. Team play: CLAUDE.md is shared infrastructure — PR changes to it like code, because a bad instruction now misleads every teammate's agent too.

The iteration habit

Your CLAUDE.md is born adequate and grows sharp through one habit:

Every time the agent does something you had to correct — ask: "would a line in CLAUDE.md have prevented that?" If yes, add it. On the spot.

The elegant move: make the agent do it.

That's the second time you've put new styles inline instead of in
the style block. Update CLAUDE.md so this never happens again —
add it under Conventions, phrased as a clear rule.

The file becomes a ratchet: every mistake it absorbs is a mistake retired from the project. Six weeks in, your agent behaves like it's been here — because, via the file, it has.

Try it now

  1. In your quick-win project, write CLAUDE.md — five sections, honest v1.
  2. Prove it works: /clear, then start a session with just What are this project's conventions and boundaries? It should answer from the file, unprompted.
  3. Run a small real task and watch for behavior shaped by the file (style matched, boundary respected).
  4. Add one rule using the correction habit — ideally via the agent itself — and commit the file. It ships with the project from now on.

Check your understanding

  • When can CLAUDE.md be loaded, and what should you verify in a session?
  • Name the five sections and the character every line should have.
  • Give one example each of a wish-vs-instruction rewrite and a thing that must never be in the file.
  • What's the iteration trigger, and why does making the agent write the rule work so well?