DESIGN.md: o arquivo que vem depois do AGENTS.md

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

O DESIGN.md é um ficheiro Markdown na raiz do seu 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, incluindo o comando de compilação, o comando de testes, o lint 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, ou seja, uma ferramenta como Claude Code ou Cursor que lê e edita o seu repositório de forma autónoma, parte de uma posição de confiança. Encontra um padrão que não reconhece e melhora-o. Uma cache escrita manualmente passa a usar Redis (um armazenamento de dados em memória), porque é assim que uma cache aparece na maioria do código que o modelo leu. O AGENTS.md não impede isto, porque make test passa em ambos os casos. A regra violada nunca foi registada 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 está ao lado dele explica o formato e onde cada ferramenta o procura. O que se segue é o capítulo posterior a esse.

O que há realmente num DESIGN.md publicado

A forma mais rápida de aprender o formato é ler os ficheiros que as empresas publicam sobre si próprias. O repositório official-design-md acompanha apenas esses ficheiros. 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 agosto de 2026, a lista inclui sete: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel e VoltAgent. Cada ficheiro está num URL público estável, por isso pode ler um deles já a partir de 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 sistemas de design. Descrevem o aspeto que um produto deve ter: cor, tipografia, espaçamento e movimento. Ignore o tema específico, porque a parte útil está na estrutura do texto, não no assunto.

O ficheiro do Nuxt tem cerca de 2,100 palavras, e a maior parte consiste numa regra acompanhada da respetiva razão:

Dark mode is the default theme.
Colors are semantic (`primary`, `neutral`, `error`…) rather than hardcoded hex values in components.
Don't hardcode `#00DC82` in UI code — use `text-primary` or `color="primary"`.

O ficheiro da Vercel é mais longo, com cerca de 6,500 palavras em agosto de 2026, e vai um passo mais longe. Um dos seus títulos é Reject generated-design reflexes. Abaixo dele há uma lista daquilo a que um gerador competente recorre quando ninguém lhe diz para não o fazer:

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 ficheiro. É uma lista escrita dos valores predefinidos que um modelo confiante produz, publicada para fazer com que o modelo deixe de os produzir. Todo DESIGN.md que valha a pena versionar é essa lista para um determinado domínio.

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

A comunidade chegou primeiro. awesome-design-md reúne 73 ficheiros obtidos por engenharia reversa de sites públicos. Cada ficheiro segue o mesmo formato de nove secções. Assim, é possível indicar um deles a um agente para produzir algo semelhante àquele visual. Esses ficheiros são úteis, mas continuam a ser suposições. Ninguém nas empresas os reviu.

Um ficheiro publicado pela 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 é alterado. Uma cópia recolhida em março continua a ensinar a escala antiga ao seu agente, e nada no seu repositório indicará que a cópia ficou desatualizada.

Sete empresas é um número pequeno, e o repositório reconhece isso: o padrão é recente e a adoção oficial está a crescer. As duas coleções são mantidas pela VoltAgent, um framework open source para agentes que também publica o seu próprio ficheiro. Por isso, interprete a lista como um acompanhamento, e não como um recenseamento neutro. Ainda assim, vale a pena acompanhá-la por causa das sete empresas incluídas. São as empresas cujo código front-end é mais frequentemente copiado por outros programadores, e os seus ficheiros estão a tornar-se o exemplo prático do que é um DESIGN.md. Compare o percurso do AGENTS.md: agents.md já contabiliza mais de 60,000 projetos open source que usam o formato, e a gestão está a cargo da Agentic AI Foundation, sob a Linux Foundation. As convenções para ficheiros legíveis por agentes estão a consolidar-se rapidamente, e estão a consolidar-se de cima para baixo.

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

A maior parte do software executado num VPS não tem uma linguagem visual a especificar. Ainda assim, o ficheiro justifica-se, porque o mecanismo não tem relação com cores. Trata-se de documentar as restrições que um editor confiante violaria sem se aperceber.

Invariantes. Uma frase para cada uma, indicando algo que tem de continuar verdadeiro depois de qualquer edição. "Cada escrita passa por queue.enqueue(). Uma escrita direta na base de dados ignora o registo de auditoria, e é esse registo que a exportação de conformidade lê." Um invariante acompanhado do respetivo motivo mantém-se válido perante uma tarefa que nunca 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 o motivo pelo 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ções." Sem esse parágrafo, um agente a quem seja pedido para acelerar a cache adiciona Redis, e tem razão para o fazer: nunca lhe indicou a restrição. Esta é a secção que justifica todo o ficheiro.

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

