CLAUDE.md

Every new Claude Code session starts with a blank memory. A CLAUDE.md file fixes that. It tells Claude Code what your project is and how you like to work, every single time.

What is CLAUDE.md?

Imagine a new helper joins your shop each morning. Instead of explaining everything again, you leave a note on the counter: what we sell, where things go, and the house rules.

CLAUDE.md is that note. It is a Markdown file in your project folder. Claude Code reads it automatically at the start of every session.

• It is plain text written in Markdown, a simple way to format text with # headings and - bullets
• It lives in the top folder of your project
• You and Claude Code can both edit it
• It gets saved to Git with the rest of your project

my-shop/
├── CLAUDE.md        ← Claude Code reads this every session
├── README.md        ← for humans
├── docs/
│   └── PRD.md       ← the product plan
├── .env.local       ← secrets (never committed)
└── .gitignore

Create it with /init

You don't need to write it from scratch. Inside Claude Code, type:

/init

Claude Code looks through your project and writes a first CLAUDE.md for you. It describes the folders, the tools used, and the commands to run the app.

In an empty folder, /init has little to describe. That's fine. You can ask Claude Code to write it from your plan instead:

Read docs/PRD.md and create a CLAUDE.md for this project.
Include: what the app is, the tech stack, how to run it, and our working rules.
Keep it under 60 lines and use simple headings.

What to put in it

Keep it short and practical. Think "what would a new helper need to know on day one?"

• What the project is — one or two sentences
• Tech stack — the main tools, so it doesn't pick different ones
• Commands — how to install, run, and check the app
• Folder layout — where pages, components, and docs live
• Rules — things to always or never do, like "never commit .env.local"

Example: CLAUDE.md for an online shop

For example, imagine you are building an online shop that sells handmade goods. Its CLAUDE.md might look like this. Yours will describe your own app.

# Online shop

An online shop for handmade home goods.
Customers browse products, save a wishlist, add to cart, and check out.
Admins add and edit products and view orders.
Full plan: docs/PRD.md

## Tech stack
- Next.js + Tailwind CSS
- Supabase (database, auth, storage, Row Level Security)
- Stripe in test mode for checkout
- An LLM API for the AI shopping assistant (server-side only)
- GitHub for code, Vercel for hosting

## Commands
- Install: npm install
- Run locally: npm run dev  (then open http://localhost:3000)
- Check for errors: npm run build

## Database tables
products, profiles, cart_items, wishlist_items, orders, order_items

## Environment variables (values live in .env.local)
NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY,
STRIPE_SECRET_KEY, NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
NEXT_PUBLIC_SITE_URL, ANTHROPIC_API_KEY

## Rules
- Work in small steps. Explain the plan before big changes.
- Keep secrets in .env.local. Never commit it. Never print keys.
- Never use the Supabase service_role key in browser code.
- Only NEXT_PUBLIC_ variables may be used in the browser.
- Every table must have Row Level Security turned on.
- Use simple, beginner-friendly code and short comments.
- After each working step, suggest a commit message.

Let's break this down:

• The top section gives the big picture in three lines
• The stack list stops Claude Code from switching tools halfway
• The rules turn your safety habits into instructions it follows every time

Keep it up to date

Your project will grow. When you make a decision you want Claude Code to remember, add it to the file. You can ask:

Add a rule to CLAUDE.md: prices are shown with a $ sign and two decimals.

Common mistakes

Writing a novel

A 500-line file buries the important rules. Keep it short and move long details into docs/PRD.md.

Vague rules

<!-- Wrong -->
- Write good code.

<!-- Right -->
- Use Tailwind classes for styling. Do not add other CSS libraries.

Forgetting to commit it

Commit CLAUDE.md like any other file. Then the memory travels with your project.

What's next?

Claude Code now remembers your project. Next, let's learn how to work with it safely: planning first, reviewing changes, and saving progress with Git.