Part 4 of 7 · Chapter 2 of 5

Rules Files

AGENTS.md, CLAUDE.md, and .cursorrules: how to tell the AI your conventions once instead of every prompt.

Intermediate12 min read

A rules file is a markdown file in your repo that your AI tool reads automatically before every request. It is the highest-payoff thing in this course: written once, it improves every prompt you will ever write in that project.

What they are

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.

Where each tool looks

AGENTS.md        an emerging cross-tool conventionCLAUDE.md        Claude Code.cursorrules     Cursor.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.

What to put in one

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

AGENTS.md

# 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

What makes a good rule

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.

Good rules are

Specific.“Use named exports” beats “write clean code.”
Checkable. Someone can tell whether the rule was followed.
Non-obvious. The model already writes reasonable code — spend the space on what is unusual about your project.
Current. A rule describing a refactor you abandoned is worse than no rule.

The commands section earns its keep

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.

What this unlocks

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.

Keeping it honest

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.

Key takeaways

A rules file is loaded into every request automatically. Write it once, benefit forever.
The test: have you explained it in a prompt more than twice?
Spend the space on what is unusual about your project, not on general good practice.
Include your check command — it turns the AI into something that verifies its own work.
A stale rule is worse than no rule. Update it in the same commit as the convention.