CLAUDE.md starter for non-developers

CLAUDE.md is 80 lines of leverage, not an 800-line rulebook

CLAUDE.md is a plain markdown file at the root of your project. Claude Code reads it at the start of every session and treats it as standing instructions. That's the whole mechanic: whatever is in there is context the agent carries into every task, without you retyping it.

That makes it the highest-leverage file in your repo. It's also the easiest one to ruin, because the failure mode isn't an error message. It's silence.

The strongest signal I know: the most-loved public CLAUDE.md files people actually share and copy tend to be tiny. The one I see cited most (as of July 2026) is 65 lines. Not 65 rules. 65 lines, total, including headers and blank lines. Meanwhile the 1,000-line "ultimate CLAUDE.md" repos get stars and then get ignored by the model that has to read them.

One more framing before the file: CLAUDE.md is not documentation for humans and it's not a personality transplant for the model. It's an operating agreement. What the project is, how to run it, what's off-limits, when to ask, and what "done" means. That's 6 sections. Everything else is optional.

The starter file: complete, annotated, under 80 lines

Here's the whole thing. Comments (the <!-- --> blocks) explain each section inline; you delete them after filling in the brackets. Filled in and stripped, this lands around 45-60 lines.

# CLAUDE.md

<!-- THE ANTI-BLOAT STARTER
     Copy to your repo root as CLAUDE.md. Replace every [BRACKET],
     delete every comment block like this one, delete sections that
     don't apply. If your finished file is over 100 lines, you are
     probably doing it wrong. -->

## What this is

