DESIGN.md + AGENTS.md + RULES.md: which file does what

design-md agents-md rules comparison

DESIGN.md + AGENTS.md + RULES.md: which file does what

Open the root of any serious repository today and count the context files for agents: DESIGN.md, AGENTS.md, CLAUDE.md, CODEX.md, .cursorrules, .clinerules, .github/copilot-instructions.md, .windsurfrules. It looks like the config file mess from the early 2000s, and that’s exactly what’s happening.

Murphy Trueman wrote on Medium what a lot of people were thinking: “Your design system is fragmenting into agent files.” The observation is dead on. Instead of one coherent system, we have instruction fragments scattered across half a dozen files that no single agent loads all at once. It’s the Tower of Babel of dotfiles.

The real problem: nobody knows where to put what

This confusion isn’t theoretical. It shows up like this in practice:

Without a clear mental model, information ends up in whichever file the person remembered first. The result: redundancy, contradictions, and agents that only load part of the context.

The map: one file, one responsibility

Here’s the taxonomy that actually works. Each file has a clear scope. Follow this model and you’ll never wonder where something belongs.

DESIGN.md: the visual layer

Responsibility: Everything that affects how the interface looks.

Contains:

Does not contain:

Who consumes it: Any agent generating UI: Cursor, Copilot, Claude, Codex, Windsurf, Cline. It’s portable, tool-agnostic.

Example content:

## Colors
- primary: #2563EB
- destructive: #DC2626

## Components
### Button
- Variants: primary, secondary, ghost
- Use primary: main CTA (one per viewport)
- Never: two primary buttons side by side

AGENTS.md: code behavior

Responsibility: How the agent should write code in this repository. Engineering rules, not design rules.

Contains:

Does not contain:

Who consumes it: Any agent working on the code. Universal.

Example content:

## Stack
- Runtime: Node 22
- Framework: Astro 5 + React
- Styling: Tailwind CSS v4 (utility-first, never CSS modules)
- Database: SQLite via Drizzle ORM

## Conventions
- Functions over classes
- Colocation: component + test + styles in same folder
- Named exports only (no default exports)

.cursorrules / .clinerules / .windsurfrules: tool-specific

Responsibility: Instructions that only make sense for that specific tool.

Contains:

Does not contain:

Who consumes it: Only that specific tool.

Example content (.cursorrules):

## Cursor-specific
- Always use Composer for multi-file changes
- When editing tests, run them automatically after changes
- Prefer inline diffs over full file rewrites

CLAUDE.md / CODEX.md / copilot-instructions.md: model-specific

Responsibility: Instructions that exploit capabilities or mitigate limitations of one specific model/provider.

Contains:

Does not contain:

Who consumes it: Only that model/provider.

Example content (CLAUDE.md):

## Claude-specific
- Use extended thinking for architecture decisions
- Prefer tool use over inline code execution
- When reading SOPS files, never echo decrypted values

The decision flowchart

When a new instruction comes up, run it through this filter:

┌─────────────────────────────────────────────────┐
│ "I need to instruct the agent about X"          │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│ Does X affect the APPEARANCE of the interface?  │
│ (colors, fonts, components, layout, animations) │
└───────┬───────────────────────────┬─────────────┘
        │ YES                       │ NO
        ▼                           ▼
   DESIGN.md              ┌─────────────────────────────────┐
                          │ Is X a universal CODE rule?      │
                          │ (patterns, stack, conventions,   │
                          │  git workflow, security)         │
                          └───────┬───────────────┬─────────┘
                                  │ YES           │ NO
                                  ▼               ▼
                             AGENTS.md   ┌──────────────────────────┐
                                         │ Does X only apply to ONE │
                                         │ tool? (Cursor, Cline,    │
                                         │ Windsurf)                │
                                         └───────┬──────────┬───────┘
                                                 │ YES      │ NO
                                                 ▼          ▼
                                          .cursorrules  ┌────────────────────┐
                                          .clinerules   │ Does X only apply  │
                                          etc.          │ to ONE model?      │
                                                        │ (Claude, GPT,      │
                                                        │ Copilot)           │
                                                        └──────┬──────┬──────┘
                                                               │ YES  │ NO
                                                               ▼      ▼
                                                         CLAUDE.md  AGENTS.md
                                                         CODEX.md   (universal
                                                         etc.        fallback)

If you reach the end without knowing where to put something, it goes in AGENTS.md. That’s the universal fallback. Everything that qualifies as “instruction for the agent that doesn’t fit somewhere more specific” lives there.

The most common mistakes

Mistake 1: Putting design tokens in AGENTS.md

I’ve seen this dozens of times. AGENTS.md becomes a frankenstein monster with git rules, TypeScript conventions, AND design system colors all mashed together. The agent loads it, sure. But another dev who only needs the code rules gets buried in visual noise they don’t care about.

Fix: Tokens and visual components always go in DESIGN.md. No exceptions.

Mistake 2: Duplicating rules between .cursorrules and AGENTS.md

