What to put in CLAUDE.md: a beginner's template for Claude Code

Every Claude Code session starts fresh, with no memory of what you told it yesterday. CLAUDE.md is how you fix that. This guide gives you a CLAUDE.md example for beginners: what the file is, where it goes, what belongs in it, and a short template you can paste in today.

What CLAUDE.md is

CLAUDE.md is a plain text (markdown) file of instructions. Claude Code reads it at the start of every session, so you don't have to repeat yourself. Claude's docs describe it as "the place you write down what you'd otherwise re-explain".

One honest limit, straight from the docs: Claude treats CLAUDE.md as context, not enforced configuration. It reads it and tries to follow it, but there is no guarantee. Clear, specific instructions get followed far more reliably than vague ones.

Where it goes

For a project, put it in the main folder of your project as CLAUDE.md (or inside a .claude folder as .claude/CLAUDE.md). Other places exist too:

The quickest start: run /init inside Claude Code. It looks at your project and writes a starting CLAUDE.md for you. Then trim and add to it. To check the file loaded, run /context and look under Memory files.

What belongs in it

The docs suggest adding something when Claude makes the same mistake twice, or when you catch yourself typing the same correction again. Good things to include:

• What the app is, in one or two sentences.
• How to run it (for example, npm run dev).
• Your safety rules: plan first, ask before deleting, keep secrets out of code.
• How you want explanations: plain English, no unexplained jargon.

What to leave out: long procedures, huge style guides, and anything Claude can figure out by reading your code.

Keep it short

Claude's docs recommend staying under 200 lines per file. Longer files use up more of the AI's attention and get followed less closely. Be concrete: "Run npm test before saying a change works" beats "make sure things work".

A safe starter template

# About this project
A simple booking app for my yoga studio. Built with Next.js and Supabase.
I am not a developer. Explain everything in plain English.

# How to run it
- Start locally: npm run dev
- The site runs at http://localhost:3000

# Rules
- Before changing code, tell me the plan in plain English and wait for "go".
- Change one thing at a time. After each change, tell me how to check it.
- Never delete files, drop tables, or run git reset --hard, git clean,
  git push --force or rm -rf unless I say "yes" after you explain what
  will be lost.
- Before a big change, remind me to make a git save point.
- Never put API keys or passwords in code. Use .env.local and tell me
  where to add them on the host.
- Never turn off Supabase Row Level Security to make an error go away.
- If a fix fails twice, stop and explain instead of trying a third time.
- Never say something works unless you actually ran it.

Swap the first two sections for your own project. The rules section works almost anywhere.

When you outgrow one file

For bigger projects, Claude Code supports a .claude/rules/ folder with one markdown file per topic. A rule can be limited to certain files with a paths setting at the top, so it only loads when Claude works on matching files. Most beginners won't need this for a while.

Using Cursor too?

Cursor has its own rules system. See Cursor rules for beginners for the equivalent setup. Claude Code can also read an AGENTS.md file in place of CLAUDE.md, which some people use to share one instruction file between tools.

Get it ready-made

Our free starter pack includes a ready-to-use CLAUDE.md with these safety rules, plus the same rules as a Cursor rule file and a one-page launch checklist. The Ship-Safe Starter Kit has a ready-made CLAUDE.md, 9 Cursor rules, a git undo cheat sheet and a pre-deploy security checklist.

Vibe Shipped is independent and not affiliated with Anthropic, PBC. Written with AI assistance and reviewed by a human.