Your first CLAUDE.md

By now you’ve probably noticed yourself repeating things. “This project uses pnpm, not npm.” “The dev server is npm run dev.” “Please don’t touch the legacy/ folder.” You say it, Claude listens, you get your work done — and then tomorrow you open a fresh conversation and say all of it again.

There’s a fix, and it’s almost embarrassingly simple.

Put a file named CLAUDE.md in your project, and Claude reads it at the start of every conversation — automatically, before you’ve typed a word.

It’s a prompt you write once instead of re-typing every time.

What goes in it

Anything you’d otherwise find yourself explaining over and over. A good starter CLAUDE.md is short and specific:

# CLAUDE.md

This is a recipe-sharing app. Astro frontend, small Node backend.

## Commands
- `npm run dev` — start the local server on port 4321
- `npm test` — run the tests
- `npm run build` — build for production

## Conventions
- Use pnpm, not npm.
- Don't edit anything in `legacy/` — it's being deleted next month.
- Prefer small, focused changes over big rewrites.

That’s it. No magic. You’re just writing down the stuff you’d say out loud, so you don’t have to say it again.

It’s just markdown — that’s the part people miss

People expect a config file: keys, values, some syntax they’ll get wrong. There’s none of that.

CLAUDE.md is plain English in a markdown file. It’s a note to Claude, written the way you’d write a note to a new teammate on their first day. If you can write a to-do list, you can write a CLAUDE.md.

That’s the whole reason it’s the single highest-payoff thing in this level: there’s nothing to learn except that it exists.

Make one right now

You don’t need a real project to feel how little there is to this. In the practice terminal you’re sitting in a small app called taskly. Write a CLAUDE.md into it with one command:

echo "Use pnpm, not npm. The dev server is npm run dev." > CLAUDE.md

The > takes what echo would have printed and drops it into a file instead of onto the screen — the same redirect you met in Level 1. Read it back to prove it’s really there:

cat CLAUDE.md

That’s the entire act of “adding a CLAUDE.md”: a line of plain English, in one file, at the top of the project. The only thing a real project adds is that Claude reads it for you — automatically, at the start of every conversation.

Try that part next, for real: in an actual project, save a CLAUDE.md, start a new conversation (close this one or run /clear), and ask something it could only know from the file, like “how do I run this project?” Claude answers correctly without you ever mentioning the file. That “wait, it just knew” moment is the whole point — from now on, that context rides along with every conversation in the project, for free.

What’s next

You put your CLAUDE.md in the project’s top folder. But it turns out that’s only one of three places this file can live — and the other two unlock some things the project file can’t. That’s next.