Vocabulário. Se o código diz tenant e a equipa diz customer, documente a correspondência. 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 hoje as duas secções que consegue escrever de memória: invariantes e alternativas rejeitadas. Deixe o resto apenas como títulos. Um ficheiro com quatro linhas honestas é útil. Um ficheiro com quarenta linhas inventadas 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 usada 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 for indicado. Não assuma um comportamento específico. 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 incorreta mais comum é fácil de ler 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 foram feitas dessa forma.

Isso tem dois custos. O primeiro é 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 é apenas sobrecarga dentro de uma janela fixa. Gerir essa janela é uma competência própria, abordada em gerir a janela de contexto no Claude Code. Em resumo: 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 acabam por divergir. O README diz que o serviço escuta na porta 8080, o DESIGN.md ainda diz 3000, e o agente não tem como determinar qual deve prevalecer. Por isso, escolhe uma e escreve 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 estar confortavelmente no README, remova-o do DESIGN.md. O que ficar 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. Existe uma verificação que pode executar num minuto.

Dê ao agente uma tarefa que vá diretamente contra uma invariável. "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 indicar 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 diretamente, uma de duas coisas é verdadeira. O ficheiro não está a ser lido ou a invariável está descrita de forma suficientemente vaga para permitir discussão.

Observe também a contagem de tokens, porque este ficheiro é carregado em cada turno. 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á conhecia. Como ler os contadores de tokens no Claude Code mostra onde esse orçamento é usado.

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 a configuração descrita em um workspace do Claude Code numa VPS com tmux, não tem memória da conversa de ontem. O repositório é a memória. Tudo o que explicou no chat e nunca submeteu 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 é uma invariante que nunca foi registada. Também é 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 consigo, não segundo um calendário. Se ainda está a tentar perceber onde os agentes se enquadram num fluxo de trabalho 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 um site próprio em agents.md, é utilizado por mais de 60,000 projetos open source e é mantido pela Agentic AI Foundation, uma entidade da Linux Foundation. Em agosto de 2026, o DESIGN.md não tem uma entidade responsável nem uma especificação publicada. O que existe é adoção pelos próprios fornecedores: sete empresas, incluindo Vercel, Nuxt, Atlassian e Resend, publicam um ficheiro num URL público, e uma coleção da comunidade reúne mais 73 ficheiros obtidos por engenharia reversa a partir de sites públicos. Trate-o como uma convenção que pode adotar agora e ampliar livremente, porque nada valida os nomes das secções.

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

Para um repositório pequeno, sim. Um ficheiro que o agente lê com certeza é melhor do que dois ficheiros, quando um deles pode ser ignorado. Separe-os quando o AGENTS.md deixar de ser fácil de consultar ou quando verificar que as duas partes mudam a ritmos diferentes. O AGENTS.md muda quando o processo de compilação muda. O DESIGN.md muda quando uma decisão muda, o que acontece com menos frequência e tem mais impacto. Ao separar os ficheiros, adicione uma linha ao AGENTS.md a indicar ao agente que deve ler o DESIGN.md antes de editar código, porque nem todas as ferramentas carregam todos os ficheiros markdown na raiz.

Em que difere o DESIGN.md de um architecture decision record?

Um ADR (architecture decision record) é um registo datado de uma decisão e um projeto saudável acumula dezenas deles numa pasta. Isso é um histórico, e carregar um histórico tem um custo elevado, porque o agente teria de ler todos os registos para determinar quais continuam válidos. O DESIGN.md representa o estado atual e foi escrito para ser lido na íntegra em todas as tarefas. Mantenha ambos se já escreve ADRs. O ADR indica o que foi decidido e quando. O DESIGN.md indica o que é verdade hoje e é o ficheiro que deve indicar ao agente.

Qual deve ser o tamanho de um DESIGN.md?

Deve ser suficientemente curto para ser carregado em cada interação sem causar problemas. Os exemplos publicados são longos porque especificam uma linguagem visual completa: em agosto de 2026, o ficheiro do Nuxt tem cerca de 2,100 palavras e o ficheiro da Vercel cerca de 6,500. Um serviço backend normalmente precisa de muito menos. Comece com uma página e aumente o ficheiro 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, de outro modo, o agente faria incorretamente.