O que é DESIGN.md para Agentes de Programação?

Agentes de codificação são confiantes, rápidos e arquitetonicamente alheios à sua base de código até que você os instrua de outra forma. Entregue ao Claude Code ou Codex um ticket vago e ele felizmente escreverá um código que compila, passa em um teste rápido e silenciosamente viola a fronteira entre sua camada de domínio e sua camada HTTP. O agente não leu sua documentação de design. Ele leu os arquivos que pôde ver, fez correspondência de padrões e adivinhou. Um arquivo DESIGN.md resolve o problema da adivinhação ao registrar sua intenção arquitetônica no único lugar onde um agente sempre procura: o próprio repositório.

TL;DR

DESIGN.md é um arquivo de repositório de convenção da comunidade que registra a intenção arquitetônica, as restrições e as decisões de design de uma base de código em Markdown simples, para que os agentes de codificação (Claude Code, Codex, Cursor) gerem código que se ajuste ao sistema em vez de ir contra ele. Ele responde a "por que o código é estruturado dessa forma", enquanto o AGENTS.md responde a "como construir e testar".

Introdução

Aqui está o modo de falha que toda equipe que adota agentes de codificação encontra em uma semana. Você pede a um agente para adicionar um endpoint de reembolso a um serviço de pagamentos. Ele retorna um manipulador funcional que chama o banco de dados diretamente do controlador, ignora o erro do gateway e inventa um novo tipo de moeda porque não percebeu que você já tinha um. O diff está limpo. Os testes passam. Mas também está errado de três maneiras que apenas um revisor que conhece a arquitetura pode pegar. O agente não é ruim em codificar; ele é cego a decisões que vivem na sua cabeça, em uma página do Notion ou em um thread do Slack de oito meses atrás.

DESIGN.md é a resposta em que um número crescente de equipes convergiu. É um único arquivo Markdown, commitado na raiz do repositório, que informa a qualquer agente os fatos cruciais sobre o seu sistema: as regras de camadas, os invariantes que nunca devem ser quebrados, os padrões que você escolheu de propósito e os que você rejeitou. Não é uma especificação de fornecedor e não há um comitê que seja seu proprietário; é uma convenção, da mesma forma que ARCHITECTURE.md e CONTRIBUTING.md são convenções. Mas ele se conecta naturalmente com os arquivos de instrução específicos da ferramenta que os agentes já leem, e para trabalho de API e backend, é um dos documentos de maior alavancagem que você pode escrever.

O que DESIGN.md realmente é

DESIGN.md é um registro em texto puro do porquê seu código é estruturado dessa forma. Não o que ele faz (isso é o README), nem como executá-lo (isso é o AGENTS.md), mas o raciocínio que um engenheiro sênior explicaria a um novo contratado no primeiro dia antes de deixá-lo mexer em algo importante.

Pense nas conversas que não estão em nenhum arquivo. “Não chamamos o gateway de pagamento da thread de requisição; tudo passa pela tabela de outbox porque o gateway expira sob carga.” “O dinheiro é sempre uma contagem inteira de unidades menores; banimos floats após o incidente de arredondamento.” “O agregado Account é o proprietário das mutações de saldo; nada mais escreve no livro-razão.” Essas são decisões de design. Elas são invisíveis para um agente que lê o código-fonte, porque a fonte mostra o resultado da decisão, não a decisão ou sua justificativa. Um agente pode ver que Account.debit() existe. Ele não consegue ver que você deliberadamente o tornou o único caminho de escrita, então ele alegremente adicionará um segundo.

A convenção tem raízes em práticas mais antigas e bem estabelecidas. O padrão ARCHITECTURE.md (popularizado pelo amplamente citado artigo de Alex Kladov) defende que um repositório deve conter um mapa de alto nível da base de código que explique a estrutura e os invariantes sem tentar se manter sincronizado linha a linha com o código. Os Registros de Decisões de Arquitetura (ADRs) capturam decisões individuais e sua justificativa ao longo do tempo. DESIGN.md é o que você obtém ao escrever esse tipo de documento para um público que inclui um agente de codificação: conciso, declarativo, orientado a decisões e estacionado onde o agente realmente o carregará.