“Use TypeScript strict mode” appears in both files. When someone updates one and forgets the other, the agent receives contradictory instructions depending on which file takes priority.

Fix: If it applies to any tool, put it only in AGENTS.md. The .cursorrules file is a supplement, not a copy.

Mistake 3: DESIGN.md as code documentation

## Button Component
import { Button } from '@/components/ui/button'
<Button variant="primary" size="lg">Click</Button>

That’s API documentation, not a design spec. DESIGN.md should say when to use Button primary, not how to import the component.

Fix: DESIGN.md describes intent and visual decisions. Implementation code stays in the codebase (or in Storybook).

Mistake 4: One giant file because “it’s easier”

Some teams dump everything into a 3000-line AGENTS.md. “The agent reads it all at once.” Yes, and it consumes 15K context tokens with information that may not even be relevant to the current task.

Fix: Separate by responsibility. Smart agents (Claude, GPT-4) already know how to load selectively: DESIGN.md when the task is UI, AGENTS.md when it’s code, both when it’s full-stack.

A real-world example: organized repository

Here’s what a well-organized repository looks like:

my-project/
├── DESIGN.md                  ← Visual: tokens, components, behaviors
├── AGENTS.md                  ← Code: stack, conventions, git workflow
├── CLAUDE.md                  ← Claude-specific: thinking mode, tool use prefs
├── CODEX.md                   ← Codex-specific: sandbox constraints
├── .cursorrules               ← Cursor-specific: composer prefs, auto-run
├── .clinerules                ← Cline-specific: approval mode, verbosity
├── .github/
│   └── copilot-instructions.md ← Copilot-specific: suggestion style
└── src/
    └── ...

Each file is short, focused, zero redundancy. A new developer looks at this and knows exactly where to edit each type of instruction.

”But I only use Cursor. Do I need all of these?”

No. If you only use one tool and one model, the minimalist version is:

my-project/
├── DESIGN.md     ← Visual (if you have UI)
├── AGENTS.md     ← Everything code + agent behavior
└── .cursorrules  ← Cursor-specific stuff (if any)

Two or three files. That’s it. The taxonomy exists for scale. When the team grows, when tools change, when a colleague uses Windsurf instead of Cursor, the separation already makes sense.

The future: convergence or more fragmentation?

Short-term trend: more fragmentation. Every tool invents its own format (.clinerules, .windsurfrules, .boltrules). It’s the same pattern we saw with linters (.eslintrc, .prettierrc, .stylelintrc) until someone unified them.

Long-term trend: convergence around a standard. And the strongest candidates are precisely the clean separation between DESIGN.md (visual) and AGENTS.md (code). These two formats are becoming de facto standards. Most tools already read both.

Tool-specific files will become like browser prefixes: necessary for a while, irrelevant once the standard stabilizes. I give it 18 months before at least two major tools announce they’re deprecating their proprietary format in favor of a shared one. Maybe I’m being optimistic. But the pressure is clearly there.

The golden rule

If you’re unsure, ask: “Is this about how the thing LOOKS or about how the CODE works?”

Done. You don’t need more than that. If a rule applies to both visual and code (say, “always use 8px grid”), put it where it’s more likely to be needed. A component spacing rule goes in DESIGN.md. A file indentation rule goes in AGENTS.md. Use judgment.

What nobody’s talking about: maintenance

The real problem isn’t creating these files. It’s keeping them updated. Design systems evolve, conventions change, tools get swapped out. A beautifully organized set of context files that hasn’t been touched in 6 months is worse than a messy single file that someone updates weekly.

Practical tips:

  1. Review in PRs: Changed a component? Does DESIGN.md reflect it? Add it to your PR checklist.
  2. Revision date: Put a # Last reviewed: 2026-07-01 at the top. If it’s been more than 3 months, review it.
  3. Clear ownership: DESIGN.md is design’s responsibility. AGENTS.md is the tech lead’s. .cursorrules belongs to whoever uses Cursor.
  4. Sanity checks: Once a month, ask the agent to generate something new using only the context files. If the result is wrong, your files are stale.

I’ll add a fifth one that’s less obvious: treat these files like production code. They affect your team’s output quality every single day. A stale DESIGN.md is like a broken test. It actively makes things worse because the agent trusts it and produces confidently wrong output based on outdated information.

Conclusion: order from chaos

The proliferation of context files isn’t a problem. It’s an emergent solution to a real problem. Agents need context, and different types of context naturally live in different places. The chaos only happens when there’s no mental model guiding the organization.

With the map from this article, you know exactly where each piece of information lives. Your team doesn’t duplicate. Your agents don’t receive contradictions. And when something changes, you know which file to edit.

Keep it simple: visual stuff in DESIGN.md, code stuff in AGENTS.md, tool quirks in their dotfile, model quirks in their .md file. Taxonomy solved. Move on and build something.

Want to generate your DESIGN.md automatically? designmd.app analyzes your site and produces a complete design spec: tokens, components, behaviors, ready for any agent to consume. It’s the perfect companion for your AGENTS.md. Try it free.