DESIGN.md + AGENTS.md + RULES.md: qual arquivo faz o quê

design-md agents-md rules comparação

DESIGN.md + AGENTS.md + RULES.md: qual arquivo faz o quê

Abra a raiz de qualquer repositório sério hoje e conte os arquivos de contexto para agentes: DESIGN.md, AGENTS.md, CLAUDE.md, CODEX.md, .cursorrules, .clinerules, .github/copilot-instructions.md, .windsurfrules. Parece uma bagunça de config files dos anos 2000 — e é exatamente isso que está acontecendo.

Murphy Trueman escreveu no Medium o que muita gente tava pensando: “Your design system is fragmenting into agent files.” A observação é certeira. Em vez de um sistema coerente, temos pedaços de instrução espalhados por meia dúzia de arquivos que nenhum agente carrega todos ao mesmo tempo. É a Torre de Babel dos dotfiles.

O problema real: ninguém sabe onde colocar o quê

A confusão não é teórica. Ela aparece assim na prática:

Sem um modelo mental claro, as informações vão parar em qualquer arquivo que a pessoa lembrou primeiro. Resultado: redundância, contradição, e agentes que carregam só parte do contexto.

O mapa: cada arquivo, uma responsabilidade

Aqui está a taxonomia que funciona. Cada arquivo tem um escopo claro, e se você seguir esse modelo, nunca vai ter dúvida de onde colocar algo.

DESIGN.md — O visual

Responsabilidade: Tudo que afeta a aparência da interface.

Contém:

Não contém:

Quem consome: Qualquer agente gerando UI — Cursor, Copilot, Claude, Codex, Windsurf, Cline. É portátil, agnóstico de ferramenta.

Exemplo de conteúdo:

## 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 — O comportamento do código

Responsabilidade: Como o agente deve escrever código neste repositório. Regras de engenharia, não de design.

Contém:

Não contém:

Quem consome: Qualquer agente trabalhando no código — é universal.

Exemplo de conteúdo:

## 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 — Ferramenta-específico

Responsabilidade: Instruções que só fazem sentido para aquela ferramenta específica.

Contém:

Não contém:

Quem consome: Apenas a ferramenta específica.

