L3Lesson 3

Write Your First CLAUDE.md

After this, you'll have a working CLAUDE.md with your first five project-specific rules, each written from a real mistake rather than speculation.

Before you start

Before diving in, complete Plan Before You Code so your first five rules come from gaps you spotted in real plans rather than from speculation.

The idea

CLAUDE.md is the file that Claude Code reads at the start of every session, before you type anything. Whatever is in it persists. Every session starts with it already loaded. This is the answer to the hardest problem at Level 3: the model makes the same mistake again and again because there is nowhere for lessons to go. CLAUDE.md is where they go.

Here is the before and after: Five rules from one real project: "Never use var. Always const or let." "All database queries go through the query-builder utility in src/db/query.ts, not raw SQL." "This project uses Tailwind v4. Do not suggest v3 class names." "Test files live in src/__tests__, not next to the source files." "Never add console.log to production code." Each of these rules came from a mistake that happened at least once. None of them are advice Claude already knows. They are project-specific constraints.

The test for every line: would Claude do the right thing without this rule? If yes, delete it. If no, keep it. General advice ("write clean code", "handle errors gracefully") fails this test every time. Project-specific constraints ("use query.ts, not raw SQL") pass it. Start with five rules from real mistakes. That is the whole first CLAUDE.md.

Try it (20 min)

Watch out for

Writing rules before you have real mistakes to prevent. Speculative rules waste tokens and rarely match actual behavior.
Adding general best practices like "write readable code." Claude already knows these. They cost tokens and change nothing.
Making rules too long. "Always use the query-builder in src/db/query.ts for all database calls" is one sentence and it works.
Forgetting to start a new session after editing CLAUDE.md. The new rules only load at session start.
Never updating it. After any session where Claude made the same mistake twice, add the rule that would have prevented it.

Paste this into Claude:

I want to write my first CLAUDE.md. Help me do it correctly. Ask me: (1) What are the top three mistakes Claude has made in my project that it repeated more than once? (2) What tech stack, versions, or libraries does this project use that Claude might get wrong? (3) Are there specific files, utilities, or patterns I always want Claude to use instead of the default approach? (4) What should Claude never do in this codebase (forbidden patterns, wrong libraries, wrong file locations)? After I answer, write me a CLAUDE.md under 30 lines with only the rules that pass this test: would Claude do the right thing without this rule? If no, it stays. If yes, delete it.

What good looks like:

You answered each of the four questions with at least one real example from your project
Your CLAUDE.md has at least five rules and every one came from a real mistake or a real project constraint, not speculation
Every rule passes the deletion test: Claude would behave differently without it
The file is under 30 lines
You created the file in your project root and started a new session to verify it loaded and affected Claude's behavior

What a good response looks like:

Based on your answers, here is your first CLAUDE.md. Every line came from a mistake you described.

```
# Project Rules

## Stack
- This project uses Tailwind v4. Do not suggest v3 class names (e.g. use `text-sm` not `text-base/sm`).
- Database layer: all queries go through src/db/query.ts. Never write raw SQL or use the Prisma client directly.
- TypeScript strict mode is on. Never use `any`. Use `unknown` and narrow it.

## Patterns
- API responses always use the ApiResponse wrapper in src/types/api.ts. Never return plain objects from endpoints.
- Errors are logged via src/lib/logger.ts. Never use console.log or console.error in production code.

## File locations
- Tests live in src/__tests__/. Never create test files next to source files.
```

Lines I removed from your draft: "Write clean, maintainable code" (Claude knows this), "Handle errors gracefully" (too vague to act on), "Follow TypeScript best practices" (already covered by strict mode). Those three lines cost tokens every session and change nothing. The six lines above will change behavior the first time you open a new session.

When this breaks

Breaks when rules are written from imagined risks rather than observed failures because there is no signal that any line actually changes behavior, only the cost of loading them every session.
Breaks when general advice fills the file ("write readable code", "handle errors gracefully") because the model would do these by default and the file becomes pure tax with no return.
Degrades over time when the file grows without a deletion ritual because stale rules accumulate, the signal-to-noise drops, and you stop trusting the file to influence behavior.

Claude can do it for you

After any session where Claude made a mistake you have seen before, say: "Add a rule to my CLAUDE.md that would prevent this mistake. Write the exact line." Then copy that line into your file. That is the compounding habit.

You can now

Produce a CLAUDE.md under 30 lines where every line has a named real-world failure or constraint behind it and would change Claude's output if removed.

Key takeaways

Five rules from real mistakes beat 50 rules from good intentions. Write from what went wrong, not from what you hope will go right.

CLAUDE.md is the project rules file the model reads at the start of every session
Every line should pass one test: would the model do the right thing without it? If yes, cut it
Sourcing matters. Rules from real mistakes compound; rules from speculation become noise
Start with five rules. Update after sessions where the model repeats a mistake. Audit every few weeks

Go deeper

I want to write my first CLAUDE.md. Help me do it correctly. Ask me: (1) What are the top three mistakes Claude has made in my project that it repeated more than once? (2) What tech stack, versions, or libraries does this project use that Claude might get wrong? (3) Are there specific files, utilities, or patterns I always want Claude to use instead of the default approach? (4) What should Claude never do in this codebase (forbidden patterns, wrong libraries, wrong file locations)? After I answer, write me a CLAUDE.md under 30 lines with only the rules that pass this test: would Claude do the right thing without this rule? If no, it stays. If yes, delete it.

Based on your answers, here is your first CLAUDE.md. Every line came from a mistake you described. ``` # Project Rules ## Stack - This project uses Tailwind v4. Do not suggest v3 class names (e.g. use `text-sm` not `text-base/sm`). - Database layer: all queries go through src/db/query.ts. Never write raw SQL or use the Prisma client directly. - TypeScript strict mode is on. Never use `any`. Use `unknown` and narrow it. ## Patterns - API responses always use the ApiResponse wrapper in src/types/api.ts. Never return plain objects from endpoints. - Errors are logged via src/lib/logger.ts. Never use console.log or console.error in production code. ## File locations - Tests live in src/__tests__/. Never create test files next to source files. ``` Lines I removed from your draft: "Write clean, maintainable code" (Claude knows this), "Handle errors gracefully" (too vague to act on), "Follow TypeScript best practices" (already covered by strict mode). Those three lines cost tokens every session and change nothing. The six lines above will change behavior the first time you open a new session.

After any session where Claude made a mistake you have seen before, say: "Add a rule to my CLAUDE.md that would prevent this mistake. Write the exact line." Then copy that line into your file. That is the compounding habit.