Your first CLAUDE.md
The file your AI reads on every session. What goes in it, what doesn’t.
What CLAUDE.md is
CLAUDE.md is a markdown file at the root of your project. When you start a Claude Code session in that project, Claude reads this file before it reads anything else. It’s the instruction layer that sits above the code.
You can think of it as a permanent “here’s what you need to know about this project” brief that the agent loads automatically. Without it, every session starts from zero. With it, every session starts with shared context.
Most operators get the most value from CLAUDE.md within the first 24 hours of writing one. The conversations stop having “wait, which framework are we using” turns. The agent stops asking questions you’ve already answered five times. You stop re-explaining your stack to a fresh session.
This lesson is the cheapest, highest-leverage habit in the operator’s toolkit. By the end of it, you’ll have your first CLAUDE.md.
The 5-minute story
I asked Claude to add a contact form to a website. Simple ask. Three turns of follow-up questions later — “which form service?” “which validation library?” “what visual style?” — I realized I was answering the same questions I’d already answered the previous week, on a different feature.
The agent wasn’t being slow. It was doing its job. It just didn’t know anything about my project. Every session, it started from zero. Every session, I re-taught it the basics.
I stopped, opened a CLAUDE.md, and wrote 28 lines: the stack, three conventions, where things lived, three rules of “don’t do these.” Five minutes of work.
The next agent session needed zero of those clarifying questions. The session after that, same. Every conversation got 3-5 turns shorter. Across thirty conversations, that’s 90+ turns saved — easily an hour back. From a 5-minute file.
That’s the leverage. CLAUDE.md is the cheapest productivity gain in your toolkit. The reason most people don’t have one is that they don’t know what to put in it. So this lesson is mostly about that.
Three ways CLAUDE.md goes wrong
Most first attempts fall into one of these patterns. Hover any card to see the diagnosis.
The kitchen sink
Wishful preferences
The stale snapshot
The fix in all three cases is the same: every line in CLAUDE.md must be something that changes the agent’s behavior. If a line doesn’t change behavior, it’s noise. Cut it or move it elsewhere.
The audit move
The diagnostic to apply when reviewing a CLAUDE.md (yours or someone else’s):
Read my CLAUDE.md.
For every line, ask: would the agent's output be different if this
line were missing? Mark each line:
- KEEP — yes, removing it would change agent behavior
- CUT — no, this is description or wish, not a rule
- MOVE — context that belongs elsewhere (memory, wiki, decision log)
Output the trimmed CLAUDE.md as a code block. The goal is the
shortest file that still produces the right behavior.Forces every line to justify itself in terms of behavior change.
The output gets you three buckets:
- KEEP — lines that change behavior. These earn their space.
- CUT — descriptions, wishes, generic preferences. Delete.
- MOVE — context that’s real but lives elsewhere: long-form project history → wiki, contact details → memory, decisions → decision log.
A good first-week CLAUDE.md is 20-50 lines. A mature multi-venture one (the kind I run) might be 100-150 lines. Anything north of 200 means you’re using CLAUDE.md as a documentation site instead of an instruction file. Move stuff out.
Annotated transcript
A real conversation that should have been a CLAUDE.md. Watch for the moment the operator stops the conversation and writes the file. Click any pinned annotation under an agent reply to expand the commentary.
Five turns of clarifying questions. Then the operator stops, writes the file, and never asks them again.
- operator
Add a contact form to the homepage.
- agent
Sure — I'll create a form with name, email, and message fields. Should I use a third-party service like Formspree, or wire it to a custom endpoint?
- operator
We're on Netlify. Use Netlify Forms. Match the existing visual style.
- agent
Got it. I'll use Netlify Forms with a hidden honeypot field. For visual style, I'll match the existing components — though I notice there's no design tokens file. Mind if I extract some?
- operator
Stop. Let me write this down once. Where should it go?
- agent
CLAUDE.md at the project root. Three sections will cover most of what we just hit:
1. Stack — "Netlify (auto-deploy from main), Next.js 16, Tailwind 4, design tokens in app/trupath.css."
2. Conventions — "Forms use Netlify Forms with honeypot. Match existing components; don't extract new design tokens without approval."
3. Routing — "Site features → /app, Labs publication → /app/labs (different shell)."Any new agent session will read these in 5 seconds. You'll never re-explain.
- operator
Good. Write it.
- agent
Drafted at /CLAUDE.md, 28 lines. Reading now: covers stack, conventions, routing, three lines of "don't do these things" (no analytics scripts, no auto-bumping deps, no rewrites without a decision-record entry). Save?
The skeleton — copy-paste this and fill in your values
A working CLAUDE.md skeleton. Replace the bracketed values with your real ones, delete sections that don’t apply, and save it at your project root.
# [Project name]
## Stack
- Hosting: [Netlify / Vercel / self-hosted on / etc.]
- Framework: [Next.js 16 / Astro 5 / Vite + React / etc.]
- Styling: [Tailwind v4 / Pretext / vanilla CSS / etc.]
- Database: [Supabase / Postgres / Redis / none]
- Deploys: [auto on push to main / manual / etc.]
## Key people
- [Name] — [role] — [email or contact]
## Active work
- [URGENT item], [target date or trigger]
- [In-progress item]
## Conventions
- [Specific convention #1 — observable, enforceable]
- [Specific convention #2]
- [Specific convention #3]
## Rules
- Never [specific action you want blocked]
- Always [specific action you want done]
- Before [trigger], do [thing]
## Where things live
- [Concept] → [file path or folder convention]
- [Concept] → [file path or folder convention]
## Key terms
- [Acronym] = [expansion]
- [Acronym] = [expansion]
You don’t need every section. A solo project with one stack might be 12 lines. A multi-venture vault with 5 agents might be 120. Length is a function of complexity, not effort. Aim for as short as the project allows.
Prompt kit
Three prompts for keeping CLAUDE.md alive over time. Save in a personal snippets file.
Read my CLAUDE.md.
For every line, ask: would the agent's output be different if this
line were missing? Mark each line:
- KEEP — yes, removing it would change agent behavior
- CUT — no, this is description or wish, not a rule
- MOVE — context that belongs elsewhere (memory, wiki, decision log)
Output the trimmed CLAUDE.md as a code block. The goal is the
shortest file that still produces the right behavior.Read my CLAUDE.md and look at the last 5 conversations
in this project. For each conversation, ask: did the operator
have to explain something the agent should have already known
from CLAUDE.md?
Output a list of additions to CLAUDE.md, each as a single
declarative line.My CLAUDE.md was last edited <N> weeks ago. Walk every line
and check it against the current state of the project. Flag any
line that:
- Mentions a person, model, or tool we no longer use
- Refers to a priority that has shifted
- Describes a convention we've since changed
Suggest the rewrite for each.Apply this — write your first CLAUDE.md right now
20-minute exercise. Don’t over-think. Version 1 will be wrong. Version 5 is right. Iteration is the feature.
Build your first CLAUDE.md
Each step takes ~5 minutes. Progress saves automatically.
- 01Open your project root. If there's no CLAUDE.md, create one.Just touch the file. Don't write yet.
- 02Drop in the skeleton from this lesson. Replace placeholders with your real values.Stack, agents (or skip if solo), key terms, three rules. That's it.
- 03Spend exactly 10 minutes filling it in. No more.If you can't finish in 10 min, the entries are too long. Trim.
- 04Open a new Claude Code session in that project. Ask it: "summarize what you know about this project."What it knows = what's in CLAUDE.md. If the summary is wrong, the file is wrong. Iterate.
- 05Add one line every time you have to re-explain something to Claude. Trim a line every time you notice one isn't doing work.CLAUDE.md is alive. The first version is wrong. Version 5 is right.