Rules Files
AGENTS.md, CLAUDE.md, and .cursorrules: how to tell the AI your conventions once instead of every prompt.
A rules file is a markdown file in your repo that your AI tool reads automatically before every request. It gives every request the same project context.
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.
AGENTS.md an emerging cross-tool conventionCLAUDE.md Claude Code.cursorrules Cursor.github/copilot-instructions.md GitHub CopilotSeveral 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.
# 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 componentWhat's better said once, per request
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.
Belongs in the file
Stable, and applies to nearly every request: naming conventions, the check command, which state library you use, where secrets live.
Better said per request
True today but volatile — “we’re mid-migration off X” — a one-off exception, or anything specific to the single file you are editing right now.
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.
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.
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?
- Volatile and one-off information belongs in the prompt, not the file — it outlives its truth and misleads every request after.
- 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.
Quick check
Answer these to unlock the next chapter — 3 of 4 to pass. You can retake it anytime.
Answer every question to check.
Make a free account to read on
Every chapter is free — an account is how your progress, XP, and streak follow you from your laptop to your phone, and how you show up on the leaderboard. No payment, no trial.