Como usar o arquivo DESIGN.md para agentes de IA

O que é o DESIGN.md e o que o AGENTS.md não abrange

O DESIGN.md é um ficheiro Markdown na raiz do repositório que explica a um agente de programação com IA por que motivo o código está estruturado dessa forma. O AGENTS.md responde a uma pergunta diferente: como trabalhar neste repositório. Isso inclui o comando de compilação, o comando de teste, o linter que tem de passar e os caminhos que não devem ser alterados. O DESIGN.md regista as decisões já estabelecidas e o que deixa de funcionar quando uma delas é revertida.

Um agente de programação, isto é, uma ferramenta como Claude Code ou Cursor que lê e edita o repositório autonomamente, parte do princípio de que pode tomar decisões. Quando encontra um padrão que não reconhece, melhora esse padrão. Uma cache implementada manualmente passa a usar Redis (um armazenamento de dados em memória), porque é assim que uma cache aparece na maior parte do código que o modelo leu. O AGENTS.md não impede esta alteração, porque make test passa em ambos os casos. A regra que foi violada nunca tinha sido documentada num local que o agente pudesse consultar.

Se ainda não escreveu o primeiro ficheiro, comece por aí. O AGENTS.md e o HUMAN.md que fica ao lado explica o formato e onde cada ferramenta o procura. O que se segue é o capítulo posterior a esse.

O que há de fato dentro de um DESIGN.md publicado

A maneira mais rápida de aprender o formato é ler os arquivos que as empresas publicam sobre si mesmas. O repositório official-design-md acompanha apenas esses arquivos. A regra de inclusão tem uma linha, e essa linha é o objetivo de toda a coleção:

Every entry here is a DESIGN.md published by the company or project itself — not extracted, not reverse-engineered, not community-made.

Em outubro de 2026, ele lista onze: Ant Design, Atlassian, Clerk, Juspay, Microsoft FAST, Mintlify, Nuxt, Oxide Computer, Resend, Vercel e VoltAgent. Cada arquivo está em uma URL pública, a maioria no domínio da própria empresa e os demais em um repositório público do GitHub, portanto você pode ler um deles agora mesmo em um terminal.

curl -s https://nuxt.com/design.md | head -n 60
curl -s https://vercel.com/design.md | wc -w

Ambos são documentos de sistema de design. Eles descrevem como um produto deve ser: cor, tipografia, espaçamento e movimento. Vá além do assunto, porque a parte útil é a estrutura do texto, não o tema.

O arquivo do Nuxt tem aproximadamente 2.000 palavras em 27 de outubro de 2026, e a maior parte dele é uma regra acompanhada do seu motivo. Ele começa afirmando que o modo escuro é o tema padrão. Lista o verde da marca #00DC82 com uma observação de que as cores da marca são "Para logotipos, imagens para redes sociais e impressão. Não as use como valores brutos no código da interface." Perto do fim, uma seção intitulada Reject these inclui:

Raw hex values or palette classes (`text-gray-500`) in components instead of semantic tokens.

O arquivo da Vercel é mais longo, com aproximadamente 6.000 palavras em outubro de 2026, e vai um passo além. Um dos títulos é Reject generated-design reflexes. Abaixo dele há uma lista do que um gerador competente escolhe quando ninguém diz para não fazer isso:

Hard reject decorative gradients, gradient text, glows, blobs, stripes, textures, grid backgrounds, glass effects, paper simulations, colored side rails, ornamental shadows, and fake depth.

Essa frase define o tipo de arquivo. É uma lista escrita dos padrões que um modelo confiante produz, publicada para fazer o modelo parar de produzi-los. Todo DESIGN.md que vale a pena versionar é essa lista para algum domínio.

Por que as empresas publicam o seu próprio DESIGN.md?

A comunidade chegou primeiro. awesome-design-md reúne 84 ficheiros extraídos de sites públicos, segundo a contagem do seu README em 27 de outubro de 2026. Cada ficheiro segue o mesmo formato de nove secções, para que um agente possa receber um deles como referência e produzir algo próximo desse aspeto. Esses ficheiros são úteis, mas continuam a ser suposições. Ninguém nas empresas analisadas os reviu.