Duas propriedades o fazem funcionar. Ele está no repositório, então o agente o lê com as mesmas ferramentas que lê o código; você não precisa de um plugin ou de uma chamada de API. E é sobre intenção, então permanece útil mesmo com a movimentação de arquivos. Renomeie um pacote e as capturas de tela do seu README apodrecem; a regra "a lógica de domínio nunca importa o framework web" ainda é verdadeira.

DESIGN.md vs AGENTS.md vs CLAUDE.md vs README

Esses arquivos se sobrepõem o suficiente para confundir as pessoas e diferem o suficiente para que colapsá-los em um só seja um erro. A versão curta: README é para humanos em processo de integração, AGENTS.md é o contrato operacional para agentes, CLAUDE.md é o arquivo de instrução específico do Claude, e DESIGN.md é o raciocínio arquitetônico de que todos eles se beneficiam.

AGENTS.md é agora um formato real e amplamente adotado; o projeto agents.md o descreve como "um formato simples e aberto para guiar agentes de codificação", usado em dezenas de milhares de projetos e supervisionado pela Fundação Agentic AI da Linux Foundation. Sua função é operacional: etapas de construção, comandos de teste, estilo de código, convenções de commit, as coisas que você diria a um novo colega de equipe para mantê-lo desbloqueado. De acordo com a documentação de memória do Claude Code da Anthropic, CLAUDE.md desempenha o mesmo papel de instrução especificamente para o Claude; a documentação até recomenda que, se você já tiver um AGENTS.md, crie um CLAUDE.md que o importe com @AGENTS.md para que ambas as ferramentas leiam uma única fonte de verdade.

Observe o que falta nessas descrições: justificativa arquitetônica profunda. AGENTS.md e CLAUDE.md são ajustados para serem curtos. A documentação do Claude Code recomenda explicitamente manter o CLAUDE.md com menos de 200 linhas porque arquivos mais longos consomem contexto e reduzem a confiabilidade com que o modelo os segue. Uma explicação arquitetônica real, os limites, os invariantes, as alternativas rejeitadas, as regras do modelo de dados, não caberão lá sem inchá-lo. Então você o referencia. DESIGN.md se torna o documento aprofundado; AGENTS.md / CLAUDE.md o apontam com uma única linha.

A relação é complementar, não competitiva. Uma configuração limpa para uma empresa que usa Claude + Codex seria assim: README.md para humanos; um AGENTS.md com etapas de construção/teste/estilo; um CLAUDE.md que é apenas @AGENTS.md mais duas linhas específicas do Claude; e DESIGN.md contendo a arquitetura, linkado do AGENTS.md para que todo agente o carregue sob demanda. Sem duplicação, cada arquivo tem uma única função. Se você quiser um tour mais aprofundado sobre como estruturar o contexto do Claude nesses arquivos, Fluxos de trabalho do Claude Code detalha o modelo de memória na prática.

O que colocar em DESIGN.md (com um modelo)

DESIGN.md deve responder às perguntas que um agente não consegue inferir do código: a forma do sistema, as regras que não aparecem em nenhum arquivo único e as decisões que você tomou de propósito. Mantenha-o declarativo. Cada seção deve ser lida como uma regra que um revisor imporia, não um ensaio.

Cubra estes pontos:

