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

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

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. AGENTS.md responde a uma pergunta diferente: como trabalhar neste repositório. Isso inclui o comando de compilação, o comando de testes, o linter que tem de passar e os caminhos que não devem ser alterados. 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. Quando encontra um padrão que não reconhece, 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. AGENTS.md não impede isto, porque make test funciona nos dois casos. A regra violada nunca foi registada num local que o agente pudesse ler.

Se ainda não escreveu o primeiro ficheiro, comece por aí. 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 seguinte.

O que há realmente 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 cabe numa 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 mesmo 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 específico, porque o que interessa é a estrutura do texto, não o assunto.

O ficheiro do Nuxt tem aproximadamente 2,100 palavras, e a maior parte do conteúdo é uma 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 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 impedir que o modelo continue a produzi-los. Qualquer DESIGN.md que valha a pena versionar é essa lista aplicada a 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 a partir de sites públicos. Cada ficheiro segue o mesmo formato de nove secções. Assim, um agente pode receber um deles e produzir algo próximo desse aspeto. Esses ficheiros são úteis, mas continuam a ser suposições. Ninguém nas empresas os reviu.

Um ficheiro de primeira parte é 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 é atualizado. Uma cópia recolhida em março continua a ensinar ao seu agente a escala antiga. 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, uma 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 levantamento neutro. Ainda assim, vale a pena acompanhá-la por causa de quem são esses sete publicadores. São as empresas cujo código front-end é mais 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 contabiliza agora 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 a partir do topo.

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

Invariantes. Escreva uma frase para cada uma, 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 origem dos dados lidos pela exportação de conformidade." Uma invariante acompanhada da respetiva razão resiste a uma tarefa que nunca tinha previsto. Uma invariante isolada parece uma preferência, e as preferências acabam por ser removidas durante a otimização.

Alternativas rejeitadas. Indique a opção óbvia e explique por que motivo 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 faz bem em fazê-lo: nunca lhe indicou essa restrição. Esta é a secção que justifica todo o ficheiro.

Limites. Registe os pontos onde uma pequena edição pode ter um impacto amplo. O schema 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 iniciar a aplicação. A entrada do cron que pressupõe que só existe uma cópia em execução. Identifique cada um e indique o custo de uma alteração. Se o agente também puder aceder à web pública, através de uma instância self-hosted do SearXNG 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 qual deve ser apenas citado de volta para si.

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 produz código que parece correto e representa o conceito errado. Esse é 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 restante apenas como títulos. Um ficheiro com quatro linhas honestas é útil. Um ficheiro com quarenta linhas especulativas não é.

Algumas ferramentas carregam todos os ficheiros Markdown na raiz do repositório. Outras carregam apenas o ficheiro que lhes é indicado. Não presuma que todas funcionam da mesma forma. 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, mas 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 decisões foram tomadas.

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 espaço 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 ainda diz 3000. O agente não tem forma de determinar qual das duas informações 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 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 choque diretamente com uma invariante. "Adicione um job 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 job 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á conhecia. Ler os contadores de tokens no Claude Code mostra para onde vai esse orçamento.

Isto é mais importante quando o agente reside num servidor, e não no seu portátil. Um agente que trabalha numa sessão de longa duração, como a configuração em um workspace 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 uma regra invariável que nunca foi documentada. Cada um também indica 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, e não segundo um calendário. Se ainda está a perceber onde os agentes se enquadram num fluxo de desenvolvimento normal, o guia de 2026 para aprender a usar 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 uma página 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 existe é adoção por parte dos próprios fornecedores: sete empresas, incluindo Vercel, Nuxt, Atlassian e Resend, publicam um ficheiro num URL público, e uma coleção da comunidade contém mais 73 ficheiros obtidos por engenharia inversa a partir de sites públicos. Trate-o como uma convenção que pode adotar já e expandir 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ê certamente é melhor do que dois ficheiros, se um deles for 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 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 separá-los, 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 o histórico é caro de carregar, porque um 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 integralmente em cada tarefa. 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 é para ele que deve encaminhar o agente.

Qual deve ser o tamanho de um DESIGN.md?

Deve ser suficientemente curto para ser carregado em cada interação sem arrependimento. 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 de backend normalmente precisa de muito menos. Comece com uma página e aumente o ficheiro apenas quando um agente fizer algo incorreto que uma única frase teria evitado. O tamanho não é o critério. Cada linha deve descrever algo que, de outra forma, o agente faria incorretamente.