Working with agents · 17 August 2026 · 5 min

Where design rules belong: AGENTS.md, .cursorrules, or MCP

Rules files load into every session, in full, and are versioned with one repo. Design decisions are the opposite shape. Here is the division of labour that keeps both small.

Every repository has one of these now. An AGENTS.md at the root, or a CLAUDE.md, or a .cursor/rules directory — a file that tells the agent how this project works before anyone types a prompt. It starts as build commands and test conventions. Then someone pastes the brand colours in, and a note about the typeface, and the persona.

That version half-works, and it is rarely obvious why. The answer is not that rules files are bad. They are very good at one specific job, and most of what you want to say about design is not that job.

What a rules file actually is

AGENTS.md is an open format read by more than twenty agents — Codex, Cursor, Copilot, Jules and the rest — placed at the repository root, with nested files in monorepo subdirectories that the agent resolves closest-first. Claude Code reads CLAUDE.md rather than AGENTS.md, though a one-line @AGENTS.md import makes both tools read the same file. Cursor reads .mdc files in .cursor/rules; the single .cursorrules file is the legacy form of the same idea.

The formats differ. The mechanic underneath them does not, and it is the mechanic that matters here:

They load at the start of every session, in full, whether the task needs them or not. Anthropic's own guidance is to keep a CLAUDE.md under 200 lines, because longer files consume more context and reduce adherence — the file competes with the work for the same window, and past a point the agent starts averaging it out. Cursor's rule types exist for exactly this reason: "Apply to Specific Files" narrows a rule to a glob so it only arrives when relevant.

They are versioned with one repository. That is a feature. A convention about where API handlers live should travel with the code that has API handlers.

They are text. Markdown in, markdown out.

Three properties, all correct for the thing they were designed for. Design decisions break all three.

Why design context is the wrong shape for the file

It is relevant to almost every file, so scoping does not save you. Path-scoped rules work beautifully for "these are the rules for src/api/**". Design applies to anything that renders — which is most of the repository — so the narrowest honest glob is roughly "all UI". You are back to always-on, and now your palette, type scale, motion durations and voice rules are sitting in the context window during a database migration, being paid for and ignored.

It changes on a different clock from the code. Conventions change when the architecture does, which is rarely. A palette changes when the brand does, and then it has to change in every repository and every tool-specific file that holds a copy. The second repository is where this starts: now there are two copies, and they begin disagreeing in ways nobody decided. That drift is the argument in how to teach a coding agent your design taste — a rules file solves the "written down" half and leaves the "in one place" half untouched.

Half of it is not text. A logo has an SVG and a clear-space rule. A reference is an image you saved because it got something right. A typeface has a source, a licence and a fallback stack. Markdown holds the names of these things and not the things.

The split that works

Put in the rules file only what is short, always true, and cheap to carry. Put everything else behind a call the agent makes when it needs it.

In practice that is about six lines in AGENTS.md:

## Design

Before writing UI, call `get_canvas` (moodspec MCP). It is the source of
truth for typography, colour, logo, voice and persona — do not infer them
from existing components.

Always true, no fetch required:
- One accent. It means "act here". Never body text, never a heading.
- No gradient heroes, no violet, no emoji in UI copy.
- Motion is 320ms ease-out. Nothing bounces.

Two things are happening there and they are worth separating.

The negative constraints are in the file because they are one line each and they are true during the database migration too. They also do the most work per token of anything you can write: "no gradient heroes, no violet, no emoji" closes off three of the model's highest-probability defaults in a single line, which is most of what produces the app that looks like every other vibe-coded app.

The pointer is in the file because the file's best use is telling the agent where the truth is, not being the truth. This is the same instinct as a good README, and it fails in the same way when you get it backwards: a README that duplicates the API docs is a README that is wrong by Thursday.

What sits behind the call

Everything with a value, a reason and a shelf life. The hex codes with their job descriptions — #E8511E, primary action, never text — because as building a colour palette you can defend argues, the rule is the part that generalises to the pricing table the agent has never seen. The type pairing with the sizes each face owns. The persona your copy is addressed to. The logo files. The references.

Increasingly this includes whatever your design tool sends, which arrives the same way and lasts about as long — the agents differ in which servers they can reach at all, and not one of them keeps what it received past the session.

Fetched at the moment of use, this material is current by construction, and it exists once rather than once per repository per tool. MCP for designers covers the mechanics; the docs are one block of config, and there are setup guides for Claude Code, Cursor and the rest.

The distinction is simpler than the tooling makes it look. A rules file is a broadcast. A tool call is a question. Broadcast what is always true and short. Answer the rest on demand.

When the file is genuinely enough

One repository, one person, one tool, and design rules that fit in ten lines you have not touched in a month — the file is fine. Copying a paragraph into AGENTS.md is a smaller act than connecting anything, and smaller is usually right.

The split starts paying at the second of anything. A second repository, and now there are two copies. A second tool, and now there are two formats. A second person, and now there is a version in their head as well.

The test

Grep your repositories for your accent colour:

grep -ril "#E8511E" ~/code --include="*.md" --include="*.mdc"

Count the files. Then open two of them and check whether they still say the same thing about when to use it.

If there is one file, stop reading — you do not have this problem yet. If there are four and two of them disagree, the rules file is not the wrong tool. It is just being asked to be a database, and it has never once been a good one.