• Forma do sistema: as camadas ou módulos e qual direção as dependências fluem. Uma frase por limite.
• Invariantes: coisas que devem ser sempre verdadeiras. Declare-as como absolutos. “Saldos nunca ficam negativos fora de um cheque especial autorizado.” “Toda chamada externa é idempotente por chave de requisição.”
• Decisões-chave e sua justificativa: as escolhas que parecem arbitrárias até que você saiba o porquê. Inclua o porquê; a justificativa é o que impede um agente de "corrigi-lo".
• Alternativas rejeitadas: o que você deliberadamente não fez, para que um agente não o proponha como uma ideia nova. Esta única seção previne uma enorme classe de sugestões ruins.
• Regras de dados e domínio: representação de moeda, tratamento de data/hora/fuso horário, identificadores, soft-delete, multi-tenancy.
• A única fonte de verdade do contrato da API: onde a especificação OpenAPI vive e a regra de que ela é autoritativa sobre tipos escritos à mão.
• Onde o novo código vai: um pequeno mapa "se você está adicionando X, ele pertence a Y" para que os agentes parem de espalhar a lógica.
• Fora do escopo / não tocar: arquivos gerados, módulos legados em migração, qualquer coisa que um agente deva deixar em paz.

Aqui está um modelo completo, escrito para um serviço de API de pagamentos realista. Copie-o, exclua o que não se aplica, preencha o restante.

# DESIGN.md: Serviço de API de Pagamentos

Este arquivo registra a intenção arquitetônica e as decisões por trás dela.
Leia isto antes de gerar ou modificar o código. Se uma alteração entrar em conflito
com uma regra aqui, pare e sinalize-a em vez de contorná-la.

## Forma do sistema

Em camadas, dependências apontam apenas para dentro:

  http (manipuladores, DTOs)  ->  app (casos de uso)  ->  domínio (entidades,
  invariantes)  <-  infra (db, clientes de gateway)

- `domain/` não possui importações de `http/`, `app/`, ou qualquer framework.
- `infra/` implementa interfaces declaradas em `domain/` ou `app/`.
- `http/` nunca toca o banco de dados ou o gateway de pagamento diretamente.
  Ele chama um caso de uso em `app/`.

## Invariantes (devem ser sempre verdadeiros)

- Uma entrada de livro-razão é imutável uma vez escrita. Correções são novas
  entradas compensatórias, nunca atualizações ou exclusões.
- O saldo da conta é derivado de entradas do livro-razão, não armazenado como um
  campo mutável que o código pode definir diretamente.
- O dinheiro é uma contagem inteira de unidades menores (centavos) mais um código
  de moeda ISO-4217. Nunca um float. Nunca misture moedas em uma operação.
- Toda chamada a um gateway de pagamento externo é idempotente, chaveada por
  `idempotency_key`. Retentativas não devem gerar dupla cobrança.
- Saldos nunca ficam negativos, a menos que uma `OverdraftPolicy` explícita
  o autorize para aquela conta.

## Decisões-chave e justificativa

- **Padrão Outbox para chamadas de gateway.** Manipuladores escrevem uma linha
  de intenção na mesma transação de DB que a alteração de negócio, então um worker
  chama o gateway. Justificativa: o gateway expira sob carga;
  fazê-lo inline tornava a latência da requisição e o tratamento de falhas sem
  proprietário. Não chame o gateway de um manipulador de requisição.
- **Único caminho de escrita por agregado.** Apenas `Account.post_entry()`
  escreve no livro-razão. Justificativa: um segundo caminho de escrita causou o
  desvio de saldo em Mar-2025. Adicione um novo comportamento como métodos no
  agregado, não novas queries.
- **Event sourcing apenas para o livro-razão.** O restante do sistema é
  CRUD. Justificativa: precisamos de um rastro de auditoria perfeito para dinheiro e
  nada mais, e o event sourcing completo era muito caro em outros lugares.

## Alternativas rejeitadas (não reintroduzir)

- Carregamento preguiçoso (lazy-loading) de ORM entre agregados; causava N+1s e
  limites de transação pouco claros. Repositórios retornam agregados
  totalmente carregados.
- Armazenar saldo como uma coluna atualizada no lugar; veja incidente de
  desvio de saldo. O saldo é sempre derivado.
- Uma biblioteca `Money` genérica puxada do registro; temos nossa
  própria `domain/money.py`; use-a.
- Webhooks síncronos para comerciantes da thread de requisição; eles
  bloqueiam e falham silenciosamente. Use a fila de notificação.

