AI Coding Agent Design Files: CLAUDE.md, AGENTS.md, and DESIGN.md Explained
A short history of repo-level instructions for AI agents
The root directory of a software repository has always functioned as the primary interface between the codebase and the developer. Over decades, clear conventions emerged. The README.md file became the standard for project overviews and setup instructions. The CONTRIBUTING.md file evolved to govern human collaboration, outlining pull request standards and code review expectations.
As Large Language Models and AI coding agents entered the development workflow, a new pattern emerged: adapting human conventions into agent conventions. Engineers quickly realized that standard system prompts were insufficient for complex codebases. The AI needed persistent, repository-specific context. This led to the adoption of files like CLAUDE.md, designed to feed strict behavioral rules directly into the agent's context window. We are now seeing the formalization of specialized files that split instructions into discrete domains, shaping a new architecture for AI-assisted development.
The three files at the root, what each one owns
To manage the complexity of AI context windows, instructions are increasingly divided across three primary files, each with a strict domain of responsibility.
First is CLAUDE.md (or its equivalent cursorrules file). This file owns behavior, coding conventions, and repository context. It tells the AI how to write tests, which libraries to prefer, and how to structure module imports.
Second is AGENTS.md. This file owns capabilities and orchestration patterns. It defines the specific sub-agents available within a project, their tool access permissions, and the workflows required for complex, multi-step tasks.
Third is DESIGN.md. This file owns the visual identity, design tokens, and UI components. It provides the machine-readable specifications required to generate interface code that perfectly matches a product's brand guidelines. Understanding what DESIGN.md is is important for standardizing frontend AI generation.
CLAUDE.md in depth
The CLAUDE.md file is the foundational behavioral layer. When tools like Claude Code initialize in a directory, they actively look for this file to establish baseline operational rules.
Typical contents include strict directives regarding architectural choices. For example, a CLAUDE.md file might explicitly instruct the agent to use standard fetch over axios, or to strictly type all API responses. It often includes project-specific context, such as explaining that the lib/core directory contains legacy code that should not be refactored without explicit permission.
Anti-patterns in CLAUDE.md usually involve overloading the file. When engineers attempt to cram visual design rules, routing logic, and deployment scripts into this single document, the AI's attention mechanism degrades. The context window becomes diluted, leading to hallucinations and ignored instructions.
AGENTS.md in depth
As AI development moves from single-turn completions to autonomous task execution, AGENTS.md provides the necessary orchestration map.
This file covers the definitions of distinct AI personas operating within the repository. It dictates that a "Reviewer" agent has read-only access to the source code but full access to the testing suite, while a "Scaffolder" agent is permitted to write new files and execute package managers.
AGENTS.md sits functionally between the behavioral rules of CLAUDE.md and the visual rules of DESIGN.md. It tells the system who is doing the work and how they're allowed to operate, relying on the other files to dictate the quality and style of the output.
DESIGN.md in depth
Visual design requires its own semantic structure, which is why DESIGN.md exists.
The structure of the file relies on a YAML frontmatter block that defines exact values for colors, typography, spacing scales, border radius, and shadows. Below this block, markdown narrative explains how to compose components using the defined tokens. For an exact breakdown of this syntax, consult the DESIGN.md specification.
Visuals deserve their own file because design systems are inherently cross-functional. A product's design identity often needs to be referenced independently of its backend routing rules or testing conventions. By isolating these tokens, agents can parse the exact hex codes and spacing values without parsing unrelated server logic. If you want to look closer into this integration, explore how this file interacts when building design systems for AI development.
How the three files cooperate
In a mature, AI-ready monorepo, these three files cooperate to provide a comprehensive context environment.
Consider a standard Next.js repository. The CLAUDE.md file instructs the agent to use App Router conventions and strictly type server actions. The AGENTS.md file defines a workflow where a planner agent drafts the component structure before a coder agent implements it. The DESIGN.md file provides the exact Tailwind utility classes required to match the brand identity.
When a developer prompts, "Build the new user dashboard," the prompt references all three. The system limits token expenditure by pulling only the necessary design tokens for the frontend, the server action rules for the backend integration, and the workflow rules for the execution. Ordering in the context window is typically handled by the agent, but separating the files ensures the system can index and retrieve the specific domain knowledge efficiently. To see how different IDEs handle this, you can read our guides on using DESIGN.md with Cursor, using DESIGN.md with Claude Code, and using DESIGN.md with Copilot.
When you don't need all three
Not every project requires the full trio of files. Pragmatic adoption depends on the repository's scope.
Strictly backend-only projects, such as Go microservices or Python data pipelines, should skip DESIGN.md entirely. There is no graphical interface to govern, rendering visual tokens useless overhead.
Similarly, single-agent setups or smaller side projects can safely fold any basic orchestration rules directly into the CLAUDE.md file. The complexity of a dedicated AGENTS.md file is unnecessary when only one standard agent is executing tasks.
The simplest effective case for frontend and full-stack applications is often just DESIGN.md paired with CLAUDE.md. This provides both behavioral guardrails and visual consistency, which is the baseline requirement for most product engineering. You can read more about our philosophy on AI tooling on our about page.
Future of the convention
The landscape of AI repo files is shifting rapidly. We are seeing these disparate files converging toward standard, recognizable schemas.
In the near future, we anticipate standardization across the major LLM providers regarding how these files are formatted and ingested. Much like package.json became the undisputed standard for Node environments, a unified schema for AI context files is inevitable. Until then, segmenting responsibilities across CLAUDE.md, AGENTS.md, and DESIGN.md remains the most robust architecture for AI-assisted software engineering.
Get Started
Start with DESIGN.md — extract one in 3 minutes. Visit designmd.run to automate your design extraction today.