Getting Started

DESIGN.md vs AGENTS.md

A clean mental model for splitting agent instructions by domain.

May 10, 20267 min read

AGENTS.md handles execution

Before an autonomous Codex agent touches a single file in the repository, it reads AGENTS.md to understand the rules of engagement — how to navigate the codebase, which commands to run, how to verify work before committing, and which directories are off-limits. A well-written AGENTS.md tells the agent how to navigate the codebase, which commands to run, how to verify work before finishing, what test commands exist, how to handle file conflicts, which directories are off-limits, and how to format commits. It is an execution contract: it governs the agent's actions, not its output taste. The goal of AGENTS.md is to make autonomous operation predictable and safe — an agent that follows a good AGENTS.md should behave as a reliable engineer who understands the codebase conventions and can act independently without breaking things. Its scope is deliberately bounded to process and code quality rather than to visual or product output.

DESIGN.md handles output taste

Following every rule in AGENTS.md perfectly still leaves the visual output entirely up to the agent's trained defaults — which is exactly the gap DESIGN.md fills. Where AGENTS.md tells the agent what to do and how to do it, DESIGN.md tells the agent what the product should look like when the work is done. These are genuinely different dimensions of implementation quality. An agent can perfectly follow every rule in AGENTS.md — correct file structure, proper commit format, passing tests — while still producing UI that looks generic, inconsistent, or misaligned with the product's design system. The visual quality of the output depends entirely on the design information the agent was given. DESIGN.md carries that information. Together, AGENTS.md and DESIGN.md give an autonomous agent two complete layers of instruction: how to work and what to produce visually. Without both, either the process quality or the product quality is left to chance.

Why it matters

Separating execution rules from visual rules has compounding benefits over time. Each file stays shorter, more focused, and easier to maintain because it covers only one domain. Agents can read only the relevant file for a given task: a pure backend task does not need DESIGN.md, and a UI polish task does not need to wade through AGENTS.md. Updates to one file do not affect the other: a new CI command in AGENTS.md does not require a design review, and a new card density rule in DESIGN.md does not require engineering sign-off. The separation also makes each file more useful as a standalone reference. A new team member who wants to understand the engineering conventions reads AGENTS.md. A designer reviewing AI-generated UI reads DESIGN.md against the output. The clarity that comes from having two focused files consistently produces better-maintained documentation than one combined document that grows in two directions simultaneously.

Writing AGENTS.md well

A complete AGENTS.md for a mid-size project covers eight things: the repository layout naming which directories are writable and which are read-only, the exact commands to install dependencies and run tests with full invocations rather than paraphrases, the definition of a passing test run and whether tests must pass before committing, the commit format and branch naming conventions used in the project, the list of auto-generated files the agent must not edit directly, any environment differences from the default setup that affect how commands behave, dependency installation quirks for packages with native bindings or unusual setup requirements, and the procedure for handling file conflicts when they arise during implementation. Simpler projects can compress this to four or five points and stay under a page. The only test that matters for a well-written AGENTS.md: could a new agent read this file and complete a full feature implementation — including tests, lint, and commit — without making a single process mistake?

Writing DESIGN.md well

A complete DESIGN.md for a mid-size product covers seven things: the product personality in one concise paragraph that captures emotional register and visual direction, the color tokens with semantic roles and explicit usage constraints (not just hex values but where each color applies and where it is prohibited), the typography scale with exact font sizes and weights for every heading level and text role used in the product, the spacing system with pixel values mapped to specific component contexts rather than listed as an abstract scale, the component rules for the most common UI elements with enough specificity to implement each correctly without asking for clarification, two or three common page layout patterns describing how full screens should be structured, and the anti-patterns section that explicitly names visual choices that are never acceptable in this product. A simpler product can start with just color, type scale, and anti-patterns, then add component depth as more surfaces are built. The only test that matters: could an agent read this file alone and produce a new screen that looks like it belongs to the product?

The combined setup in practice

Teams that adopt both files consistently find one result: AI-generated pull requests require less review time, because AGENTS.md reduces process errors and DESIGN.md reduces visual drift — the two most common correction categories in AI-generated code. When starting a task that involves both engineering work and UI work, the prompt includes both: "Read AGENTS.md for process rules and DESIGN.md for visual rules before planning." When starting a pure engineering task, only AGENTS.md is referenced. When starting a pure UI task, only DESIGN.md is referenced. This keeps context lean while making both files available when needed. Teams that adopt this two-file setup typically find that AI-generated pull requests require less review time — AGENTS.md reduces process errors and DESIGN.md reduces visual drift, which are the two most common categories of correction in AI-generated code. The setup is easy to adopt incrementally: start with whichever file addresses the most urgent current problem, and add the second file when the first is solid enough to rely on.

Use DESIGN.md with a real product reference

Browse curated DESIGN.md examples from product teams, design systems, developer tools, SaaS dashboards, and AI-native apps. Use them as references before your agent builds the next screen.

Browse directory Submit DESIGN.md

Related guides

Getting Started7 min read