Home › Rules › CLAUDE.md examples

CLAUDE.md examples and best practices (with a copy-paste template)

Checked against Anthropic's Claude Code memory docs on Oct 19, 2026. Sources below.

• Formats
• Claude Code

Short answer: a good CLAUDE.md is short (Anthropic says aim for under 200 lines), written as concrete rules you could check, and grouped under headings: what the project is, the commands, the rules, and how to report back. Copy the template, fill in the brackets, and delete anything that doesn't apply.

What CLAUDE.md is (in one paragraph)

A plain Markdown file that Claude Code reads at the start of every session. It's how you stop repeating "use npm, not yarn" or "ask before touching the database" in every chat. Claude treats it as context, not as a hard lock, so the clearer each rule is, the more reliably it gets followed.

Where it goes

Already have an AGENTS.md? Read AGENTS.md vs CLAUDE.md first. Adding a CLAUDE.md (or CLAUDE.local.md) stops Claude reading AGENTS.md unless you import it.

The template (copy this)

# 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 scans your project and writes a first CLAUDE.md with the commands it finds (or suggests improvements if you already have one). Then paste in the Rules section above, which /init can't guess.

CLAUDE.md examples

Example 1: a Next.js + Supabase web app

# CLAUDE.md: Recipe Box (Next.js + Supabase)

## Project
- A web app where home cooks save and tag their own recipes. Logged-in users only.
- Stack: Next.js 15 (App Router), TypeScript, Tailwind, Supabase (auth + Postgres).
- Pages live in `app/`, database helpers in `lib/db.ts`, migrations in `supabase/migrations/`.

## Commands
- Run: `npm run dev` (http://localhost:3000)
- Tests: `npm test`
- New migration: `supabase migration new <name>`, then `supabase db push`

## Rules
- Every new table gets row-level security with policies in the same migration. Users only see their own rows.
- Server-only keys (service role, Stripe secret) never get a `NEXT_PUBLIC_` prefix.
- Use server components by default; add "use client" only for interactivity.
- Ask before dropping or renaming a column.
- One task per request, 3-line plan first, smallest change that works.

Example 2: a Python script

# CLAUDE.md: Invoice renamer (Python script)

## Project
- A script that reads PDF invoices in `inbox/`, pulls the vendor and date, and renames them `YYYY-MM-DD_vendor.pdf`.
- Python 3.12, one file: `rename.py`. Dependencies in `requirements.txt`.

## Commands
- Setup: `python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`
- Dry run (changes nothing): `python rename.py --dry-run`
- Tests: `pytest`

## Rules
- Default to dry run. Never move or delete a file without the `--apply` flag.
- Log every rename to `renames.log` so I can undo it.
- If a PDF can't be read, skip it and say why. Don't guess the vendor.
- Ask before adding a new library.

Example 3: your personal file for every project

# ~/.claude/CLAUDE.md (personal, applies to every project)

- 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.

Need one for a specific project type? Every page in the rules library has a ready file (games, bots, web apps, scripts and more), or use the CLAUDE.md generator.

CLAUDE.md best practices (from Anthropic's docs)

• Be concreteWrite rules you could check.The docs' own examples: "Use 2-space indentation" instead of "Format code properly"; "Run npm test before committing" instead of "Test your changes".
• Keep it shortAim for under 200 lines per file.Longer files use more context and get followed less. Imports (@path) help you organize, but imported files still load at the start, so they don't save space.
• Use structureHeadings and bullets, not paragraphs.Grouped sections are easier for Claude to follow than dense text.
• No contradictionsWhen two rules disagree, Claude may pick either one.Review your files now and then. Newer versions (v2.1.283+) can do it for you with /doctor prompt-audit, which suggests edits without changing anything.
• Scope itMove part-of-the-project rules to .claude/rules/.A rule with paths: ["supabase/**/*.sql"] only loads when Claude touches those files.
• Hard limitsFor "must never happen", use hooks or permissions.CLAUDE.md is guidance. The docs point to hooks and permission settings for things you need to block for sure.
• Notes for humansHTML comments are free.Block comments like <!-- why this rule exists --> are stripped before Claude reads the file, so they cost no context.

Bad rule vs good rule

Check that it loaded

Run /memory in a session to see which CLAUDE.md files Claude picked up. If yours isn't listed, check the file name is exactly CLAUDE.md (capitals matter on Linux) and that you started Claude Code inside the project folder.

Related

• AGENTS.md vs CLAUDE.md (which one you need, and the one-line import)
• Cursor rules examples (the same ideas as .mdc files)
• Rules file formats explained (which file each tool reads)
• Rules for cleaning up an existing codebase
• CLAUDE.md generator (free, runs in your browser)

Sources

• Claude Code docs: How Claude remembers your project (CLAUDE.md, AGENTS.md, .claude/rules)
• Claude Code docs: Hooks guide

Checked Oct 19, 2026. These tools change often; if something here no longer matches, tell us at [email protected].