Rules Files

Different tools look for different filenames, but they all do the same job — inject a file into the context of every request without you asking.

AGENTS.md        an emerging cross-tool conventionCLAUDE.md        Claude Code.cursor/rules/   Cursor (older projects: .cursorrules).github/copilot-instructions.md    GitHub Copilot

Several tools now read AGENTS.md, and the others can be one-line pointer files that import it — which keeps one source of truth instead of four files drifting apart.

The test for whether something belongs is simple: have you explained it in a prompt more than twice? If so, it belongs here.

# Project A Next.js 16 app using the App Router. TypeScript strict mode. ## Commands- npm run dev     start the dev server- npm run check   lint + typecheck + build — must pass before any PR ## Conventions- Named exports only, no default exports- Tailwind utility classes, never inline styles- Components in PascalCase, utilities in camelCase- 2-space indentation ## Things that will bite you- Colours come from design tokens, never hardcoded hex values- Every route href must end in a trailing slash- Lesson data is seeded — never use Math.random in a component

Not everything true about your project belongs in the file that loads on every single request. Some things are better said once, in the prompt where they matter, and left out otherwise.

Put a migration note in the rules file and it outlives the migration by months, actively misleading every request that comes after. Put a one-off exception in there and it silently applies everywhere, not just the one place you meant it.

There is a second reason to be selective, independent of staleness. A rules file that has grown past a page stops behaving like a set of rules the model reliably follows and starts behaving like reference material it skims. You will see it honour rule four and quietly ignore rule forty — not carelessness, just what happens to a long, undifferentiated list of instructions. The fix is not a longer file. It is a shorter one, with the volatile and the one-off routed to the prompt instead.

Rules compete for the same context budget as your code, so a bloated rules file makes things worse. Aim for specific, checkable, and non-obvious.

If you include nothing else, include how to run the checks. It converts the AI from something that writes plausible code into something that verifies its own work.

Add the feature, then run npm run check and fix anythingit reports. Do not stop until it passes.

That prompt only works if the model knows the command exists. Put it in the rules file and every future request can lean on it.

A rules file rots like any other documentation, and a stale one actively misleads — the model will follow a convention you abandoned six months ago with total confidence.

Treat it as code. When you change a convention, change the file in the same commit. When you notice yourself correcting the AI on the same thing repeatedly, that is a missing rule telling you about itself.