DESIGN.md vs AGENTS.md — Design visual e comportamento de agente são coisas diferentes

Veredito Rápido

Não são concorrentes. DESIGN.md define como as coisas devem parecer. AGENTS.md define como o agente deve se comportar. Um é o design system legível por máquina. O outro é o manual de conduta do assistente. Usar só um é como contratar um pintor que sabe misturar cores mas não sabe que parede pintar — ou que sabe a planta da casa mas não distingue azul de verde. Use os dois.

Tabela Comparativa

Dimensão	DESIGN.md	AGENTS.md
Escopo	Design system — aparência visual	Comportamento e workflow do agente
Conteúdo típico	Tokens (cores, tipo, spacing), componentes, rationale visual	Regras de conduta, ferramentas disponíveis, convenções de código
Quem consome	AI agents gerando UI/frontend	AI agents fazendo qualquer tarefa no repo
Quando atualiza	Quando design system muda	Quando workflow ou convenções mudam
Formato	YAML tokens + Markdown explicativo	Markdown puro (instruções textuais)
Sem ele, o agente…	Gera UI inconsistente, ignora design system	Ignora convenções do projeto, faz coisas que não deveria
Padrão de mercado	Google Labs, 24K stars	Anthropic/Claude, adotado por múltiplas ferramentas
Arquivo no repo	`DESIGN.md` (raiz ou /docs)	`AGENTS.md` (raiz)

DESIGN.md em Detalhe

Domínio: O Visual

DESIGN.md responde perguntas como:

Qual a cor primária e quando usá-la?
Qual fonte usar em headings vs body?
Quanto espaçamento entre componentes?
Cards têm borda ou sombra? Qual radius?
Qual a filosofia visual — minimal? brutalist? playful?

O que contém

# Tokens estruturados
colors:
  brand:
    primary: { value: "#1a1a2e", usage: "CTAs, headers" }
    accent: { value: "#e94560", usage: "Destaques, badges, alertas" }
  semantic:
    success: { value: "#10b981", usage: "Confirmações, status positivo" }
    error: { value: "#ef4444", usage: "Erros, validações" }

typography:
  display: { family: "Cal Sans", weight: 700 }
  body: { family: "Inter", weight: 400 }

spacing:
  unit: "4px"
  scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]

Mais seções Markdown:

## Filosofia Visual

Design minimalista com espaço negativo generoso.
Tipografia como elemento principal de hierarquia.
Cor usada com parcimônia — mostly neutral, accent para chamar atenção.

## Anti-padrões

- Nunca usar gradientes em backgrounds
- Nunca usar mais de 2 font-weights no mesmo componente
- Nunca usar sombras em elementos inline

Impacto no output do agente

Sem DESIGN.md: agente gera um botão com bg-blue-500 text-white rounded-md px-4 py-2 — genérico, funcional, sem identidade.

Com DESIGN.md: agente gera bg-primary text-primary-foreground rounded-lg px-6 py-3 font-display font-semibold — consistente com o sistema, identidade preservada.

AGENTS.md em Detalhe

Domínio: O Comportamento

AGENTS.md responde perguntas como:

Em qual idioma o agente deve responder?
Quais ferramentas e credenciais estão disponíveis?
Qual a estrutura do repositório?
O que o agente NUNCA deve fazer?
Como commitar, qual convenção de mensagem?
Quais skills/workflows seguir?

O que contém (exemplo real)

# AGENTS.md

## Regra Principal
Interaja em Português Brasileiro.

## Estrutura do Repositório
homelab/
├── .agents/skills/    ← Skills operacionais
├── brain/             ← Vault Obsidian
└── AGENTS.md          ← Este arquivo

## Convenções
- Commits: `docs(<skill>): <descrição>`
- Credenciais: SOPS + age, nunca exibir descriptografado
- Sempre ler SKILL.md antes de executar operação

## Segurança
- NUNCA exibir conteúdo descriptografado
- NUNCA criar repos públicos
- Menor privilégio em tokens

Impacto no output do agente

Sem AGENTS.md: agente responde em inglês, commita com mensagem genérica, pode expor credenciais, não sabe onde estão os scripts.

Com AGENTS.md: agente responde em PT-BR, segue convenção de commits, protege credenciais, sabe exatamente qual skill consultar.

São Complementares — Não Concorrentes

A confusão aparece porque ambos são “arquivos Markdown na raiz que instruem AI agents”. Mas a sobreposição é zero:

Pergunta	Quem responde
”Que cor usar no botão de CTA?”	DESIGN.md
”Em qual branch commitar?”	AGENTS.md
”Qual font-family pro heading?”	DESIGN.md
”Precisa rodar testes antes do commit?”	AGENTS.md
”Quanto de border-radius nos cards?”	DESIGN.md
”Qual idioma usar na documentação?”	AGENTS.md
”Dark mode usa qual surface?”	DESIGN.md
”Onde ficam as credenciais?”	AGENTS.md

O único ponto de contato

Se AGENTS.md menciona “siga o DESIGN.md para decisões visuais” — perfeito. Essa referência cruzada é o padrão ideal. O AGENTS.md é o manual geral que diz “pra design, consulta o DESIGN.md”. São camadas.

Anatomia de Um Projeto Bem Configurado

