What Are Agent Rules and How Do You Write Them for AI Coding Agents?

Agent rules are persistent instructions an AI coding agent reads before it generates or edits code — stack versions, folder conventions, design tokens, lint commands, and hard limits on what it must not touch. You write them once in a config file at a known path (for example AGENTS.md, CLAUDE.md, or .cursor/rules/*.mdc), and the agent applies them across every task in that scope instead of you re-explaining your conventions in each new chat. They are worth setting up as soon as you use an agent on a repo more than once; for a single throwaway snippet, a one-off prompt is faster.

How agent rules differ from prompts

A prompt is scoped to one request and disappears when the session ends. Rules live in the repo, so they survive across sessions, tools, and teammates.

The practical difference: with rules, "use our Tailwind token names and never edit globals.css by hand" is stated once and enforced on every generation. With prompts, you repeat it and the agent still drifts.

The common rule file formats and what each is for

Different agents read different files. Design.dev's generator set maps them directly:

• AGENTS.md — one config file intended for every coding agent. The broadest option; start here if your team mixes tools.
• CLAUDE.md — project memory for Claude Code.
• .cursor/rules/*.mdc — scoped rules for the Cursor IDE, where each .mdc file can target a path or pattern.
• copilot-instructions.md — repo-wide rules for GitHub Copilot.
• SKILL.md — reusable skills shared across 27+ coding agents, for capabilities you want to invoke rather than always-on conventions.
• DESIGN.md — design tokens and rules agents can apply, generated from brand assets or a Figma file.
• mcp.json — connects agents to tools and data via MCP, which is configuration rather than rules.

If you only maintain one file, AGENTS.md covers the most agents. If your team is standardized on a single tool, the tool-specific file gives you tighter scoping.

What to put in your rules

Keep each rule checkable — something you could verify by looking at the output.

• Stack and versions. Framework, language version, package manager. "React 19, TypeScript strict, pnpm" prevents an agent from reaching for an older API.
• Folder and naming conventions. Where components, hooks, and tests live, and the casing each uses.
• Design tokens. The token names and values the agent should reference instead of hardcoding colors and spacing. A DESIGN.md or generated tokens.css gives the agent something concrete to apply.
• Formatting and lint commands. The exact commands to run, so the agent can self-check before handing work back.
• Hard limits. Files or directories the agent must never modify, and dependencies it must not add without asking.

A short, specific rule beats a long, vague one. "Never edit globals.css; add tokens to tokens.css" is enforceable. "Write clean code" is not.

Scoping and precedence

Rules stack, and conflicts are the main failure mode. Order them so the most specific wins:

1. Repo-wide rules (AGENTS.md, copilot-instructions.md) — the baseline for every task.
2. Per-directory rules (.cursor/rules/*.mdc scoped to a path) — override the baseline inside that folder.
3. Per-task prompts — override everything for the current request only.

If two files disagree, the agent may follow either, so keep the baseline general and push specifics into scoped files. When you change a convention, update the file that owns it rather than adding a contradicting rule elsewhere.

Verify the agent actually followed the rules

Rules are only useful if the output matches them. After a generation, check the things agents most often get wrong:

• Color contrast. Agents ship low-contrast grays by default. A contrast checker catches them before review.
• Browser feature support. Confirm the CSS and JS the agent used actually ships in your target browsers.
• Images. Compress and convert agent-generated images before they land in the repo.
• Token usage. Grep the diff for hardcoded hex values or pixel spacing that should have been tokens.

If the agent ignored a rule, the usual cause is that the rule was ambiguous or buried. Move it to the top of the file, make it concrete, and re-run the task.

A starting workflow

1. Pick your file: AGENTS.md for mixed tools, or the tool-specific file if you've standardized.
2. Write the five sections above — stack, conventions, tokens, commands, limits.
3. Generate or hand-write a DESIGN.md / tokens.css so token rules have a source of truth.
4. Run one real task and check the output against the rules.
5. Tighten any rule the agent missed, then commit the file so the whole team benefits.

Design.dev offers free generators for each of these config files alongside the verification tools above, so you can produce a first draft and refine it against real output.