## Regras de dados e domínio

- Todos os timestamps são UTC, armazenados como timestamptz, formatados RFC 3339
  na borda. Nenhum datetime ingênuo cruza um limite de função.
- IDs são ULIDs gerados na camada de aplicação, nunca autoincremento de DB.
- Soft delete não é usado. Registros são ativos ou movidos para uma
  tabela de arquivo por um caso de uso explícito.
- Multi-locatário: toda query é com escopo de `tenant_id`. Um método de repositório
  sem um escopo de locatário é um bug.

## Única fonte de verdade do contrato da API

- A especificação OpenAPI 3.1 em `api/openapi.yaml` é autoritativa.
  Os tipos de requisição/resposta são gerados a partir dela; não edite manualmente os
  tipos gerados em `http/generated/`.
- Endpoints novos ou alterados: atualize `api/openapi.yaml` primeiro, depois
  regenere, então implemente. A especificação é projetada e revisada no
  Apidog antes das alterações de código.
- Respostas de erro seguem RFC 9457 (problem+json). Use o auxiliar compartilhado
  `problem()`; não invente formatos de erro ad-hoc.

## Onde o novo código vai

- Novo endpoint: rota em `http/routes/`, DTO em `http/dto/`, caso de
  uso em `app/usecases/`, lógica de domínio em `domain/`.
- Nova integração externa: cliente em `infra/clients/`, interface
  em `app/ports/`.
- Preocupação transversal (autenticação, logging, idempotência): middleware em
  `http/middleware/`, nunca inline em manipuladores.

## Fora do escopo / não tocar

- `http/generated/`: regenerado do OpenAPI, edições são perdidas.
- `legacy/billing_v1/`: congelado, em migração. Não estender.
- `migrations/`: nunca edite uma migração aplicada; adicione uma nova.

## Em caso de dúvida

Se uma alteração solicitada exigir a quebra de uma regra acima, o correto
é informar e propor a menor alternativa consistente com o design,
e não contornar a regra silenciosamente.

Essa última seção importa mais do que parece. Dizer a um agente o que fazer quando a requisição conflita com o design transforma o arquivo de documentação passiva em um guarda-chuva ativo. Sem ele, um agente que encontra uma restrição tende a contorná-la e enviar a solução alternativa.

Como os agentes de codificação realmente consomem DESIGN.md

Os agentes não têm um analisador DESIGN.md especial. Eles o consomem da mesma forma que consomem qualquer arquivo: lendo-o com suas ferramentas de arquivo e tratando o conteúdo como contexto. Portanto, a mecânica de como ele é carregado importa, e difere ligeiramente por ferramenta.

O padrão confiável é referenciar DESIGN.md a partir do arquivo de instrução que cada agente já carrega na inicialização. Para o Claude Code, é o CLAUDE.md; a documentação de memória descreve uma sintaxe de importação @path onde @DESIGN.md expande o arquivo para o contexto no início da sessão. Para o ecossistema AGENTS.md, você adiciona uma linha em AGENTS.md apontando para ele ("Regras de arquitetura e design: consulte DESIGN.md; leia-o antes de alterações estruturais"). Agentes que percorrem a árvore de diretórios pegarão o AGENTS.md mais próximo, verão o ponteiro e puxarão DESIGN.md quando o trabalho tocar na arquitetura. De qualquer forma, você não está duplicando conteúdo; você está mantendo o arquivo operacional curto e deixando o arquivo aprofundado ser aprofundado.

Três notas práticas sobre como essas ferramentas se comportam:

Primeiro, o agente trata o arquivo como contexto, não como regras impostas. A documentação do Claude Code é direta ao afirmar que o conteúdo do CLAUDE.md é uma orientação que o modelo tenta seguir, não uma restrição rígida. O mesmo se aplica a qualquer coisa que você referencie a partir dele. É por isso que o modelo formula tudo como absolutos testáveis e adiciona uma instrução explícita "em caso de dúvida"; a prosa vaga é ignorada sob pressão, regras claras são seguidas com mais frequência.