Exemplo de conteúdo (.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 — Modelo-específico

Responsabilidade: Instruções que exploram capacidades ou mitigam limitações de um modelo/provider específico.

Contém:

Não contém:

Quem consome: Apenas aquele modelo/provider.

Exemplo de conteúdo (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

O fluxograma de decisão

Quando surge uma nova instrução, passe por esse filtro:

┌─────────────────────────────────────────────────┐
│ "Preciso instruir o agente sobre X"             │
└───────────────────────┬─────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────┐
│ X afeta a APARÊNCIA da interface?               │
│ (cores, fontes, componentes, layout, animações) │
└───────┬───────────────────────────┬─────────────┘
        │ SIM                       │ NÃO
        ▼                           ▼
   DESIGN.md              ┌─────────────────────────────────┐
                          │ X é regra de CÓDIGO universal?   │
                          │ (patterns, stack, conventions,   │
                          │  git workflow, segurança)        │
                          └───────┬───────────────┬─────────┘
                                  │ SIM           │ NÃO
                                  ▼               ▼
                             AGENTS.md   ┌──────────────────────────┐
                                         │ X só se aplica a UMA     │
                                         │ ferramenta? (Cursor,     │
                                         │ Cline, Windsurf)         │
                                         └───────┬──────────┬───────┘
                                                 │ SIM      │ NÃO
                                                 ▼          ▼
                                          .cursorrules  ┌────────────────────┐
                                          .clinerules   │ X só se aplica a   │
                                          etc.          │ UM modelo? (Claude,│
                                                        │ GPT, Copilot)      │
                                                        └──────┬──────┬──────┘
                                                               │ SIM  │ NÃO
                                                               ▼      ▼
                                                         CLAUDE.md  AGENTS.md
                                                         CODEX.md   (fallback
                                                         etc.        universal)

Se você chegou no final sem saber onde colocar, vai no AGENTS.md. É o fallback universal — tudo que é “instrução para o agente que não cabe em lugar mais específico” vai ali.

Os erros mais comuns

Erro 1: Colocar design tokens no AGENTS.md

Vi isso dezenas de vezes. O AGENTS.md vira um frankenstein com regras de git, conventions de TypeScript, E cores do design system tudo misturado. O agente carrega — mas outro dev que só precisa das regras de código recebe noise visual desnecessário.

Fix: Tokens e componentes visuais → DESIGN.md. Sempre.

Erro 2: Duplicar regras entre .cursorrules e AGENTS.md

“Use TypeScript strict mode” aparece nos dois. Quando alguém atualiza um e esquece o outro, o agente recebe instrução contraditória dependendo de qual arquivo tem prioridade.

Fix: Se vale pra qualquer ferramenta, só no AGENTS.md. O .cursorrules é suplemento, não cópia.

Erro 3: DESIGN.md como código

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

Isso é documentação de API, não design spec. O DESIGN.md deve dizer quando usar Button primary, não como importar o componente.

Fix: O DESIGN.md descreve intenção e decisões visuais. O código da implementação fica no codebase (ou no Storybook).

Erro 4: Um arquivo gigante porque “é mais fácil”

Algumas equipes jogam tudo num AGENTS.md de 3000 linhas. “O agente lê tudo de uma vez.” Sim, e consome 15K tokens de contexto com informação que pode não ser relevante pra task atual.

Fix: Separar por responsabilidade. Agentes inteligentes (Claude, GPT-4) já sabem carregar seletivamente — DESIGN.md quando a task é UI, AGENTS.md quando é código, ambos quando é full-stack.

O caso real: repositório organizado

Aqui está como fica um repositório bem organizado:

meu-projeto/
├── DESIGN.md                  ← Visual: tokens, components, behaviors
├── AGENTS.md                  ← Código: 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/
    └── ...

Cada arquivo é curto, focado, sem redundância. Um dev novo olha e sabe exatamente onde editar cada tipo de instrução.

”Mas eu só uso Cursor. Preciso de todos esses?”

Não. Se você só usa uma ferramenta e um modelo, a versão minimalista é:

meu-projeto/
├── DESIGN.md     ← Visual (se tem UI)
├── AGENTS.md     ← Tudo que é código + comportamento do agente
└── .cursorrules  ← Coisas muito específicas do Cursor (se tiver)

Dois ou três arquivos. A taxonomia serve pra escalar — quando o time cresce, quando ferramentas mudam, quando um colega usa Windsurf em vez de Cursor.

O futuro: convergência ou mais fragmentação?

A tendência curto prazo é mais fragmentação. Cada ferramenta inventa seu formato (.clinerules, .windsurfrules, .boltrules). É o mesmo padrão que vimos com linters — .eslintrc, .prettierrc, .stylelintrc — até alguém unificar.

A tendência longo prazo é convergência num padrão. E o candidato mais forte é justamente a separação clara entre DESIGN.md (visual) e AGENTS.md (código). Esses dois formatos estão se tornando padrão de facto — a maioria das ferramentas já lê ambos.

Os arquivos ferramenta-específicos vão virar como browser prefixes: necessários por um tempo, irrelevantes quando o padrão estabilizar.

A regra de ouro

Se está em dúvida, pergunte: “Isso é sobre como a coisa PARECE ou sobre como o CÓDIGO funciona?”

Pronto. Não precisa de mais que isso.

O que ninguém está falando: manutenção

O problema real não é criar esses arquivos — é mantê-los atualizados. Design system evolui, conventions mudam, ferramentas são trocadas.

Dicas práticas:

  1. Review nos PRs: Mudou um componente? O DESIGN.md reflete? Adicione ao checklist de PR.
  2. Data de revisão: Coloque um # Last reviewed: 2026-07-01 no topo. Se tem mais de 3 meses, revise.
  3. Owner claro: DESIGN.md é responsabilidade do design. AGENTS.md do tech lead. .cursorrules de quem usa Cursor.
  4. Testes de sanidade: Uma vez por mês, peça ao agente para gerar algo novo usando só os context files. Se o resultado está errado, os arquivos estão desatualizados.

Conclusão: ordem no caos

A proliferação de context files não é um problema — é uma solução emergente para um problema real. Agentes precisam de contexto, e diferentes tipos de contexto naturalmente vivem em diferentes lugares.

O caos surge quando não há modelo mental. Com o mapa deste artigo, você sabe exatamente onde cada informação vive. Seu time não duplica. Seus agentes não recebem contradição. E quando muda algo, você sabe qual arquivo editar.

Simplifique: visual no DESIGN.md, código no AGENTS.md, ferramentas no seu dotfile, modelos no seu .md. Taxonomia resolvida.

Quer gerar seu DESIGN.md automaticamente? O designmd.app analisa seu site e produz uma spec de design completa — tokens, componentes, behaviors — pronta para qualquer agente consumir. É o par perfeito para o seu AGENTS.md. Teste grátis.