The CLAUDE.md
Starter Template

CLAUDE.md is a plain text notes file Claude reads at the start of every Claude Code session — basically Claude's memory for your project. Get it right and Claude stops making the same mistakes, stops guessing your setup, and stops needing the same corrections over and over.

Most guides make this way more complicated than it needs to be. So this one has two levels, and you start wherever you are:

· New to Claude Code? Start with the beginner version below. You can have a working CLAUDE.md in about 30 seconds — Claude will even write it for you.

· Ready to level up? Then keep scrolling to the exact system Anthropic's own engineering team runs — where the file improves itself from every mistake Claude makes. That part's more advanced, and it's worth it.

Forget everything fancy for a second. To get started, you don't even have to write this file yourself. There are two beginner ways in.

/init

# 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

You don't even have to open the file to add to it. Any time Claude does something you have to correct, just tell it in plain English: "add this to CLAUDE.md." Claude writes the rule itself. (Newer versions of Claude Code also quietly save notes on their own as they learn your project — that's called auto memory.)

Where to put it: the file lives in your project's main folder as CLAUDE.md (commit it so your team shares it). Want rules that apply to every project — like your personal style preferences? Put a second one at ~/.claude/CLAUDE.md.

Everything above is enough to start. But once it's part of your routine, here's the system Anthropic's own engineering team runs — where your CLAUDE.md stops being something you maintain and starts writing itself from every mistake Claude makes. This is the part worth the extra effort.

Boris Cherny (lead on Claude Code) calls it Compounding Engineering, and his team edits their CLAUDE.md multiple times a week with it. Every time Claude makes a mistake, instead of just fixing it and moving on, you end your prompt with one specific sentence:

"Update CLAUDE.md so you don't repeat this."

That's it. Claude writes itself a rule about the exact mistake it just made, in the exact phrasing the model responds best to. Next session, Claude reads the rule and doesn't make the mistake. Two weeks in, your CLAUDE.md is a curated list of every weird thing your project has — written by the model, for the model. Here's how to run it.

Most people write CLAUDE.md once, list a few rules they think matter, and never touch it again. The trick flips that: let Claude write the file from its own mistakes. Every time Claude does something wrong in your project, end your fix prompt with: "Update CLAUDE.md so you don't repeat this."

Boris calls Claude "eerily good at writing rules for itself" from its own failures. The phrasing Claude picks tends to be more precise than what you'd write — because it's written in the language Claude itself responds to.

What this fixes:

· The same Claude mistake popping up in session after session.

· Onboarding new team members — they clone the repo and the whole accumulated practice ships with the code.

· Sloppy output that you're tired of correcting by hand.

· The slow drift away from your team's conventions because nobody wrote them down.

The Claude Code team's own CLAUDE.md (which Boris walked through publicly) has four sections. That's the canonical structure — copy it.

· # Development Workflow — the build commands, test commands, lint commands. The exact order to run them. Anything Claude can't guess about your toolchain. (Bun vs npm. Pytest vs unittest. The one obscure flag your lint setup needs.)

· # Code style — the conventions Claude should follow. "Use ES modules, not CommonJS. Tabs not spaces. Named exports, not default." Only the rules that aren't standard for your language.

· # Architecture — structural rules. "All API routes go through src/api/middleware/auth.ts. New database queries go in src/db/queries/, no inline raw SQL." The decisions that compound when Claude follows them and break things when it doesn't.

· # Gotchas — the section that captures all the "Update CLAUDE.md so you don't repeat this" entries. Every entry started as a real mistake Claude made on a real change. "User and UserRecord are distinct types. UserRecord is the DB row, User is the runtime object." "formatCurrency assumes USD. For international use formatCurrencyByLocale."

What goes where: if you're not sure which section, put it in Gotchas. That section grows over time and is where the real value compounds.

Drop this into the root of your repo as CLAUDE.md. Then start replacing the placeholders with your actual project details. The Gotchas section starts empty — that's by design. It fills itself in over the next two weeks.

CLAUDE.md is team-shared (checked into git). But you'll have rules that are just for you — PR feedback you keep getting, your own quirks to correct, personal preferences. That goes in CLAUDE.local.md.

Same path, same auto-load behavior, but gitignored. It stays on your machine. Add it to your .gitignore on day one.

The workflow that makes this compound:

· After every PR you open, copy any reviewer comments into CLAUDE.local.md the moment you read them.

· Group as # From PR feedback and # My own quirks to correct — mixing them makes the file harder to prune later.

· Loaded every session. Claude includes those rules without you asking. Two weeks in, the same nitpick comments stop coming.

A template:

# From PR feedback
- New SQS consumers need a DLQ 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

Most CLAUDE.md files balloon to hundreds of lines and stop working — the rules that actually matter get buried under noise. Boris's filter again: would removing this line cause a mistake? If no, cut it.

Specifically, skip:

· Standard language conventions Claude already knows (it knows Python uses snake_case, JavaScript uses camelCase, etc).

· File-by-file codebase tours. Claude can read the code.

· Long tutorials. Use a /skills/ file instead, or link to an external doc.

· API documentation. That changes too often and bloats the file.

· Platitudes ("write clean code," "be thorough"). Meaningless to the model.

· Anything that changes frequently. CLAUDE.md should be stable; the volatile stuff lives in code comments or rules/.

The CLAUDE.md trick works because you apply it consistently for the first two weeks. After that, the gains compound on their own. Here's the ritual:

· Days 1–3. Set up CLAUDE.md from the starter template above. Get your build/test commands right. Replace the placeholders. Run a normal Claude Code session and notice the first time Claude does something wrong.

· Days 4–14. Every. Single. Mistake. Ends with: "Update CLAUDE.md so you don't repeat this." No exceptions. Don't filter "is this big enough?" — trust the model to write the rule, you can prune later.

· End of week 1. Review the Gotchas section. Are the entries phrased clearly? Are any duplicates? If so, ask Claude to dedupe them: "reread the Gotchas section in CLAUDE.md and merge any duplicate or overlapping rules."

· End of week 2. Review again. By now you'll have 15–30 gotcha entries. Trim anything that's now muscle memory (the thing that runs on autopilot can leave the file).

· Ongoing. The habit becomes automatic. Use @claude in PR comments to commit a rule directly from a code review: "@claude add to CLAUDE.md to never use enums, always prefer literal unions."

Two weeks. That's the entire investment. After that, every project you start has compounding context as a baseline.