Segundo, o comprimento e a estrutura mudam a adesão. Títulos e marcadores superam parágrafos porque o modelo escaneia a estrutura da mesma forma que um leitor. Uma parede de filosofia arquitetônica de 3 páginas será lida rapidamente; dez invariantes nítidos sob um título claro serão usados. Escreva para recuperação, não para prosa.

Terceiro, o arquivo muda a economia de revisão, não apenas a geração. Mesmo quando um agente o ignora parcialmente, um revisor pode apontar a regra violada e o agente a corrige em uma única vez ("isso quebra a regra de caminho de escrita único em DESIGN.md"). Esse ciclo de feedback, fundamentar a correção na decisão escrita, é onde muito do valor real se concretiza. Equipes construindo suas próprias ferramentas de agente dependem exatamente disso; veja construa seu próprio Claude Code para saber como esse ciclo é integrado em fluxos autônomos.

Antipadrões e como evitar que se deteriore

A maneira mais rápida de tornar o DESIGN.md inútil é escrevê-lo como uma página wiki. Um arquivo de design deteriorado é pior do que nenhum, porque agentes e humanos confiam nele e são enganados. Evite estes:

Reafirmar o código. "A classe UserService lida com usuários" não informa ao agente nada que ele não possa ler em user_service.py. Se uma frase é verdadeira ao ler o arquivo, corte-a. Mantenha apenas o que o código não pode lhe dizer: justificativa, invariantes, caminhos rejeitados.

Excesso de tutoriais. Passo a passo de "como adicionar uma funcionalidade" pertencem ao CONTRIBUTING.md ou a um skill, não aqui. No momento em que o DESIGN.md tiver comandos de shell e trechos de copiar e colar, ele será o documento errado e ficará desatualizado na velocidade das ferramentas.

Aspiração como fato. Escrever "o sistema usa CQRS" quando metade dele não usa treina os agentes a produzir código que corresponde a uma ficção. Documente o que é verdade agora e para onde você está deliberadamente se dirigindo, e rotule a diferença. "Meta: todas as escritas passam por casos de uso. Atual: legacy/ contorna isso; não o estenda."

Sem proprietário, sem gatilho de revisão. Um arquivo de design pelo qual ninguém é responsável se desvia em um trimestre. Amarre-o a um gatilho: revise o DESIGN.md em qualquer PR que adicione um módulo, altere um limite de camada ou introduza uma nova dependência externa. Coloque essa regra no modelo de PR. Algumas equipes adicionam um item de lista de verificação, "esta mudança altera uma decisão em DESIGN.md? Se sim, atualize-o na mesma PR."

Teatro de sincronização. Não tente mantê-lo sincronizado linha a linha com o código; isso é uma batalha perdida e é a razão pela qual a documentação de arquitetura é abandonada. Mantenha-o no nível de decisões que mudam algumas vezes por ano, não assinaturas de funções que mudam semanalmente. A orientação de matklad para ARCHITECTURE.md é o instinto correto aqui: registre apenas o que é improvável de mudar com frequência.

Contradizer os outros arquivos de instrução. Se AGENTS.md diz uma coisa sobre tratamento de erros e DESIGN.md diz outra, os agentes escolhem um arbitrariamente. Mantenha as regras operacionais em AGENTS.md / CLAUDE.md e as regras arquitetônicas em DESIGN.md, e não deixe que se sobreponham. Quando eles devem se referenciar, um aponta para o outro; eles não afirmam o mesmo fato.

Um DESIGN.md saudável é curto, denso, declarativo, de propriedade e revisado por um gatilho. Se o seu for longo, narrativo e foi tocado pela última vez há um ano, os agentes estão lendo ficção.

DESIGN.md para bases de código de API e backend

É aqui que o arquivo ganha seu valor. Serviços de API e backend têm exatamente o tipo de restrições invisíveis e de alto custo em que os agentes são piores: limites de contrato, semântica de transação, idempotência, integridade de dados, camadas. Nada disso é óbvio a partir de um único arquivo, e errar envia bugs que chegam à produção e ao dinheiro.