[PROJECT NAME] is a [ONE-LINE DESCRIPTION, e.g. "Next.js app that
lets newsletter writers sell paid subscriptions"]. The [MOST
IMPORTANT THING TO KNOW, e.g. "money-critical code lives in
src/billing/ and must never be changed without asking me first"].

<!-- Two lines max. The agent can read your code; it cannot read
     your intent. This section is intent only. -->

## Commands

- Dev server: `[npm run dev]`
- Tests: `[npm test]` (run before saying anything is done)
- Typecheck/lint: `[npm run check]`
- Deploy: `[git push origin main]` (auto-deploys; never deploy another way)

<!-- Only commands the agent will actually run. If a command is
     discoverable in package.json and obvious, you can skip it.
     Keep the parenthetical rules: those are the real content. -->

## Code style

- [LANGUAGE RULE, e.g. "TypeScript strict mode, no `any`"]
- [PATTERN RULE, e.g. "Server components by default, 'use client' only when needed"]
- [DEPENDENCY RULE, e.g. "Ask before adding any new dependency"]
- Match the style of surrounding code over any general convention.

<!-- Every rule here must be CHECKABLE: you (or a linter) can look
     at a diff and say pass/fail. "Write clean code" is not a rule,
     it's a wish. Delete wishes. -->

## Never touch

- `[.env, .env.local]` (secrets; read if needed, never edit or print values)
- `[src/db/migrations/]` (applied migrations are immutable; new ones OK)
- `[legacy/]` (scheduled for deletion; do not fix or extend)

<!-- The highest-value section in the file. Every entry here is
     something that costs real money or real hours if the agent
     edits it. Earn each line: only list things that actually
     exist in your repo. -->

## When unsure

- Ambiguous requirements: ask me, don't guess.
- Two reasonable implementations: pick one, say why in one sentence, proceed.
- Anything involving [PAYMENTS/AUTH/USER DATA]: always ask first.
- Destructive operations (deleting files, dropping tables, force-push): always ask.

<!-- This section kills the two worst failure modes: the agent
     asking permission for everything, and the agent confidently
     rewriting your billing code at 2am. -->

## Definition of done

A task is done when ALL of these pass:

1. `[npm run check]` passes with zero errors
2. `[npm test]` passes
3. The feature works when you actually exercise it (not "should work")
4. No new console errors or warnings in the changed flow

If any of these fail, the task is not done. Say so plainly instead
of describing the work as complete.

<!-- Without this section, "done" means "I wrote code that looks
     plausible." With it, "done" means the same thing it means
     to you. This is the section that pays rent every session. -->

1. 1

   Drop it in

   Save the file as CLAUDE.md in your project root (same folder as package.json or your main script). Claude Code picks it up automatically on the next session. No config, no restart flag.

2. 2

   Fill every bracket, delete every comment

   Replace each [BRACKET] with your real values. Then delete all the <!-- --> comment blocks. The comments are for you, not the model; leaving them in is exactly the kind of dead weight this file exists to avoid.

3. 3

   Delete what doesn't apply

   No test suite yet? Cut the test line from Commands and adjust Definition of done. No legacy folder? Cut it from Never touch. An empty section beats an invented rule. Fake rules teach the model your file can't be trusted literally.

4. 4

   Test it in one session

   Start a fresh session and give it a small real task. Watch whether it runs your check command before claiming done, and whether it asks before the things you flagged. If yes, you're set. If no, the fix is usually making the line more specific, not longer.

Interview me, then write a CLAUDE.md for this project.

Rules for the file you produce:
- Maximum 80 lines total.
- Exactly these sections: What this is / Commands / Code style / Never touch / When unsure / Definition of done.
- Every code style rule must be checkable (pass/fail from looking at a diff). No aspirational rules like "write clean code".
- Do not include anything you can already see in the repo (framework, folder structure, dependency list). Intent and constraints only.
- Do not invent rules I didn't confirm. If a section has nothing real in it, leave it with one line: "Nothing yet."

Interview process:
1. First, read the repo yourself: package.json / requirements / scripts, top-level folders. Don't ask me anything you can answer from the code.
2. Then ask me a maximum of 7 questions, one at a time, covering: what the project does and for whom; which files or folders would hurt most if edited wrongly; how I deploy; what the agent has gotten wrong before in this repo; when I want to be asked vs. when it should just proceed; what I personally check before calling a task done.
3. Then output the complete CLAUDE.md in one code block and nothing else.

Project context to start from: [ONE SENTENCE ABOUT YOUR PROJECT]

Line by line: why each section earns its place

Six sections, and each one exists because leaving it out costs you something specific. Here's the case for every line, so you know what you're deleting when you delete it.

1. 1

   What this is (2 lines)

   The agent can infer your stack from the code in seconds. What it can't infer is intent and stakes: who this is for, what part is money-critical, what phase the project is in. Two lines of intent change hundreds of small decisions downstream (how defensive to be, what to optimize for). Two lines. If you're writing a third, you're describing the code, and the code already does that.

2. 2

   Commands (4-6 lines)

   Without this, the agent guesses commands from package.json and sometimes guesses wrong, or runs npm test when your suite needs a flag. Worse, it doesn't know your deploy rule. The parentheticals are the real payload: "run before saying anything is done" and "never deploy another way" are behavioral rules smuggled into a reference list. Cheapest 5 lines in the file.

3. 3

   Code style (3-5 lines, all checkable)

   One filter decides what belongs here: could a reviewer look at a diff and say pass or fail? "No any" passes the filter. "Prefer readable code" doesn't, so it goes. And if your linter already enforces a rule, the linter is the better home for it; put npm run check in Commands instead of restating 30 lint rules in prose. The closing line, "match surrounding code," is the one style meta-rule worth stating because it resolves every case you didn't cover.

4. 4

   Never touch (the highest-ROI section)

   This is the section that prevents the expensive day. Env files with secrets, applied migrations, generated folders, the payment webhook. Each entry should name a real path in your repo and, in one parenthetical, why. The why matters: "secrets" and "immutable once applied" let the model generalize correctly to files you forgot to list. Three to five entries is normal. Fifteen means you're listing things that were never in danger.

5. 5

   When unsure (the ask-vs-proceed contract)

   Agents fail in two opposite directions: stopping to ask about everything (you become a human OK-button) or barreling through ambiguity (you get 400 confident lines solving the wrong problem). This section draws the line explicitly: ambiguous requirements means ask, ambiguous implementation means pick one and say why, and payments/auth/user-data/destructive ops always mean ask. Four lines, and it's the difference between an agent you supervise and an agent you babysit.

6. 6

   Definition of done (the section that pays rent)

   Every vibe coder learns this one the hard way: the agent says "done, the feature is implemented" and the build doesn't even compile. Not lying exactly, just a looser definition of done than yours. This section replaces its definition with yours: checks pass, tests pass, the flow was actually exercised, no new console errors. The last line ("say so plainly instead of describing the work as complete") is doing real work: it gives the model explicit permission to report failure, which is what cuts down the fake-victory writeups.

What NOT to put in (this list is why the file stays short)

The starter is easy. The discipline is what you keep out. Run your current CLAUDE.md against this list; every hit is a line to delete. When I did this to my own main project file it went from 340 lines to 72, and rule-following got visibly better within a week, because the 6 rules I cared about stopped competing with 300 lines of filler.

• [ ]Personality instructions. "You are a world-class senior engineer with 20 years of experience." Costs a line, changes nothing about the diff. The model doesn't code better when flattered.
• [ ]Framework tutorials. 40 lines explaining how Next.js routing or React hooks work. The model's training covers your framework in more depth than your summary; you're paying context for a worse version of what it already knows.
• [ ]Anything the repo already shows. Folder structure diagrams, dependency lists, "we use TypeScript and Tailwind." The agent reads the repo every session. Restating it is pure duplication, and it goes stale the first time you refactor.
• [ ]Aspirational fluff. "Write clean, elegant, maintainable, well-documented code." Not checkable, so not followable. Every wish-rule dilutes the real rules around it.
• [ ]Rules your linter already enforces. If ESLint or ruff catches it, one Commands line (npm run check must pass) covers all of them. Restating 30 lint rules in prose is 30 lines of redundancy.
• [ ]Generic best-practice packs from the internet. Rules written for someone else's stack and someone else's failure modes. If you didn't earn the rule from your own agent's mistake, you probably don't need it (see the growth rule below).
• [ ]Changelogs and session notes. "On June 12 we refactored auth." That's git history. CLAUDE.md is standing instructions, not a diary.
• [ ]Full API or schema documentation. If the agent needs your DB schema, it can read schema.prisma. If a doc is genuinely needed sometimes, add one line pointing to it ("DB schema: prisma/schema.prisma") instead of pasting it.
• [ ]Motivational threats and bribes. "This is EXTREMELY IMPORTANT, my job depends on it, I will tip $200." Popular in 2023 prompt lore, dead weight in a standing instructions file.
• [ ]Rules for tools you don't use. Docker rules with no Dockerfile, testing rules with no tests. The model notices when your file describes a project that doesn't exist, and your credibility (yes, files have credibility) drops.

Audit the CLAUDE.md below against these principles and rewrite it.

Delete-on-sight criteria:
1. Personality/role-play instructions ("you are a senior engineer")
2. Explanations of frameworks or languages the model already knows
3. Anything discoverable by reading the repo (structure, stack, dependency lists)
4. Non-checkable aspirational rules ("write clean code")
5. Rules a linter/formatter in this repo already enforces
6. Changelog/session-history entries
7. Pasted documentation that could be a one-line pointer to a file
8. Rules referencing tools or files that don't exist in the repo

Process:
1. Output a table: every line or rule I currently have, verdict (KEEP / CUT / REWRITE), and a max-10-word reason.
2. Anything marked REWRITE must become checkable: pass/fail from looking at a diff.
3. Then output the rewritten file, max 80 lines, organized as: What this is / Commands / Code style / Never touch / When unsure / Definition of done.
4. End with one line: original line count vs. new line count.

Do not add any new rules I didn't have. This is a cut, not an expansion.

My current CLAUDE.md:
[PASTE YOUR CLAUDE.MD]

Growing it: one rule, and it's "twice"

The starter is a floor, not a ceiling. It will grow. The only question is whether it grows from evidence or from anxiety, and there's a one-word test that decides it: twice.

You only add a line after the agent gets the same thing wrong twice. Not "might get wrong." Not "a blog post said agents often get this wrong." Got it wrong, in your repo, two separate times.

1. 1

   First mistake: fix it, note it, add nothing

   Correct the agent in the session and move on. One occurrence might be a fluke of that session's context. If you want, keep a scratch note (I keep a ## Candidates section at the bottom of a personal notes file, never in CLAUDE.md itself).

2. 2

   Second mistake: now it's a pattern, add ONE line

   Same mistake again means it's systematic, and it's earned its slot. Write the line the way you'd correct a contractor: specific, checkable, one sentence. "Use the formatDate helper in src/lib/dates.ts, never new Date().toLocaleDateString()." Slot it into whichever of the 6 sections it belongs to. A quick way in the moment: press # in Claude Code and type the rule; it gets added to memory for you, then move it to the right section next time you're in the file.

3. 3

   Write it against the mistake, not against the topic

   Bad: "Be careful with dates and timezones." Good: "All timestamps are stored UTC; convert to user timezone only in components." The first is a topic. The second is the actual correction, and it's checkable.

4. 4

   Prune on the same standard

   Once a month (or whenever you're in the file), read every line and ask: is this still true, and has it fired recently? Rules for code you deleted, workflows you changed, or mistakes the models simply stopped making: cut them. A stale rule is worse than a missing one, because the model can tell when your file doesn't match your repo.

One escape hatch worth knowing as your project grows: CLAUDE.md files nest. A CLAUDE.md inside a subfolder applies when the agent works in that folder. So when your root file starts collecting rules that only matter for one area (src/billing/, scripts/), move them into a small CLAUDE.md in that folder instead of growing the root. Root file stays under 100 lines, area rules load only when relevant.

Variants: Next.js SaaS, Python scripts, monorepo

Same skeleton, different brackets. Each variant below is a diff from the base starter: what to swap or add, section by section. Full copy-paste versions of all three are in the download.

## Commands  (swap in)
- Dev server: `npm run dev` (assume it's already running)
- Tests: `npm test`
- Typecheck + lint: `npm run check`
- DB migration: `npx prisma migrate dev --name [name]` (ask before running)
- Deploy: push to main, Vercel auto-deploys. Never deploy manually.

## Code style  (swap in)
- TypeScript strict, no `any`, no `@ts-ignore` without a comment saying why
- Server components by default; 'use client' only for interactivity
- All data access through src/lib/db.ts helpers, never raw Prisma in components
- Tailwind only, no CSS files, no inline style props
- Ask before adding any dependency

## Never touch  (add)
- `src/billing/webhooks.ts` (Stripe webhook handler; a bug here loses money)
- `prisma/migrations/` (immutable once applied; new migrations OK)
- Anything under `app/api/auth/`

## Definition of done  (add)
5. `npm run build` succeeds (catches server/client mistakes dev mode hides)

## Commands  (swap in)
- Run: `python main.py` (uses .venv; `source .venv/bin/activate`)
- Install deps: `pip install -r requirements.txt`, then update requirements.txt
- Lint/format: `ruff check . && ruff format .`
- No test suite yet. New functions with logic get a test in tests/, run `pytest`.

## Code style  (swap in)
- Python 3.12+, type hints on all function signatures
- One script = one job; shared helpers in utils.py, nothing else shared
- Secrets from os.environ only, never hardcoded
- logging, not bare print()
- Ask before adding dependencies beyond the standard library

## Never touch  (swap in)
- `.env` (secrets; read names if needed, never edit or print values)
- `output/`, `data/` (generated artifacts; scripts write here, you don't)
- Any file with `_prod` in the name unless I explicitly say so

## Definition of done  (swap in)
1. `ruff check .` passes
2. Script runs end to end on real or sample input without a traceback
3. Show me actual output, not a description of what it should output

## What this is  (swap in)
Monorepo with 3 workspaces: apps/web (customer app), apps/api (backend),
packages/ui (shared components). Each workspace has its own CLAUDE.md;
this file is only what applies everywhere.

## Commands  (swap in)
- Everything from the repo root: `pnpm dev --filter [ws]`, `pnpm test --filter [ws]`
- Build all: `pnpm build`
- Never cd into a workspace and run npm/pnpm there; always filter from root.

## Code style  (add)
- Cross-workspace imports only via packages/* public exports, no deep imports
- Changes to packages/* require the FULL test suite, not just the package's own

## Never touch  (swap in)
- Root configs (turbo.json, pnpm-workspace.yaml, tsconfig.base.json) without asking
- Workspaces other than the one the task is about

## When unsure  (add)
- Not sure which workspace a change belongs in: ask, don't duplicate into both.

## Per-workspace files  (new closing section)
apps/*/CLAUDE.md hold workspace-specific rules, ~40 lines each max.
A rule that applies to 2+ workspaces moves up here.

That's the whole system: one file under 80 lines, six sections that each earn their place, a delete list, and one growth rule. Download the starter, fill the brackets tonight, and the next session you run will already behave differently. When a rule earns its way in via the twice-rule, you'll know the file is working.