DESIGN.md, CLAUDE.md and AGENTS.md are plain-text, repo-resident files that give AI coding agents persistent context. CLAUDE.md and AGENTS.md cover code and conventions; DESIGN.md covers the visual identity. Complementary layers an agent reads on every interaction.
CLAUDE.md / AGENTS.md -> code & project context
(stack, conventions, commands)
SKILL.md -> on-demand capabilities
DESIGN.md -> the design system
(tokens + rationale)
Each handles a different concern, and they do not overlap.
Separation keeps each focused and lets you adopt them independently. A team might start with CLAUDE.md for code context, add DESIGN.md when agent-generated UI drifts off-brand, and layer in skills later. All plain text, so they version and review like code.
The cleanest setup wires them: a CLAUDE.md that tells the agent to read DESIGN.md for UI work links code context to design context. The agent gets one coherent picture - how to write the code and how to make it look right.
Start with the file that solves your biggest pain:
Most teams end up with more than one, added as the need appears.
One universal format? AGENTS.md is closest to a cross-tool standard for code context; DESIGN.md is the emerging standard for design context.
Can I have all three? Yes - code context, capabilities, and design context, each in its own file.
The pattern is the same across all of them: persistent, plain-text, repo-resident context an agent reads every time. DESIGN.md is the design member of the family.
Free starter: The format, a complete annotated example, and the core idea are on a free cheat sheet: DESIGN.md Quick-Start Cheat Sheet
Go deeper: The full guide covers the entire format — the token schema, the CLI in depth, accessibility, Tailwind and DTCG export, agent integration, and a complete walkthrough: DESIGN.md: The Complete Guide to Design Systems for AI Agents
How many of these files are in your repos already - none, one, or the full set? Curious where everyone is on this.