DESIGN.md, CLAUDE.md, AGENTS.md: The Agent-Context File Family

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.

What each file covers

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.

Why separate files?

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.

They work together

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.

Which to adopt first

Start with the file that solves your biggest pain:

• Agent gets code conventions wrong -> CLAUDE.md / AGENTS.md


• Agent writes correct code that looks off-brand -> DESIGN.md

Most teams end up with more than one, added as the need appears.

FAQ

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.

Bottom line

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.