Coloque estas coisas específicas da API em DESIGN.md e a qualidade da saída do agente em tickets de backend aumentará:

O contrato é a única fonte de verdade, e diga onde ele está. Declare claramente que a especificação OpenAPI é autoritativa e que os tipos gerados não devem ser editados manualmente. Agentes adoram "ajudar" a ajustar um tipo gerado para fazer uma build passar; uma linha em DESIGN.md impede isso. Aponte para o caminho do arquivo de especificação. Se você projetar o contrato primeiro no Apidog e exportar o documento OpenAPI para o repositório, seu DESIGN.md pode nomear esse arquivo como a coisa a que todo endpoint deve estar em conformidade, e o agente tem um alvo inequívoco. O argumento para projetar o contrato antes do código é abordado em projetando APIs para agentes de IA; um contrato design-first é exatamente o que torna os manipuladores gerados por agentes seguros para aceitar.

Limites de transação e consistência. Onde uma transação começa e termina? O que é permitido dentro dela? "Chamadas externas nunca acontecem dentro de uma transação de DB; use o outbox." Agentes, por padrão, fazem a chamada inline ingênua toda vez, a menos que o arquivo proíba.

Idempotência e retentativas. Declare a estratégia de idempotência como um invariante. Endpoints de pagamento, pedido e provisionamento são onde uma chave de idempotência ausente se torna uma dupla cobrança. O agente não inferirá isso lendo um manipulador.

Modelo de erro. Uma frase: "todos os erros são problem+json via o auxiliar problem(); nunca invente formatos de erro." Sem isso, você obtém um envelope de erro diferente por endpoint, o que quebra todo cliente.

Escopo de autenticação e multilocação. "Toda query tem escopo de locatário; um método de repositório sem escopo é um bug." Este é um invariante de segurança, e é invisível em qualquer query individual, então é exatamente o tipo de regra que precisa ser escrita.

Regras de versionamento e mudanças disruptivas. O que conta como disruptivo, como você versiona, o que é permitido em uma versão menor. Agentes felizmente renomearão um campo de resposta; o arquivo lhes diz que isso é uma mudança disruptiva com um processo.

Para o trabalho de backend, o retorno é concreto: menos violações de camadas, nenhuma chamada de gateway inline inesperada, formatos de erro e paginação consistentes, e manipuladores em conformidade com o contrato, porque o agente foi direcionado para a especificação OpenAPI em vez de adivinhar o esquema. O agente para de inventar e começa a se conformar. Se você quiser que o agente também exercite a API que acabou de escrever, a combinação contrato-mais-design é o que permite que ferramentas e agentes testem contra uma interface conhecida; Baixe o Apidog para ter o espaço de trabalho design-first, a exportação OpenAPI que seu DESIGN.md aponta, e um servidor MCP e depurador de agente de IA para verificar se os endpoints gerados realmente correspondem ao contrato.

Conclusão

• DESIGN.md registra por que seu código é estruturado da forma que é: os invariantes, decisões e alternativas rejeitadas que um agente não consegue ler do código-fonte.
• Ele complementa em vez de substituir AGENTS.md e CLAUDE.md: esses permanecem curtos e operacionais; DESIGN.md contém a arquitetura profunda e é referenciado por eles.
• Escreva-o declarativamente, como absolutos testáveis, além de uma regra "em caso de dúvida, sinalize e não contorne", para que atue como um guarda-corpo, não como prosa passiva.
• Ele compensa mais em bases de código de API e backend, onde os limites de contrato, transações, idempotência e escopo de multilocação são invisíveis e caros para errar.
• Evite que se deteriore com um proprietário e um gatilho de revisão amarrado ao seu modelo de PR; nunca o sincronize linha a linha com o código.
• O maior ganho de backend é nomear a especificação OpenAPI como autoritativa para que os agentes se conformem ao contrato em vez de inventar esquemas.
• Projete esse contrato primeiro. Baixe o Apidog para projetar APIs com uma abordagem design-first, exporte a especificação OpenAPI que seu DESIGN.md aponta, e teste se os endpoints gerados por agentes realmente correspondem a ela.