Um ficheiro da própria empresa é diferente porque é a fonte, e não uma interpretação do resultado. Quando a Vercel altera a sua escala tipográfica, vercel.com/design.md também muda. Uma cópia extraída em março continua a ensinar ao agente a escala antiga, e nada no seu repositório indica que a cópia ficou desatualizada.

Onze empresas ainda são poucas, e o repositório reconhece isso: o standard é recente e a adoção oficial está a crescer. Ambas as coleções são mantidas pela VoltAgent, um framework de agentes open source que também publica o seu próprio ficheiro. Por isso, leia a lista como um tracker, e não como um recenseamento neutro. Ainda vale a pena acompanhá-la, pelo tipo de empresas incluídas. Várias são as empresas cujo código front-end é mais copiado por outros programadores. As entradas mais recentes, Ant Design, Microsoft FAST, Juspay e Oxide Computer, são design systems sobre os quais outras equipas desenvolvem. Os seus ficheiros estão a tornar-se o exemplo concreto do que é um DESIGN.md. Compare o percurso de AGENTS.md: agents.md já regista mais de 60,000 projetos open source que usam o formato, e a responsabilidade está com a Agentic AI Foundation, sob a Linux Foundation. O DESIGN.md começou a seguir o mesmo caminho. Em 21 de abril de 2026, a Google disponibilizou uma draft specification open source para o formato, publicada como google-labs-code/design.md, com um token schema e uma CLI sob a licença Apache-2.0. Em outubro de 2026, o formato está na versão alpha e continua em desenvolvimento ativo. É mantido pela Google Labs, e não por uma foundation neutra. Também descreve uma identidade visual, por isso não diz nada sobre os invariantes necessários num ficheiro de backend. As convenções para ficheiros legíveis por agentes estão a consolidar-se rapidamente, e estão a consolidar-se a partir do topo.

O que incluir num DESIGN.md quando o projeto não tem interface de utilizador

A maioria do software executado num VPS não tem uma linguagem visual para especificar. Mesmo assim, o ficheiro continua a ser útil, porque o mecanismo não tem relação com cores. Trata-se de registar as restrições que um editor experiente violaria sem se aperceber.

Invariantes. Uma frase por item, indicando algo que tem de continuar verdadeiro depois de qualquer edição. "Todas as escritas passam por queue.enqueue(). Uma escrita direta na base de dados ignora o log de auditoria, que é a fonte usada pela exportação de conformidade." Um invariante acompanhado da respetiva razão continua válido mesmo perante uma tarefa que não tinha sido prevista. Um invariante isolado parece uma preferência, e as preferências acabam por ser eliminadas durante a otimização.

Alternativas rejeitadas. A opção óbvia e a razão pela qual foi rejeitada. "Não usamos Redis para caching. O serviço é executado num único VPS, por isso um mapa no processo é mais rápido e há menos um daemon para manter ativo. Reavalie esta decisão quando existir um segundo servidor de aplicação." Sem esse parágrafo, um agente a quem seja pedido para acelerar a cache adiciona Redis, e faz bem em fazê-lo: nunca lhe comunicou a restrição. Esta é a secção que justifica todo o ficheiro.

Limites. Os pontos onde uma pequena edição pode ter um impacto amplo. O schema da base de dados. O prefixo das rotas públicas contra o qual os clientes já executam scripts. O ficheiro de configuração que um deploy lê antes de a aplicação arrancar. A entrada do cron que pressupõe a execução de apenas uma cópia. Identifique-os e indique o custo de alterar cada um. Se o agente também puder aceder à web aberta, por exemplo através de uma instância SearXNG self-hosted configurada como backend de pesquisa, esse também é um limite que vale a pena registar, porque o ficheiro deve indicar que texto obtido pode influenciar o código e que texto deve ser apenas citado de volta.

Vocabulário. Se o código diz tenant e a equipa diz customer, registe o mapeamento. Um agente que faça uma suposição errada neste ponto produz código que parece correto e representa o conceito errado. Este é o tipo de erro mais difícil de detetar numa revisão.

Um DESIGN.md que pode copiar hoje

# DESIGN.md

