Publicado em 28/07/2026
Toda decisão importante de arquitetura tem uma pergunta escondida: "por quê?". Seis meses depois, ninguém lembra. Um ano depois, alguém reabre o debate e perde uma sprint inteira revisitando o que já foi decidido.
O ADR (Architecture Decision Record) mata esse ciclo. Ele é um documento de 200 a 500 palavras, versionado no repositório, com título curto e quatro seções: contexto, decisão, alternativas e consequências.
O template que funciona
Nós recomendamos MADR — Markdown Any Decision Records. Estrutura mínima:
- Título: "Escolhemos PostgreSQL como banco principal"
- Status: proposto / aceito / substituído
- Contexto: o problema real, sem enfeite
- Decisão: o que foi escolhido
- Consequências: o preço que você aceitou pagar
Onde guardar
Uma pasta docs/adr/ no próprio repositório, com arquivos numerados: 0001-postgres.md, 0002-events.md. Nada de Confluence, nada de Notion. Se a decisão mora com o código, ninguém pode alegar que não viu.
Guia completo com exemplos reais e template pronto: ADR na prática.