Your first CLAUDE.md

By now you’ve probably noticed yourself repeating things. “This is plain HTML — please don’t add a framework.” “Run it with npm start.” “Don’t touch messages.json — those are real messages from the contact form.” 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. Here’s one for the personal site you’ve been building:

# CLAUDE.md

This is my personal website — plain HTML and CSS, no framework.

## Commands
- `npm start` — run the local site on port 3000

## Conventions
- Keep it plain HTML and CSS. No build step, no framework.
- Don't edit `messages.json` — those are real messages from the contact form.
- 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.

Two ways to make one — both take a minute

You don’t have to leave the app to do this. There are two easy paths, and neither involves a single command.

The lazy way — just ask. Open your project in Claude Desktop and type this into the chat:

Create a CLAUDE.md at the top of this project. It's a plain HTML and
CSS personal site, run with npm start. Note that messages.json holds
real contact-form messages and should never be edited.

Claude writes the file and shows you the new CLAUDE.md in the visual diff — the same accept/reject panel you met when Claude proposes a change. Read it, click accept, and it’s saved. You’ve made your first CLAUDE.md without typing a path or a command.

The hands-on way — the file pane. Prefer to write it yourself? In the Desktop app’s file pane (the sidebar listing your project’s files), create a new file named exactly CLAUDE.md at the top of the project, type your notes into it, and save. Same file, same result — you just authored it directly instead of asking Claude to.

Either way, the act of “adding a CLAUDE.md” is the same: a few lines of plain English, in one file, at the top of the project. The magic part is what happens next — Claude reads it for you, automatically, at the start of every conversation.

See it for yourself: with the file saved, start a new conversation (a fresh chat, or /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 CLAUDE.md. 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.