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

DESIGN.md, CLAUDE.md and AGENTS.md are plain-text, repository-resident files that give AI coding agents persistent context. CLAUDE.md and AGENTS.md cover code and project conventions; DESIGN.md covers the visual identity. They are complementary layers an agent reads on every interaction.

What does each file cover?

CLAUDE.md and AGENTS.md hold project and code context — the stack, conventions, commands, and constraints an agent needs to write code that fits your repository. DESIGN.md holds the design system — the tokens and the rationale for applying them. A third pattern, SKILL.md, packages on-demand capabilities. Each handles a different concern, and they do not overlap.

Why are they separate files?

Separation keeps each file focused and lets you adopt them independently. A team might start with CLAUDE.md for code context, add DESIGN.md when agent-generated UI starts drifting off-brand, and layer in skills later. Because they are all plain text in the repository, they version and review like code.

Do they work together?

Yes. The cleanest setup wires them together: a CLAUDE.md that tells the agent to read DESIGN.md for any UI work links code context to design context. The agent then has one coherent picture — how to write the code and how to make it look right.

Which should I adopt first?

Start with the file that solves your biggest pain. If the agent gets your code conventions wrong, begin with CLAUDE.md or AGENTS.md. If it writes correct code that looks off-brand, DESIGN.md is the missing piece. Most teams end up with more than one, added as the need appears.

FAQ

Is there one universal format? AGENTS.md is the closest to a cross-tool standard for code context; DESIGN.md is the emerging standard for design context. They complement rather than compete.

Can I have all three? Yes — code context, capabilities, and design context, each in its own file, read by the same agent.