--- title: Como usar DESIGN.md com Claude Code, Cursor e agentes de IA date: 2026-05-07T00:09:00Z modified: 2026-09-08T18:00:17Z permalink: "https://camaraux.com.br/design-md-agentes-ia-ux/" type: post status: publish excerpt: "" wpid: 6386 categories: - UX & IA rank_math_title: "DESIGN.md com Claude Code e Cursor: guia prático" rank_math_description: Aprenda a usar DESIGN.md com Claude Code, Cursor e outros agentes de IA para aplicar regras e manter interfaces consistentes no código. rank_math_focus_keyword: design.md featured_image: /wp-content/uploads/2026/05/Como-usar-DESIGN.md-com-Claude-Code-Cursor-e-agentes-de-IA-.png featured_image_alt: Pessoa interagindo com painel de IA e conexões de nós em ambiente digital 3D author: Lucas Camara timestamp: 2026-09-08T18:00:17Z tags: - UX & IA --- Você já tem um `DESIGN.md` com cores, tipografia, espaçamento, componentes e regras visuais do produto. O próximo problema é fazer o agente de IA realmente usar esse contexto quando cria ou modifica a interface. Isso não acontece da mesma forma em todas as ferramentas. Claude Code, Cursor, GitHub Copilot e outros agentes possuem mecanismos próprios para carregar instruções e arquivos do projeto. Este guia mostra como conectar o `DESIGN.md` a esses ambientes sem depender da ideia genérica de que todo agente vai encontrar o arquivo automaticamente. Se você ainda está conhecendo o formato, comece pelo [guia e biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). Se precisa construir o arquivo do zero, use o guia [como criar um DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-aplicar-design-md-ia.md). Aqui, o foco é exclusivamente **como fornecer esse contexto para agentes de codificação**. ## Como o DESIGN.md funciona com agentes de IA A especificação oficial do Google Labs descreve o DESIGN.md como uma representação textual e autocontida de um design system. O arquivo combina valores estruturados, quando necessários, com orientações em linguagem natural sobre identidade visual e aplicação das decisões. Isso resolve uma diferença importante entre **contexto visual** e **instruções operacionais do agente**. | Arquivo | Função | | --- | --- | | `DESIGN.md` | Descreve como a interface deve parecer e quais regras visuais devem ser preservadas. | | `CLAUDE.md` | Fornece instruções persistentes para Claude Code. | | `.cursor/rules/*.mdc` | Fornece regras persistentes ou contextuais para o Agent do Cursor. | | `.github/copilot-instructions.md` | Fornece instruções de repositório para ambientes compatíveis do GitHub Copilot. | O DESIGN.md não precisa substituir esses arquivos. A arquitetura mais limpa é manter a identidade visual em um documento próprio e fazer o mecanismo de instruções de cada agente apontar para ele. Assim, o design system continua sendo uma fonte única de contexto em vez de ser copiado para `CLAUDE.md`, regras do Cursor e outros arquivos separadamente. ## DESIGN.md, CLAUDE.md e AGENTS.md são a mesma coisa? Não. Apesar de todos serem arquivos Markdown usados em fluxos com agentes de IA, eles resolvem problemas diferentes. Um `DESIGN.md` descreve principalmente **identidade visual e decisões de design**. Já arquivos como `CLAUDE.md` e `AGENTS.md` normalmente descrevem **como o agente deve trabalhar dentro do repositório**. | Arquivo | Exemplo de informação | | --- | --- | | `DESIGN.md` | Cor primária, tipografia, hierarquia, espaçamento, componentes e linguagem visual. | | `CLAUDE.md` | Comandos do projeto, arquitetura, padrões de código e arquivos que Claude deve consultar. | | `AGENTS.md` | Instruções compartilhadas para agentes sobre como trabalhar no codebase. | Na prática, eles podem trabalhar juntos. ``` projeto/ ├── DESIGN.md ├── CLAUDE.md ├── AGENTS.md ├── package.json ├── src/ └── ... ``` Nesse modelo, DESIGN.md continua responsável pela linguagem visual, enquanto os arquivos específicos dos agentes explicam quando e como consultar essa referência. ## Como usar DESIGN.md com Claude Code Claude Code possui suporte documentado a arquivos `CLAUDE.md` para manter instruções de projeto entre sessões. A Anthropic também permite importar outros arquivos para dentro do contexto do `CLAUDE.md` usando a sintaxe `@caminho/do/arquivo`. Isso torna a integração com DESIGN.md bastante direta. ### 1. Mantenha o DESIGN.md no projeto ``` meu-projeto/ ├── DESIGN.md ├── CLAUDE.md ├── src/ └── package.json ``` Não existe necessidade de copiar todo o conteúdo visual para o CLAUDE.md. ### 2. Importe o DESIGN.md no CLAUDE.md No arquivo `CLAUDE.md`, adicione uma referência explícita: ``` # Design e interface @DESIGN.md Ao criar ou modificar qualquer interface: - siga a identidade visual documentada em DESIGN.md; - reutilize os tokens e componentes existentes; - não invente novas cores, fontes ou espaçamentos quando o sistema já definir uma solução; - preserve os estados e restrições documentados; - verifique o resultado contra DESIGN.md antes de concluir a tarefa. ``` Segundo a documentação oficial do Claude Code, imports usando `@` são expandidos e carregados junto com o CLAUDE.md. Caminhos relativos são resolvidos em relação ao arquivo que contém a importação. Isso significa que você pode manter as decisões visuais separadas das demais instruções do agente sem perder o contexto durante a sessão. ### 3. Evite duplicar todo o DESIGN.md no CLAUDE.md Duplicação cria dois documentos que precisam ser mantidos sincronizados. Se a cor primária mudar no DESIGN.md, mas a versão copiada para CLAUDE.md permanecer antiga, o agente passa a receber instruções conflitantes. Prefira manter: - regras visuais no `DESIGN.md`; - regras de operação e desenvolvimento no `CLAUDE.md`; - uma referência entre os dois. ### 4. Verifique se Claude recebeu o contexto Antes de pedir a construção de uma tela inteira, faça um teste simples. ``` Antes de modificar o código, leia o DESIGN.md e me informe: 1. qual é a cor primária; 2. qual é a tipografia principal; 3. qual regra define botões primários; 4. quais restrições visuais você precisa preservar. ``` O objetivo não é fazer isso em toda tarefa. É validar a configuração inicial e confirmar que o agente está interpretando a fonte correta. ## Como usar DESIGN.md com Cursor No Cursor, a solução atual para contexto persistente são as **Project Rules**. A documentação oficial coloca essas regras em `.cursor/rules`. Cada regra é armazenada em um arquivo `.mdc` e pode ser aplicada sempre, associada a determinados arquivos ou disponibilizada ao agente conforme o contexto. O antigo arquivo `.cursorrules` ainda possui compatibilidade, mas é considerado legado pela documentação atual do Cursor. Para novas configurações, prefira Project Rules. ### 1. Crie uma regra de design ``` meu-projeto/ ├── DESIGN.md ├── .cursor/ │ └── rules/ │ └── design-system.mdc ├── src/ └── package.json ``` Dentro de `design-system.mdc`, você pode criar uma regra voltada para arquivos de interface: ``` --- description: Regras visuais e Design System do produto globs: - "**/*.tsx" - "**/*.jsx" - "**/*.vue" - "**/*.svelte" - "**/*.astro" - "**/*.css" alwaysApply: false --- Antes de criar ou modificar qualquer interface, consulte @DESIGN.md. Use DESIGN.md como fonte de verdade para: - cores; - tipografia; - espaçamento; - formas; - componentes; - regras de hierarquia visual; - Do's and Don'ts. Não introduza novos estilos quando o DESIGN.md já definir uma solução adequada. Ao concluir uma alteração visual, revise o resultado contra as regras documentadas. ``` O Cursor permite referenciar arquivos dentro de Project Rules usando a sintaxe `@arquivo`. Quando a regra é aplicada, o arquivo referenciado pode entrar como contexto adicional do Agent. ### 2. Defina quando a regra deve entrar no contexto Nem toda tarefa do repositório precisa carregar contexto visual. Uma alteração em banco de dados ou infraestrutura, por exemplo, não precisa consumir DESIGN.md. Já mudanças em componentes React, Vue, CSS ou páginas de interface provavelmente precisam. Por isso, usar regras associadas aos arquivos relevantes pode ser melhor do que transformar DESIGN.md em uma instrução global para todas as tarefas. ### 3. Você também pode anexar DESIGN.md manualmente Em uma tarefa pontual, também é possível fornecer explicitamente o arquivo como contexto durante a conversa com o Cursor. ``` @DESIGN.md Revise este componente e ajuste a interface para seguir o sistema visual documentado, sem alterar a lógica funcional. ``` Essa abordagem é útil quando a tarefa é excepcional e você não quer criar uma regra persistente. ## Claude Code ou Cursor: muda alguma coisa no DESIGN.md? O arquivo não precisa ser reescrito para cada agente. Essa é justamente uma das vantagens de separar identidade visual de configuração operacional. | Claude Code | Cursor | | | --- | --- | --- | | **Fonte visual** | `DESIGN.md` | `DESIGN.md` | | **Configuração do agente** | `CLAUDE.md` | `.cursor/rules/*.mdc` | | **Referência de arquivo** | `@DESIGN.md` | `@DESIGN.md` dentro da rule ou contexto | | **Objetivo** | Carregar regras visuais ao trabalhar em UI | Aplicar regras visuais de forma global ou contextual | Quando a equipe usa vários agentes, manter um único DESIGN.md pode ser mais sustentável do que duplicar as mesmas decisões em diferentes formatos proprietários. ## Como usar DESIGN.md com GitHub Copilot O GitHub Copilot também possui mecanismos de custom instructions por repositório. Entre eles está o arquivo `.github/copilot-instructions.md`, além de instruções específicas por caminho e suporte a arquivos de agente em determinados ambientes. Uma configuração simples pode registrar que DESIGN.md é a fonte visual do projeto: ``` # Interface e Design System Para tarefas relacionadas à interface: - consulte DESIGN.md antes de criar componentes; - preserve os tokens e padrões visuais documentados; - reutilize componentes existentes; - não introduza novas cores, fontes ou espaçamentos sem necessidade; - valide a implementação contra DESIGN.md antes de concluir. ``` O suporte exato a arquivos de instrução pode variar entre Copilot Chat, Copilot CLI, cloud agent e diferentes IDEs. Por isso, consulte a documentação da superfície que sua equipe utiliza em vez de assumir que todas carregam arquivos da mesma forma. ## E no Google Stitch? Google Stitch é um caso diferente porque o DESIGN.md faz parte do próprio ecossistema que originou a especificação aberta. O Stitch possui recursos próprios para trabalhar com as regras de design e exportar o contexto para uso em outros ambientes. Por isso, a integração não precisa ser tratada como uma Project Rule de editor de código. Para esse fluxo, veja o guia específico da CamaraUX sobre [como usar DESIGN.md no Google Stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-google-stitch.md). ## Como usar DESIGN.md com outros agentes Para ferramentas que não possuem integração nativa com DESIGN.md, o padrão continua sendo o mesmo: identificar qual mecanismo oficial a ferramenta usa para fornecer contexto persistente ao agente e fazer esse mecanismo consultar o arquivo. A arquitetura pode ser resumida assim: ``` Instrução do agente ↓ lê DESIGN.md ↓ entende regras ↓ cria ou modifica UI ↓ valida contra DESIGN.md ``` Evite assumir que apenas colocar DESIGN.md na raiz será suficiente em qualquer ferramenta. O comportamento de descoberta e carregamento de arquivos pertence ao agente, não à especificação do DESIGN.md. Quando uma plataforma não documentar leitura automática de arquivos, forneça o DESIGN.md explicitamente ou configure a forma oficial de instruções persistentes daquela ferramenta. ## Um bom DESIGN.md não garante que o agente vá obedecer tudo Arquivos de contexto orientam modelos de linguagem, mas não transformam instruções em regras determinísticas. A própria documentação do Claude Code explica que instruções em CLAUDE.md entram como contexto e que a forma como são escritas influencia a aderência do modelo. Instruções específicas, concisas e sem contradições tendem a funcionar melhor. O mesmo princípio vale para regras visuais. Compare estas instruções: ``` Deixe o card bonito e moderno. ``` com: ``` Use o componente Card documentado em DESIGN.md. Preserve: - Surface definida no sistema; - radius padrão; - escala de espaçamento existente; - hierarquia tipográfica; - estados de foco dos elementos interativos. Não crie uma nova variante visual. ``` A segunda instrução oferece critérios que podem ser comparados com o resultado. ## Como escrever instruções para o agente seguir o DESIGN.md Uma instrução eficaz deve dizer ao agente **quando consultar**, **o que preservar** e **como validar**. Um modelo reutilizável: ``` Antes de executar qualquer tarefa relacionada à interface, consulte DESIGN.md. Considere DESIGN.md a fonte de verdade para decisões visuais. Ao criar ou alterar UI: 1. identifique os componentes e tokens existentes; 2. reutilize padrões antes de criar novos; 3. não invente cores, tipografia, espaçamento ou formas sem necessidade; 4. preserve estados e restrições documentados; 5. adapte responsivamente sem quebrar a linguagem visual; 6. ao terminar, compare a implementação com DESIGN.md e corrija divergências. ``` Isso não precisa estar dentro do próprio DESIGN.md. Pode fazer parte da configuração do agente, mantendo responsabilidades separadas. ## Como validar se a interface gerada seguiu o DESIGN.md Gerar o código é apenas uma etapa. O resultado ainda precisa ser revisado. Depois da geração, peça ao agente para comparar a implementação com a fonte visual: ``` Audite a interface que você acabou de gerar contra DESIGN.md. Liste qualquer divergência relacionada a: - cores; - tipografia; - espaçamento; - radius; - componentes; - estados interativos; - responsividade; - acessibilidade; - Do's and Don'ts. Corrija somente as divergências encontradas e preserve a lógica funcional existente. ``` Depois, faça também revisão humana. O agente consegue verificar consistência com regras documentadas, mas isso não substitui julgamento de UX, avaliação de acessibilidade ou validação com usuários. ## Erros comuns ao usar DESIGN.md com agentes de IA ### Achar que todo agente lê DESIGN.md automaticamente DESIGN.md é um formato de contexto visual. O mecanismo que carrega esse arquivo depende da ferramenta. Configure o agente explicitamente quando necessário. ### Duplicar todas as regras em vários arquivos Copiar cores e componentes para DESIGN.md, CLAUDE.md e regras do Cursor cria diferentes fontes de verdade. Prefira referências entre os arquivos. ### Usar regras antigas do Cursor como recomendação principal O arquivo `.cursorrules` ainda aparece em muitos tutoriais, mas a documentação atual do Cursor o classifica como legado. Para novos projetos, use Project Rules em `.cursor/rules`. ### Criar instruções contraditórias Se DESIGN.md diz que o botão primário usa um determinado padrão e outra regra do agente manda usar outro, o modelo recebe informações conflitantes. Revise periodicamente os arquivos de contexto do projeto e remova instruções antigas. ### Carregar contexto visual em toda tarefa Em projetos grandes, contexto também possui custo. Nem uma migração de banco nem uma alteração de API precisam necessariamente carregar toda a documentação visual. Quando a ferramenta permitir, aplique as regras de design apenas a tarefas e arquivos relacionados à interface. ### Não revisar o resultado Um arquivo bem escrito melhora contexto, mas não transforma geração probabilística em execução determinística. Sempre confira a implementação produzida. ## Arquitetura recomendada para projetos que usam vários agentes Se o mesmo repositório é utilizado por Claude Code, Cursor, Copilot ou outros agentes, uma arquitetura simples evita duplicação: ``` meu-projeto/ ├── DESIGN.md ├── CLAUDE.md ├── AGENTS.md ├── .cursor/ │ └── rules/ │ └── design-system.mdc ├── .github/ │ └── copilot-instructions.md ├── src/ └── package.json ``` O princípio é: - `DESIGN.md` mantém a identidade visual; - cada arquivo de agente mantém suas instruções operacionais; - as configurações apontam para a mesma fonte visual; - as decisões não precisam ser copiadas manualmente entre ferramentas. Isso também torna a manutenção mais simples quando o produto evolui. ## DESIGN.md melhora a UI gerada por IA, mas não substitui UX Um agente pode receber informações precisas sobre a aparência de um botão sem saber se aquele botão deveria existir naquele momento da jornada. DESIGN.md resolve principalmente consistência e contexto visual. Ele não determina sozinho se a arquitetura da informação está adequada, se o fluxo faz sentido, se a interação atende ao modelo mental do usuário ou se a solução resolve o problema correto. Esse é o ponto de encontro entre [IA no processo de design](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/inteligencia-artificial-para-designers.md), [Fundamentos de UX](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/fundamentos-de-ux.md) e um [Design System estruturado](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-system-guia-escalabilidade-roi.md). O agente executa melhor quando recebe contexto melhor. A qualidade da decisão ainda depende de quem define esse contexto. ## Referências oficiais As configurações deste guia foram baseadas nas documentações atuais das próprias ferramentas e na especificação aberta do DESIGN.md: - [Google Labs: especificação oficial do DESIGN.md](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md) - [Anthropic: CLAUDE.md, memória e imports no Claude Code](https://code.claude.com/docs/en/memory) - [Cursor: Project Rules](https://docs.cursor.com/context/rules) - [GitHub: custom instructions para Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions-in-your-ide/add-repository-instructions-in-your-ide) ## Conclusão: mantenha uma fonte visual e adapte a conexão ao agente Você não precisa criar um design system diferente para Claude Code, outro para Cursor e outro para cada nova ferramenta que surgir. Mantenha o DESIGN.md como uma fonte compartilhada de contexto visual e use o mecanismo oficial de cada agente para conectá-lo ao fluxo de trabalho. No Claude Code, isso pode ser feito por meio do CLAUDE.md e seus imports. No Cursor, Project Rules permitem aplicar o contexto visual aos arquivos relevantes. Em outros ambientes, procure o mecanismo equivalente de instruções de repositório ou fornecimento explícito de contexto. Se você ainda precisa montar a fonte visual, siga o guia [como criar um DESIGN.md](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/como-criar-aplicar-design-md-ia.md). Se prefere começar de uma referência pronta, explore a [biblioteca de DESIGN.md da CamaraUX](https://camaraux.com.br/design-md/). Para o fluxo específico do Google, veja também [como usar DESIGN.md com Google Stitch](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/post/design-md-google-stitch.md). ### Claude Code lê DESIGN.md automaticamente? Claude Code documenta CLAUDE.md como mecanismo de instruções persistentes do projeto. Para usar DESIGN.md de forma previsível, você pode importá-lo no CLAUDE.md com a sintaxe @DESIGN.md, fazendo com que o arquivo entre no contexto junto das instruções do projeto. ### Como usar DESIGN.md no Cursor? A abordagem atual recomendada pelo Cursor é usar Project Rules em .cursor/rules. Uma regra pode ser aplicada aos arquivos de interface e referenciar DESIGN.md como contexto para geração ou alteração de componentes visuais. ### Ainda devo usar .cursorrules? Para novos projetos, prefira Project Rules em .cursor/rules. A documentação atual do Cursor classifica .cursorrules como um mecanismo legado, embora ainda exista compatibilidade. ### DESIGN.md substitui CLAUDE.md ou AGENTS.md? Não. DESIGN.md documenta principalmente a linguagem visual e o design system. CLAUDE.md, AGENTS.md e arquivos de rules servem para orientar o comportamento do agente dentro do projeto. Eles podem referenciar o mesmo DESIGN.md sem duplicar suas regras. ### O mesmo DESIGN.md pode ser usado com vários agentes? Sim. A proposta do formato é permitir que a mesma fonte textual de contexto visual possa ser utilizada entre diferentes agentes e ferramentas. O que muda é a forma como cada ambiente carrega ou referencia esse arquivo. ## Topics **Categorias:** [UX & IA](https://camaraux.com.br/wp-content/uploads/wp-mfa-exports/taxonomy/category/ux-e-ia.md)