DESIGN.md: por que o código tem essa estrutura

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

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 tem a estrutura atual. O AGENTS.md responde a uma pergunta diferente: como trabalhar neste repositório. Isso inclui o comando de compilação, o comando de testes, a análise estática que tem de passar e os caminhos que não devem ser alterados. O DESIGN.md regista as decisões já consolidadas 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 transforma-se em 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 funciona nos dois casos. A regra violada nunca foi escrita num local que o agente pudesse ler.

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

O que existe de facto dentro de um 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 empresas: Atlassian, Clerk, Mintlify, Nuxt, Resend, Vercel e VoltAgent. Cada ficheiro está num URL público estável, por isso pode ler um deles agora num 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 e concentre-se na estrutura do texto, porque é aí que está a parte útil.

O ficheiro do Nuxt tem cerca de 2.100 palavras, e a maior parte consiste numa regra acompanhada da respetiva justificaçã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 além. Um dos seus títulos é Reject generated-design reflexes. Abaixo dele aparece 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 padrões predefinidos que um modelo confiante produz, publicada para que o modelo deixe de os produzir. Todo o 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 73 ficheiros obtidos por engenharia reversa a partir de sites públicos. Cada ficheiro segue o mesmo formato de nove secções, para que um agente possa receber um deles e produzir algo semelhante àquela aparência. 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 ao seu agente a escala antiga, e nada no seu repositório indicará que a cópia ficou desatualizada.

Sete publicadores é um número reduzido, 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, leia a lista como um acompanhamento, e não como um recenseamento neutro. Ainda assim, vale a pena observá-la por causa de quem são esses sete. 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 administraçã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 a partir do topo.

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 para especificar. Ainda assim, o ficheiro é útil, porque o mecanismo não tem qualquer relação com cores. O objetivo é registar as restrições que um editor confiante violaria sem se aperceber.

Invariantes. Uma frase por cada uma, indicando algo que tem de continuar verdadeiro depois de qualquer alteração. "Todas as escritas passam por queue.enqueue(). Uma escrita direta na base de dados ignora o registo de auditoria, que é a fonte usada pela exportação de conformidade." Uma invariante acompanhada da respetiva razão mantém-se válida mesmo perante uma tarefa que não tenha sido prevista. Uma invariante isolada 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ções." Sem esse parágrafo, um agente a quem seja pedido para acelerar o cache adiciona Redis, e tem razão para o fazer: a restrição nunca lhe foi indicada. Esta é a secção que justifica todo o ficheiro.

Limites. Os pontos onde uma pequena alteração pode ter um impacto muito amplo. O esquema da base de dados. O prefixo da rota pública que os clientes já utilizam em scripts. O ficheiro de configuração que uma implementação lê antes de iniciar a aplicação. 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.

Vocabulário. Se o código usa tenant e a equipa usa customer, registe 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 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 funciona. Um ficheiro com quarenta linhas inventadas não funciona.

Algumas ferramentas carregam todos os ficheiros Markdown na raiz do repositório. Outras carregam apenas o ficheiro que lhes é 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 lê-se bem 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 motivo as decisões foram tomadas.

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 ocupa espaço sem trazer valor num contexto de tamanho fixo. Gerir esse espaço é uma competência própria, abordada em gerir a janela de contexto no Claude Code. A versão curta é esta: 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, mas o DESIGN.md continua a indicar 3000. O agente não tem forma de determinar qual das duas informações deve prevalecer, por isso escolhe uma e escreve o código com base nela. Um ficheiro que está errado algumas vezes é consultado com a mesma confiança que um ficheiro que está sempre correto.

O teste é rápido. Se um parágrafo pudesse estar 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. Existe uma verificação que pode executar num minuto.

Dê ao agente uma tarefa que conduza 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.

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

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 espaço de trabalho do Claude Code numa 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 um invariante que nunca foi documentado e um ponto em que um agente cometerá o mesmo erro, de forma mais rápida e frequente do que uma pessoa. Atualize o ficheiro quando ele falhar consigo, não segundo um calendário. Se ainda está a perceber como integrar agentes num fluxo de desenvolvimento normal, o guia de 2026 para aprender a utilizar agentes de IA é um próximo passo razoável.

FAQ

O DESIGN.md é um padrão oficial?

Não da mesma forma que AGENTS.md. O AGENTS.md tem um site em agents.md, é utilizado por mais de 60,000 projetos de código aberto e é mantido pela Agentic AI Foundation, parte da Linux Foundation. Em agosto de 2026, o DESIGN.md não tem uma entidade responsável nem uma especificação publicada. O que tem é adoção pelos próprios fornecedores: sete empresas, incluindo Vercel, Nuxt, Atlassian e Resend, publicam um ficheiro deste tipo num URL público, e uma coleção da comunidade reúne mais 73, obtidos por engenharia reversa a partir de sites públicos. Trate-o como uma convenção que pode adotar desde já e expandir livremente, porque nada valida os nomes das secções.

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

Num repositório pequeno, sim. Um ficheiro que o agente lê certamente é 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 notar que as duas partes mudam a ritmos diferentes. O AGENTS.md muda quando a compilação muda. O DESIGN.md muda quando uma decisão muda, o que acontece com menos frequência e tem mais impacto. Ao separá-los, adicione uma linha ao AGENTS.md a indicar ao agente que deve ler o DESIGN.md antes de editar o código, porque nem todas as ferramentas carregam todos os ficheiros markdown na raiz.

Em que difere o DESIGN.md de um registo de decisão de arquitetura?

Um ADR (registo de decisão de arquitetura) é o 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 é dispendioso, porque um agente teria de ler todos os registos para determinar quais continuam válidos. O DESIGN.md representa o estado atual e é escrito para ser lido integralmente 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 é válido 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 todas as interações sem pesar. Os exemplos publicados são longos porque especificam uma linguagem visual completa: em agosto de 2026, o ficheiro da Nuxt tinha cerca de 2,100 palavras e o 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 fizer algo errado 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.