design.md vs claude.md vs cursor rules: what goes where

If you have used Claude Code, Cursor, and Lovable on the same project, you have probably noticed they each want their own little markdown file. Claude reads CLAUDE.md. Cursor reads .cursorrules. And then there is design.md, which all three of them happily ignore unless you point them at it. The question I get most often is the obvious one. **design.md vs claude.md** vs cursor rules, what actually goes where.

This is the field guide I wish I had when I started. Short, opinionated, and based on what has actually worked across a few dozen projects.

design.md vs claude.md at a glance

The shortest possible answer. CLAUDE.md and .cursorrules are about how the agent works. design.md is about how the product looks. They are not competing files. They are different layers, and the trick is to keep them that way.

When you mix them, both files get worse. Your CLAUDE.md becomes a thousand line essay nobody reads, and your design tokens get buried under instructions about commit messages and folder structure. When you separate them, each file does one job well, and the agent has a clear place to look for each kind of decision.

What goes in claude.md

CLAUDE.md is your contract with Claude Code about how to behave inside this specific project. It is the file Claude reads on every session start, before it sees a single component. Treat it like onboarding for a new hire who is very fast and very literal.

The good ones cover four things. The stack you are using, the conventions you care about, the commands the agent should run before declaring work done, and a single line that points at design.md for anything visual. That is the entire job.

• Stack and runtime: framework, package manager, database, deployment target.

• Conventions: how to name files, how to handle errors, how to structure routes.

• Verification: which commands prove the change works (build, lint, test, type check).

• Pointer line: one sentence that says reference design.md for all styling decisions.

Notice what is not in there. No colors. No fonts. No button shapes. The moment you start listing tokens in CLAUDE.md, you have two sources of truth and the agent will pick whichever one it saw last. That is how the purple gradient creeps back in.

What goes in cursor rules

Cursor rules play almost the same role as CLAUDE.md, just for a different agent. The newer Cursor uses .cursor/rules/ with multiple scoped files. The older flow uses a single .cursorrules at the root. Either way, the content is process, not pixels.

Use it for the things Cursor specifically struggles with. Tell it which files to never touch, which packages to prefer, how aggressive to be about refactors, and where the design system lives. The pointer line is the same idea as in CLAUDE.md, just phrased for Cursor.

If you are using both Claude Code and Cursor on the same repo, keep CLAUDE.md and .cursorrules as near mirrors of each other. Same conventions, same verification commands, same pointer to design.md. The agent that reads each file does not care that the other one exists, but you do, because the moment they drift you start getting different output from each tool.

What goes in design.md

design.md is the visual layer. Colors, fonts, radii, shadows, motion, and a short paragraph about feel. Everything an agent needs to make a screen that belongs to your product instead of looking like every other AI app on the internet. If this part is unfamiliar, the long version of what a design.md is covers the format end to end.

The reason this needs its own file is simple. Design decisions change on a different cadence than process decisions. You will tweak a brand color twice in a quarter and never touch your verification commands. Keeping them apart means you can edit one without breaking the other, and it means the file an agent loads for styling is short and focused, not buried inside a wall of repo instructions.

The comparison table that actually matters

Here is the mental model. Three columns, three jobs, no overlap.

• **claude.md**: how Claude Code should behave in this repo. Stack, conventions, commands, pointer to design.md.

• **.cursorrules**: how Cursor should behave in this repo. Same shape as claude.md, scoped to Cursor quirks.

• **design.md**: what the product looks like. Tokens, type, motion, components, feel.

If a question starts with how should the agent work, it goes in claude.md or .cursorrules. If a question starts with what should this look like, it goes in design.md. That single rule resolves about ninety percent of the file is this in the right place arguments.

What about README.md

README.md is for humans. It explains what the project is, how to run it, and where to find things. Agents will read it, and that is fine, but do not lean on it for instructions. Anything you want an agent to follow consistently belongs in CLAUDE.md, .cursorrules, or design.md, depending on which job it does.

A useful test. If a new contributor asked the question, would you point them at the README? If yes, leave it there. If you would instead say it is in our agent rules, that is your sign it belongs in CLAUDE.md or .cursorrules.

Common mistakes when splitting these files

The first mistake is duplication. People paste the same paragraph about brand colors into all three files thinking redundancy will help. It does not. The agent reads them all, finds two that disagree, and picks one at random. One source of truth, with the others pointing at it.

The second mistake is vagueness in design.md. A line that says soft and modern means nothing. A line that says the primary surface is oklch 0.97 0.02 250 with a one pixel hairline at oklch 0.85 0.02 250 means everything. Be specific in tokens, opinionated in prose, and short overall.

The third mistake is letting CLAUDE.md grow unbounded. Every time you fix a bug, you are tempted to add a new rule. Resist. The longer the file, the more the agent skims. Keep it tight, prune monthly, and trust the pointer to design.md to handle everything visual.

Three files, three jobs. Behavior in claude.md and .cursorrules. Identity in design.md. Everything else is noise.

A working setup you can copy

Here is the setup I use on most projects. CLAUDE.md is about forty lines and covers stack, file conventions, verification commands, and a single line that says for all styling questions, read design.md and use only tokens defined there. .cursorrules mirrors it almost exactly, with one or two extras for Cursor specific quirks. design.md is its own world, between sixty and a hundred lines, with tokens, type pairing, motion notes, and a short feel paragraph at the top.

That is the whole stack. No tooling, no plugins, no custom parsers. Just three small files in the right places, each doing one job. The agents do the rest.

Where to go from here

If you do not have any of these files yet, start with design.md. It pays back faster than the others because it changes the look of every screen the agent generates from the next prompt onward. Pick a system from the directory, drop the file in your project root, and let the agent reach for it on the next request.

If you already have a CLAUDE.md or .cursorrules that has grown into a wall of text, this is your weekend cleanup. Pull every visual decision out into design.md, leave a one line pointer behind, and watch your agent rules get half as long and twice as useful.