CLAUDE.md — the Project's Brain

Claude forgets everything — on purpose

Claude Code has zero memory between sessions, by design. Yesterday's session taught it your folder structure and your conventions; today's session knows none of it. That sounds like a flaw. It's actually the deal that keeps sessions fast, private and cheap — and it comes with one big exception you control: files.

CLAUDE.md, in your project root, is the most important of those files: Claude Code auto-loads it at the start of every session. Whatever it says is simply known, every time, without you repeating yourself. It's the project's brain.

/init writes the first draft

Don't write it from scratch. In a session, run /init once: Claude scans the project — folders, configs, package.json, README — and generates a first draft. That's the easy 80%. The valuable 20% is what you do next.

Then you edit it — lean, under ~60 lines

Trim and shape the draft yourself until it covers exactly six things, briefly:

  1. Stack — what the project is built with, one or two lines.
  2. Folder map — where things live, so Claude doesn't explore to find out.
  3. Key file paths — the exact files that matter most ("the layout is src/layouts/Layout.astro").
  4. Conventions — naming, patterns, things that must stay true ("components are PascalCase", "site stays fully static").
  5. Commands — how to run, build and preview.
  6. Standing rules — the workflow you want on every task ("read docs/TODO.md before any task; update docs/STATUS.md and commit after").

A realistic complete example — this is genuinely enough:

# MyRecipes

Static Astro site: recipe pages + search. Deployed on Cloudflare Pages.

## Stack
- Astro (latest), vanilla CSS, no client frameworks

## Folder map
- src/pages/ — file-based routes
- src/components/ — PascalCase .astro components
- src/data/recipes.ts — all recipe content lives here

## Commands
- npm run dev · npm run build · npm run preview

## Rules
- Site stays fully static — no SSR, no cookies, no trackers.
- Read docs/TODO.md before any task; update docs/STATUS.md + commit after.

Why lean matters so much

Remember the context chapter: everything in the session is re-sent with every message. CLAUDE.md is in every session from message one — so a bloated CLAUDE.md is a tax on every single message, forever. Sixty sharp lines beat six hundred thorough ones. If a detail only matters for one task, it belongs in that task's prompt, not in the brain.

Quick additions with #

Mid-session, whenever you catch yourself correcting Claude on something that will be true forever — start a line with #: 

# always use pnpm, not npm
# currency is INR with Indian digit grouping (₹1,23,456)

Each one is appended to CLAUDE.md on the spot. Correct once, remembered in every future session. Prune these occasionally so the file stays lean.

Real-world example — this website. Siazly's CLAUDE.md is about forty lines: the stack (Astro + Tailwind, fully static), a folder map, exact paths to the layout and data files, conventions ("site MUST stay static", "never add cookies or tracking"), the three npm commands, and one standing rule — read the fix queue before any task; build, check off and commit after. Every session on the site starts already knowing all of that.

Up next: CLAUDE.md holds what's always true. The other half of memory — where we left off, what's next, why we chose X — lives in three small files in docs/.

FAQ

Frequently Asked Questions

What is CLAUDE.md?
A markdown file in your project root that Claude Code auto-loads at the start of every session. Whatever it says — stack, folder map, conventions, commands, standing rules — Claude simply knows, without you repeating it.
How do I create a CLAUDE.md?
Run /init once in a session: Claude scans the project and writes a first draft. Then edit it yourself — trim it to the six essentials (stack, folder map, key paths, conventions, commands, standing rules).
Why should CLAUDE.md stay under about 60 lines?
Because it's loaded into every session and re-sent with every message, a bloated CLAUDE.md is a permanent tax on speed and cost. Sixty sharp lines beat six hundred thorough ones; task-specific detail belongs in the task's prompt.
How do I add to CLAUDE.md without opening the file?
Start a message with # — e.g. # always use pnpm, not npm — and Claude Code appends it to CLAUDE.md immediately. Ideal for capturing a correction the moment you make it.