## What this service is
One paragraph. What it does, who calls it, where it runs.

## Invariants
- Every write goes through `queue.enqueue()`. Direct writes skip the audit log.
- Timestamps are stored as UTC integers. Only the display layer converts them.
- One process writes to SQLite. The database is in WAL mode, and a second writer
  gets `database is locked` under load.

## Rejected alternatives
- **Redis for caching.** Rejected: one VPS, one process, an in-process map is
  enough. Revisit at two application servers.
- **An ORM for the reporting queries.** Rejected: the reports are four hand-tuned
  SQL statements. The generated query joined the same table twice.

## Boundaries
- `schema.sql` is append-only. A column rename needs a migration and a deploy window.
- The `/v1/` routes are public. Customers script against them, so the response
  shape is frozen.

## Vocabulary
- `tenant` in code is what the docs and the billing system call a customer account.

## Keeping this file honest
Update it in the commit that changes the decision. A stale DESIGN.md is worse
than no DESIGN.md, because the agent believes it.

Preencha as duas secções que consegue escrever hoje de memória: invariantes e alternativas rejeitadas. Deixe o restante apenas como títulos. Um ficheiro com quatro linhas honestas é útil. Um ficheiro com quarenta linhas baseadas em suposições não é. Se o repositório contiver vários pacotes, um único ficheiro na raiz não servirá para todos. Nesse caso, aplique a mesma divisão por diretórios que funciona para ficheiros AGENTS.md aninhados num monorepo: um ficheiro curto na raiz para as decisões partilhadas por tudo e um ficheiro menor junto de cada pacote que tenha decisões próprias.

Algumas ferramentas carregam todos os ficheiros markdown na raiz do repositório. Outras carregam apenas o ficheiro que lhes é indicado. Não parta do princípio de que o comportamento é sempre o mesmo. Adicione uma referência a AGENTS.md:

Read DESIGN.md before editing anything under `src/`. It lists the invariants and
the alternatives that were already rejected.

O antipadrão: um DESIGN.md que repete o README

A versão inadequada mais comum é bem escrita e não ensina nada. Começa por explicar o que o projeto faz, lista as funcionalidades, explica como o instalar e termina com a licença. Tudo isso já está no README, e nada explica por que razão as coisas são como são.

Isso tem um custo duplo. O primeiro custo é o contexto. Um ficheiro que o agente lê no início de cada tarefa é contabilizado em todas as tarefas, e uma secção de instalação duplicada é pura sobrecarga num intervalo fixo. Gerir esse intervalo é uma competência própria, abordada em gerir a janela de contexto no Claude Code. A versão curta: tudo o que é carregado automaticamente deve ser o texto de maior valor no repositório.

O segundo custo é pior. Duas cópias da mesma afirmação divergem. O README diz que o serviço escuta na porta 8080, o DESIGN.md ainda diz 3000, e o agente não tem forma de determinar qual deve prevalecer. Por isso, escolhe uma e escreve o código com base nela. Um ficheiro que por vezes está errado é consultado com a mesma confiança que um ficheiro que está sempre certo.

O teste é rápido. Se um parágrafo pudesse aparecer confortavelmente no README, remova-o do DESIGN.md. O que restar deve ser a parte que diria em voz alta numa revisão de código, a parte que começa por "já tentámos isso".

Como saber se o ficheiro está a funcionar?

Não existe um linter para isto. Há uma verificação que pode executar num minuto.

Dê ao agente uma tarefa que o leve diretamente a uma invariante. "Adicione um trabalho em segundo plano que marque as linhas obsoletas como expiradas." Um ficheiro que está a cumprir a sua função aparece na resposta antes de qualquer código: o agente deve dizer que o trabalho escreve através de queue.enqueue(), porque uma escrita direta ignoraria o log de auditoria. Se abrir uma ligação à base de dados e escrever, uma de duas coisas é verdade. O ficheiro não está a ser lido, ou a invariante está formulada de forma suficientemente vaga para permitir discussão.

Observe também a contagem de tokens, porque este ficheiro é carregado em todas as interações. Se o uso de contexto aumentar depois de adicionar DESIGN.md e as respostas não melhorarem, o ficheiro contém prosa que o agente já tinha. Consultar os contadores de tokens no Claude Code mostra para onde vai esse orçamento.

