Don't Just Start Typing — Brief Claude First (CLAUDE.md)

Your project folder is open, Claude's pointed at it, and every part of you wants to just go — "build me the home page!" Hold on one second, though. There's a thirty-second move to make first, and skipping it is the single most common way a first project quietly turns to chaos.

The helper who forgets every morning

Picture the most capable assistant you've ever had. Quick, tireless, genuinely good at the work. There's just one catch: every time you sit down together, they've forgotten everything about your project. Not because they're careless — it's that each session starts with a clean, blank memory. Yesterday you explained it's a recipe site, just for family, keep it simple. Today? Gone. You're explaining it all again.

That's Claude Code, told honestly. Within a single sitting it remembers everything you've said. But each new session is a fresh start — it doesn't carry over what you told it last time. So if the only place you ever explain your project is the chat box, you're re-explaining forever. Claude fills the gaps with guesses, the guesses miss what you meant, and the whole thing starts to feel scattered and a little chaotic.

Pin one note by the door

Here's what you'd do with a real helper like that. You wouldn't re-explain every morning — you'd write the important stuff down once, on a note by the door, and they'd read it first thing every time they came in.

Claude Code has exactly that note. It's a plain text file called CLAUDE.md, and it sits right in your project folder. (Remember that .claude cupboard we spotted a couple of lessons back? It can live in there too — either spot works.) The rule that makes it matter is simple: Claude reads it at the start of every session, before it does anything else. Write your project down once, and from then on Claude begins every session already knowing it.

What to write on the note

So what actually goes on it? Less than you'd think — and that's the point. A good CLAUDE.md is short and high-signal: the handful of things you'd otherwise keep re-explaining. Roughly:

• A quick overview — what you're building and who it's for. A line or two. "A simple recipe website, just for me and my family."
• Your preferences — the "always do it this way" stuff. The big one for us: "I'm not a coder, so keep everything simple and explain things in plain English."
• A short list of don'ts — anything you already know you don't want.
• Corrections you'd otherwise repeat — every time Claude gets the same thing wrong, add a line so it stops happening.

Here's what a whole one might look like for the Recipe Box. Notice how small it is — this is a finished file, not a snippet:

# Recipe Box

A simple website where I collect my favourite recipes — just for me
and my family. I'm not a coder, so keep everything simple and explain
your choices in plain English.

## Always
- Keep the design clean and easy to read.
- Check with me before adding anything complicated.

## Don't
- Don't add logins or user accounts.
- Don't pull in fancy tools I'd have to maintain.

That's the whole thing. A screenful. Every line on it is a fact that changes how Claude works — not a description of the project written for its own sake.

What to leave off — and why it matters more than you'd guess

Now the half that trips people up, because the instinct runs exactly backwards. Once you have a note Claude always reads, it's tempting to pile everything onto it — every detail, every plan, the full story of the project. Resist that. CLAUDE.md is a short briefing, not a filing cabinet. A few things that don't belong:

• A full write-up of the project. That's documentation for people, and it has its own home (more on that in a second). The note is a briefing for Claude.
• Step-by-step procedures. "Here's exactly how I add a new recipe, in nine steps" isn't a fact to hold — it's a routine. Routines get a home of their own, and that's the very next lesson.
• Anything that changes every week. Plans, to-do lists, "what we're working on today." It goes stale fast, and a stale note is worse than no note at all.

And here's the why, which is the part actually worth remembering. That note gets read in full, at the start of every session — so it takes up room. Cram it with clutter and you do two kinds of damage at once: you waste that space, and — this is the surprising bit — you make Claude follow it less reliably. A short, sharp note gets followed closely. A long, rambling one gets skimmed — by Claude, exactly as it would be by a person. Short isn't just tidier here; it's what makes the thing work. It's also the tip the people who build Claude Code repeat more than any other: keep it short.

You don't write it — Claude does

If "set up a config file" just made your stomach drop, relax — you don't author this thing by hand. You do the thing you're already good at: you talk. Tell Claude, in plain English, what you're building and how you like things done, then ask it to write the CLAUDE.md from that. It turns the conversation into the file, and you read it over and tweak a line if you want. (Keep the dial on Plan or Ask from last lesson while it does — your call, as always.)

Starting from a project that already exists? There's an even quicker route: a built-in /init command that reads through what's already there and drafts a starting CLAUDE.md for you — and if you've already got one, it suggests improvements instead of steamrolling it.

One small thing, so it doesn't trip you up: if you just say "remember this," Claude tends to jot it into its own private notes — not your CLAUDE.md. To put something on the shared note, say so plainly: "add this to CLAUDE.md."

But where does all my detail go?

You might be thinking: my project does have real detail — notes, specifics, the longer story. Where does that live, if not here? Good instinct. It goes in its own separate file that Claude can look at when it's actually needed, which keeps CLAUDE.md itself the short front-page briefing rather than the encyclopedia. There's a tidy way to set that up, and we'll get to it down the road. For now, just hold the shape: short note out front, deep detail tucked in its own place.

So that's the move that saves you from the chaos: before you build, brief Claude once, on a note it reads every single time. You've now told it what you're making and how you like it. Which raises the other half — not what you're building, but how you like particular jobs done. That nine-step way you add a new recipe? It doesn't belong on the note. It belongs in something built exactly for repeatable routines — called a skill — and that's where we're headed next.