Claude Code for Beginners – Part 3: Teach It About Your Project

Here’s a thing that happens around week two. You’ve found a rhythm with Claude Code, and then you notice you’re typing the same sentences over and over.

We use pnpm, not npm. Tests go next to the file, not in a tests folder. Don’t touch anything under generated/.

Every session. From scratch. Because every session does start from scratch — a fresh context window, no memory of yesterday.

CLAUDE.md is how you stop doing that.

The thirty-second version

CLAUDE.md is a plain markdown file in your project. Claude Code reads it at the start of every session. That’s the entire feature.

Write down the things you’d otherwise re-explain, and you stop re-explaining them.

Let /init write the first draft

Don’t start from an empty file. Open a session in your project and run /init.

It reads your codebase and writes you a starting CLAUDE.md — build commands, test commands, whatever conventions it can work out on its own. If you already have one, it suggests improvements instead of flattening what’s there.

> /init
⏺ Read package.json, tsconfig.json
⏺ Explored src/ (34 files)
 
  I've written CLAUDE.md with your build and test
  commands, plus the conventions I could infer.
 
✓ Created CLAUDE.md (48 lines)

Then edit it. The generated file is a starting point, not the finished thing — the valuable part is everything it couldn’t infer.

What actually belongs in it

My rule: if you’d say it to a new teammate on their first day, it belongs. If they could work it out by reading the code, it doesn’t.

• Worth writing down. Commands you always run. Conventions that differ from the tool’s default. Decisions that look wrong without the reason behind them. The “never do this here” rules.
• Leave it out. The directory layout, what each file does, the dependency list. Claude reads all of that faster than you can type it, and every line you write is context it spends on every future session.

So a good one is short and a bit blunt:

# Project notes

- Build with `npm run build`. Dev server is `npm run dev`.
- Posts live in `src/content/blog/`. The filename is the URL slug.
- Tables in posts are raw HTML, not markdown pipes. Yes, on purpose.
- Never edit anything under `dist/` — it's generated.

Two things that matter more than they sound like they do. Be specific enough to check — “use 2-space indentation” works, “format code nicely” doesn’t. And keep it under about 200 lines, because it’s context every single session, and a long file gets followed less reliably than a short one.

Where these files live

There’s more than one CLAUDE.md, and knowing which is which saves a lot of confusion later.

That last part is the bit worth holding on to. They don’t compete. Everything found gets concatenated, ordered from the filesystem root down to where you started the session, so the files closest to your project are read last.

In practice you’ll use two of them: ./CLAUDE.md for things the whole team needs, and ./CLAUDE.local.md for your own stuff — sandbox URLs, test data, the notes nobody else wants. Gitignore the local one.

It takes its own notes, too

There’s a second memory system sitting alongside all this, and it took me a while to notice it: auto memory. Claude writes this one, not you.

When you correct it — “no, we always use pnpm” — it can decide that’s worth keeping and save it for next time, without being asked. Those notes live in ~/.claude/projects/<your project>/memory/, they’re plain markdown, and you can read, edit or delete any of them.

It’s on by default. To see what it’s been keeping, run /memory and open the auto memory folder. If you’d rather it didn’t, there’s a toggle on the same screen.

The split worth remembering: CLAUDE.md is what you told it. Auto memory is what it noticed.

Check the thing actually loaded

This is the step people skip, and then spend an afternoon wondering why nothing changed. Run /context and look for the Memory files section. If your CLAUDE.md isn’t listed there, Claude genuinely cannot see it — usually because it’s sitting in a directory that isn’t at or above where you started the session.

⚠️ CLAUDE.md is context, not law. It’s a strong nudge, and a well-written one gets followed most of the time — but it’s not enforcement. If something absolutely must happen every time, like a formatter or a check before every commit, that’s a hook’s job, not a memory file’s. We’ll get to those.

Next time

Part 4 is about context — the thing you’ve been quietly spending all session without watching the meter. /clear, /compact, and why starting a fresh conversation so often fixes a Claude that’s gone vague on you.

For now, go run /init on something. Even the draft it hands you is usually better than the nothing you have today. 🙂