← Back to all free guides
A free guide by Mariah Brunner ↗ INSTAGRAM ↗ TIKTOK

The CLAUDE.md
Starter Template

Two ways to set up the one file that makes Claude Code understand your project. The 30-second beginner version, then the habit the Claude Code team uses so the file gets better from every mistake.

CLAUDE.md is a plain text notes file that Claude Code reads at the start of every session. It’s Claude’s memory for your project. Get it right and Claude stops guessing your setup and stops making the same mistakes. (Claude Code docs: memory)

New to Claude Code? Start with the beginner version. Already using it? Skip to the advanced section, where the file improves itself.

Beginner: Start Here

01

Let Claude write it

Open Claude Code inside your project and type this.

Type This In Claude Code
/init

Claude reads your project and writes a starter CLAUDE.md with your build commands, test instructions and the conventions it finds. If you already have one, it suggests improvements instead of overwriting it.

02

Or write the 6-line starter

You only need two sections to start. Save this as CLAUDE.md in your project’s main folder and fill in the blanks.

6-Line Starter
# Workflow - Run tests with: [your test command] - Typecheck when you're done making a set of changes - Prefer running one test at a time, not the whole suite # Code style - [One or two rules you actually care about] - Example: use 2-space indentation, not tabs

03

Add to it in plain English

When Claude does something you have to correct, say "add this to CLAUDE.md" and it writes the rule. Claude Code also keeps its own notes as it learns your project. That’s called auto memory, and it’s on by default. Type /memory to see both.

The First Rule

Before you add a line, ask whether leaving it out would make Claude mess up. If not, skip it. Anthropic’s docs say to keep each CLAUDE.md under 200 lines, because longer files use more context and get followed less reliably.

Your project’s CLAUDE.md lives in the main folder, so commit it and your team shares it. For rules that apply to every project, like your personal style, put a second one at ~/.claude/CLAUDE.md.

Advanced: The Claude Code Team’s Way

Boris Cherny created Claude Code. His team keeps one shared CLAUDE.md in git to document Claude’s mistakes so it improves over time, and it’s only about 2.5k tokens. When he reviews a coworker’s pull request, he often tags Claude to add the lesson to CLAUDE.md. (InfoQ on Boris’s workflow)

His tip is to end every correction with one sentence.

The Sentence

"Update your CLAUDE.md so you don’t make that mistake again."

He says Claude is "eerily good at writing rules for itself." It writes a rule about the exact mistake, and next session it reads the rule and avoids it. Two weeks in, your file is a list of every odd thing about your project, written by the model for the model. People call this compounding engineering, because every fix makes the next session better.

The 4 Sections I Use

04

Development Workflow

Build, test and lint commands, in the order to run them. Anything Claude can’t guess, like Bun vs npm or the one odd flag your linter needs.

05

Code style

Only the conventions that aren’t standard for your language. "Named exports, not default" earns a line. "Python uses snake_case" doesn’t.

06

Architecture

Structural rules that break things when ignored. "All API routes go through src/api/middleware/auth.ts. No inline raw SQL."

07

Gotchas

Where every "don’t make that mistake again" rule lands. "User and UserRecord are different types. UserRecord is the database row." Not sure where a rule goes? Put it here.

Save this at the root of your repo as CLAUDE.md, commit it and replace the placeholders. Gotchas starts empty on purpose.

CLAUDE.md Starter Template
# Development Workflow Always use [your package manager], not [the wrong one]. 1. Make changes. 2. Typecheck: `[your typecheck command]` 3. Run tests: `[your test command]` (use `[single-test flag]` for a single suite) 4. Lint before committing: `[your lint command]` 5. Before opening a PR: `[your pre-PR command]` # Code style - Use ES modules (import/export), not CommonJS (require) - [Your other style rules, only the ones that aren't standard for your language] # Architecture - All API routes go through [your auth middleware path] - New database queries go in [your queries directory]. No inline raw SQL. - [Your other structural rules] # Gotchas - [Empty for now. Claude fills this in as you work.] --- ## How this file gets better Every time Claude makes a mistake in this project, end the fix prompt with: Update your CLAUDE.md so you don't make that mistake again. Claude adds a rule to Gotchas. Keep the file under 200 lines. If removing a line wouldn't cause a mistake, cut it.
Your Personal Layer

CLAUDE.md is shared with your team. For rules that are just for you, like PR feedback you keep getting, create CLAUDE.local.md in the same folder. It loads right after CLAUDE.md. Add it to your .gitignore on day one so it stays on your machine.

After every PR, paste reviewer comments in the moment you read them. Keep PR feedback and your own quirks under separate headings so it’s easier to prune later.

CLAUDE.local.md Template
# From PR feedback - New SQS consumers need a dead-letter queue and alarms in the same PR - Use Optional<T> over null returns - Tests for new endpoints must include the auth-failure case # My own quirks to correct - Stop using console.log; use the project logger instead - Always update the OpenAPI spec when adding endpoints
What To Leave Out

Skip The All Caps

Older advice said IMPORTANT or YOU MUST made Claude listen. Anthropic’s prompting guide now says newer models respond so closely that aggressive language can make them overreact, so write plain, specific rules instead.

The Two-Week Ritual
  1. Days 1 to 3. Set up CLAUDE.md from the template, get the commands right and work normally.
  2. Days 4 to 14. End every correction with the sentence. Don’t judge whether a mistake is big enough. You can prune later.
  3. End of each week. Run the cleanup prompt below to merge duplicates and cut dead weight.
  4. Ongoing. Run /install-github-app once, then comment "@claude add to CLAUDE.md: never use enums, prefer literal unions" on a PR to save a rule straight from code review. (GitHub Actions docs)
CLAUDE.md Cleanup
Review our CLAUDE.md (and CLAUDE.local.md if it exists) as an editor whose only goal is fewer mistakes from you in this project. 1. Read both files and skim the codebase enough to check the commands and paths they mention. 2. For every line, ask: would removing this make you more likely to make a mistake here? List the lines that fail that test. 3. Find duplicates or overlapping rules in Gotchas and propose one merged rule for each group. 4. Flag anything that is out of date: commands that don't exist, paths that moved, rules that contradict each other or the code. 5. Flag rules written in ALL CAPS or "YOU MUST" style and rewrite them as plain, specific instructions. 6. Show me the proposed new file as a diff, and keep it under 200 lines. Don't change anything until I approve the diff. If the file is already tight, say so.

Claude Code can also check your instruction files for you. Run /doctor prompt-audit to find rules that are outdated, contradict each other or point at files that don’t exist.