CLAUDE.md is a plain Markdown file Claude Code reads at the start of every session. It's context, not a hard lock, so the clearer each rule is, the more reliably it gets followed.

Where it goes

Heads-up if you also use AGENTS.md: adding a CLAUDE.md (or CLAUDE.local.md) stops Claude reading AGENTS.md unless you import it with @AGENTS.md.

The template

# CLAUDE.md
## Project
- What it is: [one sentence: what you're building and who it's for]
- Stack: [e.g. Next.js 15, TypeScript, Supabase]
- Main folders: [e.g. app/ for pages, lib/ for helpers, supabase/ for migrations]
## Commands
- Install: `npm install`
- Run: `npm run dev`
- Test: `npm test`
- Before every commit: `npm run lint && npm test`
## Rules
- Do one task per request. If I ask for several, list them and do only the first.
- Before writing code, give a 3-line plan: what changes, which files, how I'll test it.
- Make the smallest change that works. Don't rename or reformat code I didn't mention.
- Ask before adding a dependency, deleting files, or changing the database.
- Never say something works unless you ran it. Paste the real error if it fails.
- Secrets live in .env (listed in .gitignore). Never print or commit them.
## Finish every task with
1. What changed (files).
2. How to test it in under a minute.
3. A suggested commit message.

Fastest start: run /init in Claude Code. It writes a first draft with the commands it finds. Then paste in the Rules section, which /init can't guess.

Vague rules get ignored. Concrete ones get followed.

A few more from Anthropic's docs that helped me:

• Keep it under ~200 lines. Longer files use more context and get followed less.
• Headings and bullets, not paragraphs.
• No contradictions. When two rules disagree, Claude may pick either one.
• For "must never happen", use hooks or permissions. CLAUDE.md is guidance, not a lock.
• HTML comments are free. <!-- why this rule exists --> is stripped before Claude reads the file.

A personal one for every project

# ~/.claude/CLAUDE.md
- I'm new to coding. After each change, explain what you did in 2-3 plain sentences.
- Give me the exact commands to run, one per line.
- Use plan mode before any change that touches more than 3 files.
- Never run rm -rf, git reset --hard or a force-push without asking.

Check that it loaded: run /memory in a session. If your file isn't listed, check that the name is exactly CLAUDE.md (capitals matter on Linux) and that you started Claude Code inside the project folder.

What's the one line in your CLAUDE.md you'd never give up?

This is adapted from a page on my free rules site, which also has two full worked examples (a Next.js + Supabase app and a Python script) and links to Anthropic's docs: https://getvibekits.com/rules/claude-md-examples/ . No signup. Disclosure: I run that site and sell a few build kits there; nothing here needs them.