AGENTS.md vs Cursor rules vs DESIGN.md
**DESIGN.md** holds the brand specification. **AGENTS.md** tells every coding agent where to look and how to behave. **`.cursor/rules`** adds Cursor-specific always-on habits. You want all three for serious product work — but AGENTS.md is the portable layer that Claude Code, Cursor, and other tools share.
Many repos already have AGENTS.md for test commands and folder maps. Adding brand rules is a ten-line change with outsized impact: "Read DESIGN.md before UI work. Use semantic tokens only. Reuse components/ui."
Generate the brand half of the stack with AI Brand Kits, then paste the pointer rules below. For Cursor-only snippets see best Cursor rules for brand consistency.
Brand lines worth putting in AGENTS.md
Keep brand instructions boring and absolute. Agents follow clear negatives better than vague taste notes.
- **Read DESIGN.md first** for any styling, layout, or new page
- **Semantic tokens only** — no raw hex, rgb, or default Tailwind palette colors
- **Reuse existing components** before inventing buttons or inputs
- **Do not change fonts** unless the task explicitly rebrands
- **Match spacing/radius** from DESIGN.md; no random `rounded-3xl`
- **Human product copy** — short CTAs, no filler marketing fluff
- **Icons** — one set (e.g. Lucide) + official logo mark only
Copy-paste AGENTS.md brand block
Add this near the top of AGENTS.md after your project overview. Adjust paths if DESIGN.md lives in a package.
- **Brand source of truth** — `DESIGN.md` at repo root. Read it before UI tasks.
- **Tokens** — use CSS variables / Tailwind semantic classes from the kit; never hardcode colors.
- **Typography** — only the headline and body fonts listed in DESIGN.md.
- **Components** — search `components/ui` (or your design system path) before creating new primitives.
- **Scope** — do not restyle unrelated pages while implementing a feature.
- **Exports** — if `tokens.json` exists, keep values in sync when changing brand colors.
- **Optional** — link to how to make Cursor follow my brand for teammates.
Team patterns that scale
Solo founders keep a 15-line AGENTS.md. Agencies maintain a template brand block and swap client DESIGN.md per repo. Product orgs add ownership: design updates tokens; eng owns agent rule text.
- **Monorepo** — root AGENTS.md points to `packages/ui/DESIGN.md`
- **Client repo** — DESIGN.md + AGENTS.md brand block in every starter zip
- **Open source** — public DESIGN.md helps contributors match screenshots
- **Multi-agent** — same AGENTS.md for Cursor and Claude Code brand kit
FAQ
- Is AGENTS.md enough without Cursor rules?
- It helps a lot, especially for Claude Code and shared conventions. Cursor still benefits from alwaysApply .mdc rules so brand checks run even when the user forgets to mention design.
- Should brand rules be long?
- No. Point to DESIGN.md for details. AGENTS.md should be short commands; DESIGN.md holds the token tables and examples.
- Where can I get a starter brand kit for agents?
- Use export brand kit for AI agents — DESIGN.md, tokens, and rule folders in one zip.
- Can AGENTS.md include screenshots?
- Prefer tokens and text rules. Screenshots help humans but burn agent context; link to a live preview or Storybook instead.
- How do I update brand rules after a rebrand?
- Change DESIGN.md (and tokens.json) first, then tweak AGENTS.md only if paths or component folders changed.
Related
Free tools
Interactive utilities you can use without an account. Each tool links to related guides and export workflows across the site.