Perguntas Frequentes

É DESIGN.md um padrão oficial como AGENTS.md?

Não. AGENTS.md é um formato definido e amplamente adotado, agora supervisionado pela Fundação Agentic AI da Linux Foundation. DESIGN.md é uma convenção da comunidade sem um único proprietário ou especificação, na mesma família de ARCHITECTURE.md e ADRs. Trate-o como um padrão útil que você adapta, não um padrão ao qual você se conforma.

Preciso de DESIGN.md se já tenho AGENTS.md ou CLAUDE.md?

Se sua arquitetura tiver restrições não óbvias, sim. AGENTS.md e CLAUDE.md são feitos para serem curtos e operacionais; a documentação do Claude Code recomenda manter o CLAUDE.md com menos de aproximadamente 200 linhas. A justificativa arquitetônica profunda não se encaixa lá sem inchá-lo e prejudicar a adesão, então você a coloca em DESIGN.md e a referencia. Para o próprio arquivo operacional, consulte como escrever arquivos AGENTS.md.

Como DESIGN.md difere de ARCHITECTURE.md?

Principalmente na intenção e no público. ARCHITECTURE.md é a convenção mais antiga destinada a colaboradores humanos que mapeiam a base de código. DESIGN.md é a mesma ideia escrita para um público que inclui um agente de codificação: mais declarativo, focado em decisões e invariantes, e explicitamente referenciado nos arquivos de instrução do agente para que seja carregado no contexto. Muitas equipes usam um arquivo e um nome; os princípios são os mesmos.

Qual deve ser o comprimento de DESIGN.md?

Longo o suficiente para cobrir as decisões que os agentes continuam errando, curto o suficiente para que cada linha tenha seu valor. Denso em decisões é melhor que abrangente. Se ele parece um tutorial ou reafirma o código, corte-o. Duas a quatro páginas focadas de invariantes e justificativa são melhores do que uma narrativa de quinze páginas que nenhum agente lerá atentamente.

Como faço para que o agente realmente o leia?

Referencie-o no arquivo que o agente já carrega na inicialização. Para o Claude Code, importe-o do CLAUDE.md com @DESIGN.md. Para o ecossistema AGENTS.md, adicione uma linha de ponteiro em AGENTS.md instruindo os agentes a ler DESIGN.md antes de alterações estruturais. Não cole o arquivo inteiro no arquivo curto; referencie-o para que o arquivo operacional permaneça curto.

O agente sempre seguirá o DESIGN.md?

Não, e você deve projetar levando isso em consideração. Os arquivos de instrução do agente são um contexto que o modelo tenta seguir, não uma configuração imposta. Escreva regras como absolutos precisos, adicione uma instrução explícita "sinalize conflitos, não os contorne" e confie no ciclo de revisão; apontar para uma regra violada em DESIGN.md resulta em uma correção rápida e correta, mesmo que a primeira passagem tenha perdido.

DESIGN.md ajuda especificamente com problemas de contrato de API?

Muito. Seu uso de maior valor para backend é declarar que a especificação OpenAPI é autoritativa e nomear o arquivo, para que os agentes se conformem ao contrato em vez de inventar esquemas ou editar manualmente tipos gerados. Projetar esse contrato primeiro em uma ferramenta como Apidog dá ao agente um alvo inequívoco que seu DESIGN.md pode apontar diretamente.

Onde o DESIGN.md deve viver no repositório?

Na raiz do repositório, ao lado de README.md e AGENTS.md, para que agentes e humanos o encontrem sem pesquisa. Em um monorepo, um DESIGN.md na raiz para regras em todo o sistema, mais um por pacote para arquitetura local, funciona bem, espelhando como os agentes leem o AGENTS.md mais próximo na árvore de diretórios.