Isto é mais importante quando o agente está num servidor, e não no seu portátil. Um agente que trabalha numa sessão de longa duração, como na configuração descrita em um espaço de trabalho do Claude Code num VPS com tmux, não tem memória da conversa do dia anterior. O repositório é a memória. Tudo o que explicou no chat e nunca confirmou no repositório desaparece na sessão seguinte, e é no DESIGN.md que essa explicação deve ficar para sobreviver.

Comece pelas decisões que geram discussões

A primeira versão demora vinte minutos. Abra os últimos pull requests em que um revisor escreveu "não, aqui fazemos de outra forma". Cada um desses comentários representa uma invariável que nunca foi documentada e um ponto em que um agente cometerá o mesmo erro, mais depressa e com mais frequência do que uma pessoa. Atualize o ficheiro quando ele falhar, não segundo um calendário. Se ainda estiver a determinar como integrar agentes num fluxo de desenvolvimento normal, o guia de 2026 para aprender a trabalhar com agentes de IA é um próximo passo razoável.

FAQ

O DESIGN.md é um padrão oficial?

Não da mesma forma que o AGENTS.md. O AGENTS.md tem uma página em agents.md, é usado por mais de 60,000 projetos open source e tem supervisão da Agentic AI Foundation, parte da Linux Foundation. O DESIGN.md tem uma especificação publicada, mas não tem uma entidade neutra responsável por mantê-lo. O Google publicou uma especificação preliminar como open source em April 21, 2026, e ela está no repositório google-labs-code/design.md sob a licença Apache-2.0. Em October 2026, ele está na versão alpha e ainda em desenvolvimento ativo, e descreve uma identidade visual: cores, tipografia, layout e componentes. O DESIGN.md também tem adoção por empresas e projetos: onze empresas e projetos, incluindo Vercel, Nuxt, Atlassian e Resend, publicam um, e uma coleção da comunidade reunia mais 84 extraídos de sites públicos em October 27, 2026. Para um arquivo de backend com invariantes e alternativas rejeitadas, trate-o como uma convenção que você pode adotar agora e ampliar livremente, porque nenhuma especificação cobre esses nomes de seção.

O DESIGN.md deve ser apenas uma seção do AGENTS.md?

Para um repositório pequeno, sim. Um único arquivo que o agente certamente lê é melhor que dois arquivos, dos quais um pode ser ignorado. Separe-os quando o AGENTS.md deixar de ser fácil de consultar ou quando você perceber que as duas partes estão mudando em ritmos diferentes. O AGENTS.md muda quando o build muda. O DESIGN.md muda quando uma decisão muda, o que é menos frequente e tem mais impacto. Ao separá-los, adicione uma linha ao AGENTS.md informando ao agente que deve ler o DESIGN.md antes de editar o código, porque nem toda ferramenta carrega todos os arquivos markdown na raiz.

Qual é a diferença entre o DESIGN.md e um registro de decisão de arquitetura?

Um ADR (architecture decision record) é um registro datado de uma decisão, e um projeto saudável acumula dezenas deles em um diretório. Isso é um histórico, e carregar o histórico é custoso, pois um agente teria de ler todos os registros para descobrir quais ainda são válidos. O DESIGN.md representa o estado atual e foi escrito para ser lido por completo em cada tarefa. Mantenha ambos se você já escreve ADRs. O ADR informa o que foi decidido e quando. O DESIGN.md informa o que é verdade hoje, e é para ele que você deve direcionar o agente.

Qual deve ser o tamanho de um DESIGN.md?

Curto o suficiente para ser carregado em cada turno sem arrependimento. Os exemplos publicados são longos porque especificam uma linguagem visual completa: o arquivo do Nuxt tem aproximadamente 2,000 palavras e o arquivo da Vercel aproximadamente 6,000 em October 2026. Um serviço de backend normalmente precisa de muito menos. Comece com uma página e aumente o arquivo apenas quando um agente cometer um erro que uma única frase teria evitado. O tamanho não é o critério. Cada linha deve descrever algo que o agente erraria de outra forma.