The rules file, and what belongs in it

One file, read every turn

Every serious tool now looks for a plain text file of project instructions and puts it into the context automatically: CLAUDE.md, .cursorrules, AGENTS.md, .github/copilot-instructions.md. Same idea, different filenames, and several tools read more than one.

This is the highest-leverage thing you can write. It is the only text that is present in every single request without you doing anything.

What belongs in it

Six categories, and nothing else.

The stack, stated flatly. “Next.js app router, TypeScript, Postgres via Drizzle, Tailwind.” Without this the model infers from whatever file it happened to read.

Where things live. “All database queries in lib/queries.ts. Route handlers in app/api/. Shared types in types/.” This is what keeps a project navigable after two hundred generated files.

How to run it. The commands. npm run dev, npm run build, npm test, npm run db:migrate. An agent that knows how to build can check its own work, which is worth more than any instruction about code style.

The rules that are yours. The business constraints a model cannot infer. “Prices are stored in paise, as integers, never floats.” “Invoice numbers restart on 1 April.” “Times are stored in UTC and displayed in the salon’s local timezone.”

The prohibitions. “No new dependencies without asking.” “Never edit files in migrations/.” “Do not change the database schema without telling me first.” These are the ones that save whole afternoons.

The scars. When a mistake happens twice, write the rule that prevents it. This is the section that makes the file yours rather than generic, and it is the section people never start.

What does not belong in it

Length. Beyond about a page and a half, the file competes with itself for attention. If everything is important, the model prioritises for you, and it will not prioritise the way you would.

Praise and personality. “You are an expert senior engineer” does approximately nothing for code quality in current models. The tokens are better spent on the fact that your dates are stored in UTC.

Anything already visible in the code. The model can read package.json. It cannot read your intentions.

Stale rules. A rule describing a file you deleted is worse than no rule; it sends the agent looking for something that is not there.

A worked example

# Project rules

## Stack
Next.js app router, TypeScript, Postgres via Drizzle, Tailwind.
Deployed to Cloudflare Workers. Node 20.

## Commands
npm run dev · npm run build · npm test · npm run db:migrate
Always run `npm run build` before saying a change is finished.

## Structure
- Database queries: lib/queries.ts only
- API routes: app/api/<name>/route.ts
- Anything a browser component imports must not touch the database

## Domain rules
- Money is integer paise. Never a float.
- Bookings cannot overlap for the same stylist.
- Opening hours 09:00–19:00 local, stored UTC.

## Do not
- Add dependencies without asking
- Edit anything in drizzle/migrations/
- Refactor files I did not mention

## Learned the hard way
- The seed script wipes the dev database. Never run it to check something.
- Two components are named BookingCard. The one in app/ is dead.

That is under 200 words and it will prevent more failures than any prompt you write this month.

The line that pays for the file

“Always run npm run build before saying a change is finished.”

An agent that verifies its own work catches the type errors, the missing imports and the broken build before you have opened the browser. It costs a few seconds per change and removes the most common form of false completion: a confident summary of a change that does not compile.

Keep it in git

The rules file belongs in the repository, committed like code. It is documentation that stays true, because unlike a README, something reads it every day and you notice when it is wrong.

And when you hand the project to somebody else (a collaborator, a developer you hire, yourself in six months) this file is the fastest briefing that exists.