Production CLAUDE.md Starter

A working CLAUDE.md you can drop into a repository today, plus the reasoning behind each section so you can cut what does not apply to you.

CLAUDE.md is the file Claude Code reads automatically at the start of a session. It is persistent project context: the commands, boundaries and standards that would otherwise be repeated in every prompt. It is not documentation for humans, and it is not a place to describe your codebase — Claude can read the codebase.

The one rule that matters most

Keep it short. Every line competes for attention with every other line. A 400-line CLAUDE.md is followed less reliably than a 120-line one, because the important rules are diluted by the obvious ones. If a rule is mechanical and unconditional — "format after every edit" — it belongs in a hook, where it runs whether or not it was read.

Aim for roughly 150 lines. When you add something, look for something to remove.

What belongs in it

The starter file

Copy this to CLAUDE.md in your repository root. Replace everything in angle brackets. Delete sections that do not apply — a section you cannot fill in honestly is worse than no section.

# CLAUDE.md

> Starter version. Replace every line in angle brackets, delete what does not apply,
> and keep this file under roughly 150 lines. A file nobody trims stops being read.

## Project

<One sentence: what this is and who uses it.>

- **Stack:** <framework, language, runtime version>
- **Package manager:** <npm | pnpm | yarn | uv | poetry> — use this one, not another
- **Hosting:** <where production runs>
- **Repository layout:** <one line per top-level directory that is not obvious>

## Commands

Always use these. Do not invent equivalents.

<install> # e.g. pnpm install --frozen-lockfile <dev> # e.g. pnpm dev <build> # e.g. pnpm build <test> # e.g. pnpm test <lint> # e.g. pnpm lint <typecheck> # e.g. pnpm typecheck

## Architecture rules

- <Where new code of each kind belongs, e.g. "UI components in `src/components`, one per file.">
- <The boundary that must not be crossed, e.g. "Nothing in `src/ui` imports from `src/server`.">
- <How state/data flows, in one sentence.>
- Prefer editing an existing module over adding a new one. Ask before introducing a dependency.
- Match the surrounding file's conventions over any general style preference.

## Coding standards

- <Formatter and linter; they are the authority, not this file.>
- Naming: <the convention actually used in this repo>.
- Comments explain *why*, never *what*. No commented-out code in a commit.
- No `any`, no unchecked casts, no swallowing errors with an empty catch.
- Public functions get types on their inputs and outputs.

## Testing

- Test framework: <name>. Tests live in <path> and are named <pattern>.
- A change to behaviour needs a test that fails without it.
- Do not delete or `skip` a failing test to make the suite green. Fix it or say it is broken.
- Run `<test>` before reporting work complete. Report real results, including failures.

## Security

- **Never** read, print, log, or commit secrets. Credentials live in the environment or a
  secret manager, never in source, never in a template, never in client-side JavaScript.
- `.env` and `.env.*` are git-ignored and stay that way. Use `.env.example` for names only.
- Validate and escape every value that came from a user before it reaches HTML, SQL,
  a shell, or a file path.
- Authorisation is checked on the server for every request, not in the UI.
- Do not add a dependency to solve a problem the standard library already solves.
- Do not disable a security header, CSP rule, or certificate check to make something work.

## Accessibility

- Semantic HTML first. A `div` with a click handler is not a button.
- Every interactive control is reachable and operable by keyboard, with a visible focus style.
- Every informative image has meaningful `alt`; decorative images have `alt=""`.
- Text contrast at least 4.5:1, non-text UI at least 3:1.
- Form inputs have an associated `<label>`. Errors are announced, not only coloured.
- Headings descend without skipping levels. One `<h1>` per page.

## SEO

- One unique `<title>` and one unique meta description per route.
- One self-referencing canonical per page.
- Structured data only where it describes what is actually on the page.
- Never add review, rating, or aggregate markup without real reviews behind it.
- Internal links use descriptive anchor text, not "click here".
- Images ship at the size they render, with width and height set.

## Performance

- Set `width` and `height` on images and video to prevent layout shift.
- Lazy-load below the fold; never lazy-load the largest element above it.
- No render-blocking third-party script without a reason written down.
- Measure before optimising. Report the number, not the impression.

## Deployment

- <Branch that deploys, and where it deploys to.>
- <The exact command or pipeline that ships.>
- Never push directly to <production branch>. Open a pull request.
- Migrations run <how>; they are forward-compatible with the running version.
- A deploy is not finished until <the check that proves it worked> passes.

## Do not

- Do not commit, push, or open a pull request unless asked.
- Do not run destructive commands (`rm -rf`, `DROP`, `--force`, history rewrites) without asking.
- Do not edit generated files, lockfiles, or anything under <build output dir> by hand.
- Do not reformat files you were not asked to change; it hides the real diff.
- Do not claim something is tested, deployed, or working without having verified it.

## Before you say it is done

1. `<lint>` and `<typecheck>` pass.
2. `<test>` passes, and any new behaviour has a test.
3. `<build>` succeeds.
4. The change was exercised for real — a page loaded, an endpoint called, a command run.
5. Anything skipped or still broken is stated plainly.

How to tell whether it is working

A CLAUDE.md that is never tested is a wish list. Three checks, in increasing strength:

1. Ask. Start a session and ask "what does CLAUDE.md tell you about testing here?"

If the answer is vague, the section is vague.

1. Bait. Ask for something the file forbids — adding a dependency, pushing to the

production branch. It should push back and cite the reason.

1. Observe. Over a week, note which rules get broken. A rule broken repeatedly is

either badly written or does not belong in a prompt file at all. Move it to a hook.

Strong rules versus weak ones

The difference is that the strong version is checkable. Someone reading the diff can tell whether it was followed.

Scope: which file wins

Claude Code reads CLAUDE.md from several places and combines them. In practice:

• **~/.claude/CLAUDE.md** — your personal preferences, on every project. Keep it tiny.
• **<repo>/CLAUDE.md** — the project file. Committed. This is the one that matters.
• **<repo>/<subdir>/CLAUDE.md** — rules for one package in a monorepo, loaded when you

work in that directory.

• **CLAUDE.local.md** — your own overrides, git-ignored.

Put a rule at the narrowest scope where it is true. A rule about the Shopify theme does not belong in the file the API package also reads.

What this starter leaves out

This is deliberately a starter. It does not include per-framework files, migration rules, incident-response conventions, or the review checklists that turn a CLAUDE.md into a working standard for a team. The Claude Code Website Launch System contains the fuller versions along with the audits that check whether they are being followed.

Related reading

• Production CLAUDE.md for web development — the full guide
• CLAUDE.md examples for production web development — worked examples by project type
• Claude Code hooks — where mechanical rules belong instead
• Anthropic: memory and CLAUDE.md — the primary source

Licence

Free to use in any project, including client work. Do not resell or republish it as your own.