Rules are instructions the AI reads on every request. Think of them as the briefing you’d give a new coworker on their first day. Which files matter, which patterns to follow, which conventions to respect, how to structure the work.

Without rules, the AI has too much freedom. It picks its own conventions, its own libraries, its own idea of done. And it ends up not doing what you want.

I’d say you always need a rules file. Even on a tiny project.

Where rules live

Each tool has its own way to load them. Most tools now read an AGENTS.md file at the root of the project. It’s an open format, documented at agents.md. Claude Code uses CLAUDE.md instead, at least for now. Cursor also supports .cursor/rules/ for more granular files.

The filename matters less than the content, and whether your tool actually loads it. I wrote a full guide on what goes in an AGENTS.md file if you want the complete picture.

You write rules in plain English, or in any language you like. The same way you’d explain things to a colleague.

What belongs in there

Useful rules cover things an agent can’t safely infer:

the stack and the runtime versions
the commands for tests, linting, builds, and dev server
important directory or module boundaries
naming and formatting conventions not enforced by tooling
security and privacy requirements
generated files that must not be edited by hand
the checks required before work counts as done

The production build runs Node.js 22 is a good rule. Write good code is not. It doesn’t tell anyone what to do.

On a large codebase, rules are also where you narrow the focus. Tell the model to only work in the frontend, or only on one endpoint, or only on a few files.

Make every rule actionable

Compare:

Always test your work carefully.

After changing lesson metadata, run npm test -- courses.
After changing a page layout, open it at 375px and 1280px widths.

The second version names the trigger and the action. It can be followed, and you can check whether it was.

Rules should also explain surprising boundaries. Keep browser-only tools inside src/tools/<name> stops an agent from creating a convenient shared file that breaks the project’s architecture.

Don’t turn it into a history book

Long files eat context. Remove obsolete setup notes, finished migrations, and duplicated advice. History belongs in the docs or in Git.

Watch for contradictions. Use npm at the top and use pnpm for all commands at the bottom forces the agent to guess. Resolve the decision instead of adding another exception.

Back rules with enforcement

A written rule is guidance. A test, a formatter, a type checker, or a CI check is enforcement.

If breaking a rule would cause a serious bug, automate the check. A test can reject lesson files without a description. A secret scanner catches a committed credential. The rule explains why. The check catches the mistake.

Writing a good rules file is more art than science, and everyone has an opinion. Start small, and review the file every time the project changes. Ask of every line: is it still true, is it specific, and is it worth the context it costs?

Use project rules