CLAUDE.md: what it is and what to put in it

# CLAUDE.md

Instructions for Claude Code working on Project Name. Keep this file short
and specific: it is read on every session, and anything vague gets ignored or,
worse, over-applied.

## What this project is

One paragraph: what the software does, who uses it, and the one quality that
matters most (correctness, latency, bundle size, whatever it is). An agent that
knows what you optimise for makes better trade-offs unprompted.

## Commands

```sh
npm install       # setup
npm run dev       # local dev server on :3000
npm test          # unit + integration; must pass before any commit
npm run lint      # eslint + prettier check
npm run build     # production build to dist/
```

Run `npm test` before committing. Do not commit if it fails.

## Layout

```
src/          application code
  lib/        shared, no framework imports allowed here
  routes/     one file per route
tests/        mirrors src/
scripts/      build and maintenance tooling
```

## Conventions

- TypeScript, strict mode. No `any` without a comment saying why.
- Prefer editing an existing file over creating a new one.
- Comments explain *why*, never *what*: the code says what.
- No new dependencies without asking. This project has a deliberate budget.

## Testing

Every bug fix gets a regression test that fails before the fix. Tests live
beside the code they cover, named `<file>.test.ts`.

## Things that will bite you

- `src/lib/legacy-parser.ts` is load-bearing for two large customers. It looks
  dead. It is not.
- The dev server proxies `/api` to staging. Data there is real. Do not seed it.
- Migrations are irreversible in production. Ask before writing one.

## Pull requests

Title in the imperative (`Add retry to the export queue`). Body explains why,
not what. Link the issue. Keep the diff reviewable: split if it is not.

CLAUDE.md is a plain Markdown file in the root of a repository that Claude Code reads automatically before it does anything. Whatever is in it becomes context for every request in that project, so it is where a codebase writes down the things a newcomer would otherwise have to be told.

It is not a configuration format. There are no required keys and nothing to validate: it is prose and code blocks, read the way a new colleague would read a handover note. That is also its main failure mode: nothing stops you writing two thousand words nobody needs.

Where it goes, and which ones apply

Files nest rather than replace: working in a subdirectory gives you the root file and the local one. A monorepo can put shared rules at the top and package-specific rules beside each package.

Write down what the code cannot say

The useful content is whatever an agent cannot work out by reading the source. Which command runs the tests. Which directory is generated and must not be hand-edited. Which file looks abandoned and is quietly load-bearing for two large customers.

Restating what the code already says is the most common way these files get long without getting better. If a competent reader would learn it in thirty seconds from the source, leave it out.

Commands first

npm install       # setup
npm run dev       # local dev server on :3000
npm test          # unit + integration; must pass before any commit
npm run build     # production build to dist/

This is the section that gets used on every task, so it goes near the top. Add the one-line comment saying what each command is for - npm run check could be a linter, a type check, or a deploy gate, and guessing wrong wastes a cycle.

Be specific, not emphatic

Vague instructions are the ones that get applied unevenly. Compare:

- Write good tests.

with:

- Every bug fix gets a regression test that fails before the fix.

The first is a sentiment. The second is checkable. The same applies to emphasis: a file where several rules are marked critical reads as a file with no priorities at all. State the rule once, plainly, and let it stand.

The section people skip

The “things that will bite you” heading is the one most worth filling in, and the one most often left empty, because the traps are obvious to whoever already knows them:

- `src/lib/legacy-parser.ts` is load-bearing for two large customers. It
  looks dead. It is not.
- The dev server proxies /api to staging. Data there is real.
- Migrations are irreversible in production. Ask before writing one.

Every line there is something that would otherwise be discovered the expensive way.

Keep it current

An instruction file that has drifted from the project is worse than none, because it is trusted. When a command changes, change it here in the same commit: the file is small enough that this is a habit rather than a chore.