meu-projeto/
├── AGENTS.md              ← "Como se comportar neste repo"
│   └── Menciona: "Para UI, siga DESIGN.md"
│
├── DESIGN.md              ← "Como as coisas devem parecer"
│   └── Tokens + rationale visual
│
├── .cursorrules           ← Regras específicas do Cursor (pode duplicar parts de AGENTS.md)
├── CLAUDE.md              ← Regras específicas pro Claude
│
├── src/
├── package.json
└── tailwind.config.js     ← Runtime que implementa os tokens do DESIGN.md

Cada arquivo tem jurisdição clara. Não há conflito porque não há sobreposição de domínio.

Quando Usar Qual

Crie DESIGN.md quando:

Projeto tem UI (frontend, landing page, app, dashboard)
Usa AI agents pra gerar componentes visuais
Design system tem tokens customizados (não é só default do framework)
Precisa de consistência visual entre múltiplos contribuidores ou agentes
Quer que qualquer agente (Cursor, Claude, Copilot) gere UI on-brand

Crie AGENTS.md quando:

Projeto usa AI agents para qualquer tarefa (não só UI)
Tem convenções de código, commit, branch que o agente deve seguir
Usa credenciais, ferramentas externas, APIs que precisam de instrução
Múltiplos agentes/ferramentas trabalham no mesmo repo
Precisa de guardrails de segurança e comportamento

Crie ambos quando:

Qualquer projeto com UI que usa AI agents — que é a maioria dos projetos em 2026
Quer consistência visual E comportamental
Time distribuído onde agentes fazem trabalho significativo

Não precisa de DESIGN.md quando:

Projeto é backend puro (API, CLI, infraestrutura sem UI)
Não usa AI agents pra gerar frontend
UI é terminal/texto sem design visual

Não precisa de AGENTS.md quando:

Projeto pessoal onde você é o único operador
Não usa AI agents de forma significativa
Convenções são óbvias pelo código existente (raro, mas existe)

Erros Comuns

Erro 1: Colocar tokens de design no AGENTS.md

“O AGENTS.md já instrui o agente, então coloco tudo lá.”

Problema: AGENTS.md vira enorme, perde foco, e tokens de design ficam misturados com regras de git e segurança. O agente precisa parsear tudo pra achar uma cor. DESIGN.md é focused e otimizado pra consumo de tokens.

Erro 2: Colocar regras de workflow no DESIGN.md

“Quero que o agente sempre rode lint antes de commitar, coloco no DESIGN.md.”

Problema: DESIGN.md é sobre aparência, não processo. Regras de workflow pertencem ao AGENTS.md. Misturar domínios confunde o agente sobre o escopo de cada arquivo.

Erro 3: Não criar referência cruzada

Dois arquivos existem mas nenhum menciona o outro. O agente pode ignorar DESIGN.md se AGENTS.md não aponta pra ele.

Solução: AGENTS.md deve conter uma linha tipo: “Para decisões de design visual e tokens, consulte DESIGN.md.”

Erro 4: Duplicar informação

Copiar tokens do DESIGN.md pro AGENTS.md “pra garantir”. Resultado: drift — uma versão é atualizada, a outra não. Single-source-of-truth: cada informação mora em um lugar só.

FAQ

Se tenho AGENTS.md, ainda preciso de DESIGN.md separado?

Sim, se seu projeto tem UI. AGENTS.md é generalista — cobre git, segurança, workflow, idioma. DESIGN.md é especialista — cobre visual, tokens, componentes. Separar mantém cada arquivo focado e evita que o agente precise parsear 2000 linhas pra achar um token de cor.

Qual criar primeiro?

AGENTS.md primeiro — é o manual geral que o agente lê imediatamente. Depois DESIGN.md para projetos com UI. Na prática, crie ambos no setup inicial do projeto (leva 1 hora total).

DESIGN.md funciona sem AGENTS.md?

Funciona para o escopo visual — o agente vai gerar UI consistente. Mas pode errar em workflow (commit errado, idioma errado, branch errada). Os dois juntos cobrem o espectro completo.

Posso usar um AGENTS.md que aponta para múltiplos DESIGN.md (monorepo)?

Sim. Em monorepos, cada app/package pode ter seu DESIGN.md: apps/marketing/DESIGN.md, apps/dashboard/DESIGN.md. O AGENTS.md raiz orienta o agente a consultar o DESIGN.md do contexto atual.

Outras ferramentas (Cursor, Windsurf, Copilot) reconhecem ambos?

AGENTS.md é reconhecido nativamente pelo Claude Code e está sendo adotado por outras ferramentas. DESIGN.md é reconhecido por qualquer agente que lê o contexto do projeto (o que inclui todos os AI coding agents modernos). Não depende de suporte nativo — é Markdown, qualquer LLM lê.

Conclusão

DESIGN.md e AGENTS.md são duas metades de um projeto AI-ready. Um sem o outro funciona pela metade.

DESIGN.md sozinho: UI bonita, mas agente commita errado, responde no idioma errado, expõe credenciais.

AGENTS.md sozinho: agente comportado, mas UI inconsistente, genérica, sem identidade visual.

Os dois juntos: agente que se comporta corretamente E gera UI on-brand. É o mínimo pra um projeto profissional em 2026.

A confusão “qual usar?” revela um mal-entendido sobre escopo. Não é um ou outro. É a combinação que faz o agente deixar de ser um autocomplete glorificado e virar um colega que conhece o projeto. O designmd.app cataloga 461 design systems no formato DESIGN.md — e a maioria dos projetos bem configurados tem um AGENTS.md vizinho na mesma raiz.