CLAUDE.md — Teaching Claude How You Work

The Problem With Starting From Scratch Every Time

Every time you open a new Claude Code session, Claude wakes up with amnesia. It doesn't remember that you prefer plain language, that your app uses Supabase, that you always want it to run the tests before saying "done," or how your project is laid out. You end up re-explaining the same things over and over.

CLAUDE.md fixes this. It's a plain text file that Claude Code reads automatically at the start of every session. Think of it as a briefing note you hand to a new contractor on day one: "Here's how we do things around here." Once it's written, Claude shows up already knowing the rules.

---

What CLAUDE.md Actually Is

It's just a Markdown file named CLAUDE.md. No special syntax, no code. You write instructions in normal English (with some light structure), and Claude treats them as standing orders for the whole session.

The magic is that you don't have to tell Claude to read it. It loads on its own, every time, before you type your first message.

A tiny example:

# Project: Recipe Box

This is a recipe-sharing web app built with Next.js and Supabase.

## How I work
- I'm not a developer. Explain things in plain language.
- Always run the tests after making changes before telling me you're done.
- If you're unsure what I mean, ask before building.

## Conventions
- All database access happens server-side. Never expose secret keys to the browser.
- Keep components small and readable.

Drop that file in your project, and every future session starts with Claude already knowing it.

---

The Two Places CLAUDE.md Lives

There are two main homes for these instructions, and they serve different purposes.

The project file travels with the project — if you share the code, your teammates get it too. It answers "what is this project and how does it work?"

The global file is just for you. It answers "how does this person like to work, always?" Things like "explain things simply," "be concise," "always run linting before finishing." You write it once and it applies everywhere.

When both exist, Claude reads both. The global preferences and the project facts stack together.

Tip: There's also a CLAUDE.local.md for personal notes you don't want shared with the team. Add it to .gitignore so it stays on your machine only. And in a big project, you can drop a CLAUDE.md inside a specific subfolder — Claude reads it when it's working in that part of the code.

---

You Don't Have to Write It by Hand: /init

If you've got an existing project and don't know where to start, Claude Code can write the first draft for you.

Open Claude Code in your project and type:

/init

Claude will scan your whole codebase — the files, the structure, the build and test commands — and generate a starter CLAUDE.md describing what it found. It's rarely perfect, but it's a huge head start. You then trim and adjust it to taste.

Treat /init as a first draft, not the final word. The best CLAUDE.md files are shaped by hand over time as you notice Claude making the same mistake twice.

---

What Belongs in a Good CLAUDE.md

The best instructions are the ones that prevent the mistakes you keep correcting. Here's what's worth including:

Project facts

This is a SaaS dashboard. Frontend is Next.js, database is Supabase, deployed on Vercel.

Commands Claude should know

To run the app locally: npm run dev. To run tests: npm test. Always run tests before finishing.

Conventions and rules

Never put secret keys in files that start with NEXT_PUBLIC_. All database queries go through lib/db.ts.

Your working style

I'm non-technical. Explain trade-offs in plain language. Push back if I ask for something that's a bad idea.

Known gotchas

The users table has Row Level Security turned on — server-side reads must use the admin client.

Here's a fuller, realistic example:

# Project: Client Portal

A web app where our clients log in to view their invoices.
Next.js + Supabase + deployed on Vercel.

## Commands
- Dev server: `npm run dev`
- Tests: `npm test` (always run before saying a feature is done)
- Lint: `npm run lint`

## Rules
- All Supabase access is server-side via the service role client.
  Never expose the service key to the browser.
- Money values are stored in cents (integers), never decimals.
- Dates display as "Jan 15, 2026" in the UI.

## How I work
- I'm a founder, not an engineer. Keep explanations plain.
- Prefer the simplest solution that works. Nothing speculative.
- If a request is ambiguous, ask one clarifying question first.

---

Keep It Tight

A common beginner mistake is to treat CLAUDE.md like a dumping ground — pages and pages of instructions. Don't. Everything in it gets loaded into Claude's working memory at the start of every session, which means a bloated file eats into the space Claude has for the actual task and buries the rules that matter.

Rules of thumb:

• Short, scannable, specific. Bullet points beat paragraphs.
• Only include things Claude gets wrong without them. If Claude already does something right, you don't need a rule for it.
• Prune regularly. When a rule stops being relevant, delete it.
• Be concrete. "Write good code" is useless. "Keep functions short and add a comment explaining any non-obvious logic" is actionable.

A great CLAUDE.md is usually under a page. It's the 10–20 things that, if Claude forgot them, would cause real problems.

---

The Habit That Makes It Work

The single best habit: when you correct Claude on the same thing twice, add it to CLAUDE.md.

Caught yourself saying "remember, all money is in cents" for the third time? That's a CLAUDE.md line. Tired of telling it to run the tests? CLAUDE.md line. Over a few weeks, your file becomes a sharp, personalized briefing that makes every session smoother — and you stop repeating yourself.

---

Summary

• CLAUDE.md is a plain Markdown file Claude Code reads automatically at the start of every session — persistent instructions, no setup required.
• Project-level (CLAUDE.md in the project root) holds facts about that project; global (~/.claude/CLAUDE.md) holds your personal preferences for every project. Both load together.
• Run /init to auto-generate a starter file from an existing codebase, then refine it by hand.
• Include project facts, key commands, conventions, your working style, and known gotchas — concrete and specific.
• Keep it tight. It loads into memory every time, so include only the rules that actually prevent mistakes, and prune often.
• The winning habit: when you correct Claude on the same thing twice, write it down.