CLAUDE.md is the new spec document

Two years ago the spec was a document that a human read once and forgot. Now it is a file that a machine reads on every single task, which changes what belongs in it entirely.

We keep a CLAUDE.md at the root of every repository. It is the highest-leverage file in the project, and it took a few painful builds to work out what actually belongs there.

Why a rules file changes the economics

When an assistant writes a substantial share of the code, consistency stops being a matter of team discipline and becomes a matter of context. The model does not remember the argument you had last Tuesday about where validation lives. It only knows what is in front of it.

Without a rules file, every prompt is a fresh negotiation. You get four different error-handling patterns, three date formats and a second pricing function. With one, the same conventions apply on Monday morning and Friday night, on your machine and on a contractor’s.

The saving is not in typing. It is in the rework you never do. That is the same argument we made for the one-page spec — this is the machine-readable half of it.

What goes in

1. The map

Where things live and what each area owns. Four or five lines, not a directory dump.

Data access goes in one place. Business rules in another. Components stay presentational. Say it plainly and the assistant stops inventing a new folder for every feature.

2. The non-negotiables

The rules that must never be broken, phrased as absolutes because ambiguity gets interpreted away:

• Every database table has a row-level policy. No exceptions.
• No secret keys in client code, ever.
• All money handling goes through the pricing module.
• Every list endpoint is paginated with a hard maximum.
• No new dependency without a note explaining why the standard library will not do.

These are the rules that survive a rushed Friday deploy, which is precisely when you need them.

3. The conventions

Naming, error shapes, date and currency handling, how state is managed, what a component looks like. Boring and enormously valuable, because these are the decisions people relitigate weekly.

Include one worked example of a typical file. A single concrete reference does more than a page of description.

4. The definition of done

What must be true before something ships. Ours is short: types pass, the eight money tests pass, no console errors, the page renders without JavaScript where it should, and the migration is committed.

An assistant that knows the finish line stops handing you 80% work with an optimistic summary.

5. Phase gates

This is the part most teams miss, and it is the part that made the biggest difference for us.

Break the work into phases and state what must be signed off before the next one starts. Schema before endpoints. Endpoints before interface. Interface before polish.

Without gates, an assistant will happily build twelve screens on top of a data model that is wrong, and you will not find out until integration. With gates, the mistake surfaces on day one when it costs an hour instead of a fortnight. Read it alongside MVP, prototype or POC — gates are how you keep a POC from quietly becoming a production system.

6. The forbidden list

Every project accumulates specific traps. Write them down.

Do not use that deprecated helper. Do not touch the legacy orders table directly. Do not add another date library. Do not put logic in the route file.

This list grows every time something goes wrong, and that is the point — it is your postmortem log in an enforceable form.

What stays out

Anything that will be stale in a month. Sprint plans, ticket numbers, personnel. The file must be trustworthy or people stop reading it.

Explanations of the framework. The model knows the framework better than the file will. Spend the space on what is specific to you.

Aspirations. If the codebase does not do it yet, phrase it as a migration target, not a rule. Otherwise the assistant follows the rule, the code does not, and you get inconsistency in both directions.

Novel prose. It is a rules file. Bullets, imperatives, done.

How we actually use it

Written before the first line of code, during scoping. It is part of the deliverable, not an afterthought.

Updated when a review finds a repeated mistake. Second time we correct the same thing, it becomes a rule. That feedback loop is the whole system.

Read by humans too. New engineers onboard from it faster than from a README, because it answers the questions people actually have on day one.

Handed to the client at the end. When you own the code, you own the operating manual for it. If your current studio cannot hand you one, that tells you something — a point we make in the hiring checklist.

A starting skeleton

Six headings is enough to begin:

1. What this project is, in three lines
2. Architecture map
3. Non-negotiables
4. Conventions, with one example file
5. Definition of done
6. Forbidden patterns

Fill it in during your next feature rather than in one sitting. A file written from real corrections beats one written from imagination.

The honest limitation

A rules file does not make an assistant careful. It makes it consistent. You still need review, tests and someone who understands the domain reading the output.

What it removes is the tax of re-explaining your project every single day — and on a build of any size, that tax is most of the waste.

If you inherited a codebase with no rules file and no idea what the conventions were, the triage post is the right place to start. Writing the file comes immediately after.