AGENTS.md and DESIGN.md: how to use both in one repo

AGENTS.md is the open README for coding agents; DESIGN.md is the design system they follow. What belongs in each, how to link them, and how CLAUDE.md and Cursor rules fit in.

Devshell Mono, a monospace documentation design system for developer tools

Key takeaways

  • AGENTS.md holds how to work in the repo: setup, commands, tests and code conventions.
  • DESIGN.md holds how the product looks: tokens, type, components and visual rules.
  • Link them with one line in AGENTS.md, and keep design values out of AGENTS.md entirely.

AGENTS.md has become the shared instruction file for AI coding agents: one markdown file that tells any agent how to work in your repository. It does not tell the agent how your product should look. That is the job of DESIGN.md. Used together, they cover both halves of a good brief: how to build, and what to build it to look like.

What AGENTS.md is

AGENTS.md is an open, markdown-based format for guiding coding agents, described on agents.md as a README for agents. It has no required fields. It typically holds what a human README would not: build steps, test commands, code style and project conventions. Tools listed as supporting it include OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Windsurf, Zed and many others. In a monorepo, each package can have its own AGENTS.md, and the file closest to the code being edited wins.

What DESIGN.md is

A DESIGN.md is a design system written for agents: exact colors for light and dark mode, type roles, spacing, radius, motion, component recipes and a Do / Don't list. It answers one question, how should this look, and nothing else. The full explanation is in what a DESIGN.md file is.

AGENTS.md vs DESIGN.md: what goes where

QuestionFile
How do I install, run and test this project?AGENTS.md
Which framework, folder structure and code style?AGENTS.md
What are the brand colors in light and dark mode?DESIGN.md
Which fonts, sizes, weights and spacing?DESIGN.md
What does a button, card or table look like?DESIGN.md
Where are the design rules?AGENTS.md points to DESIGN.md

The rule that decides every case: if a line would still be true after a redesign, it belongs in AGENTS.md. If a redesign would change it, it belongs in DESIGN.md.

How to connect the two files

Keep design values out of AGENTS.md completely and add one line that sends the agent to DESIGN.md for anything visual:

AGENTS.md
# AGENTS.md

## Setup
- Install: pnpm install
- Dev server: pnpm dev
- Tests: pnpm test

## Conventions
- TypeScript strict, no default exports
- Components live in src/components, one per file

## UI
- Before any UI work, read DESIGN.md and use only its tokens
  and component recipes. Never hard-code colors, fonts,
  radius, shadows or durations.

Where CLAUDE.md and Cursor rules fit

Claude Code reads CLAUDE.md automatically. If you already keep AGENTS.md, reference it from CLAUDE.md instead of duplicating it, and add the DESIGN.md line there too:

CLAUDE.md
# CLAUDE.md

@AGENTS.md

Before any UI work, read @DESIGN.md and use only its tokens
and component recipes.

Cursor can read AGENTS.md as well, and you can also make DESIGN.md an always-on rule by saving it as .cursor/rules/design.mdc with alwaysApply: true. Step by step in Cursor rules for UI. For the longer comparison of all three files, read DESIGN.md vs CLAUDE.md vs Cursor rules.

A setup that works with every agent

  1. Save a DESIGN.md in the repo root. Start from one of the DESIGN.md examples if you do not have one.
  2. Write an AGENTS.md with setup, commands and conventions, plus the one UI line above.
  3. For Claude Code, add a short CLAUDE.md that references both.
  4. Ask for one screen and check it against DESIGN.md. Fix what is vague, not the screen.

With that in place, prompts can stay short. "Add a billing page" is enough, because the agent already knows how to build in your repo and what the result should look like. More on short, effective briefs in design prompts for AI UI.

Frequently asked questions

An open, markdown-based instruction file for AI coding agents, often called a README for agents. It holds setup steps, commands, tests and code conventions, and is read by many agents including OpenAI Codex, Cursor and GitHub Copilot's coding agent.

AGENTS.md tells agents how to work in the repository: install, run, test and code conventions. DESIGN.md tells them how the product looks: colors, type, spacing, components and visual rules. AGENTS.md should point to DESIGN.md for anything visual.

No. Keep every visual value in DESIGN.md and add one line to AGENTS.md that tells the agent to follow DESIGN.md for all UI. Two copies of the same tokens drift apart.

Claude Code reads CLAUDE.md automatically. To reuse an existing AGENTS.md, reference it from CLAUDE.md, and add a line that points to DESIGN.md for UI work.
Tammo Elsner, founder of freedesignmd

Written by Tammo Elsner

Founder of freedesignmd, a free DESIGN.md library for AI coding agents. About the project · LinkedIn

Keep reading. More on Claude, Cursor and Lovable.

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

Claude, Cursor and Lovable

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

A short, opinionated field guide to design.md vs claude.md vs cursor rules. What each file is for, what to put in it, and the one rule that resolves most of the arguments.

Nov 16, 2026 · 7 min read

How to give Claude Code a real design system, with a single markdown file

Claude, Cursor and Lovable

How to give Claude Code a real design system, with a single markdown file

Claude Code has good taste in code and weak taste in UI by default. Here is the two file setup that fixes it on day one.

Nov 16, 2026 · 5 min read

Citrine IDE design system, a warm code-editor theme for Cursor projects

Claude, Cursor and Lovable

Cursor rules for UI: use a DESIGN.md as an always-on design rule

How to turn a DESIGN.md into a Cursor rule: where the file goes, which frontmatter to set and how to check that Cursor follows your colors, type and spacing.

Nov 16, 2026 · 4 min read

Start with a free DESIGN.md. Or install a component.

Free design systems, React components and landing page templates for Claude Code, Cursor, Lovable and v0. No signup.