Template ADR (Architectural Decision)

ADR: capturando o porquê das decisões de arquitetura

Um ADR — Architecture Decision Record — é um documento curto em Markdown que registra uma decisão arquitetural: o contexto que a motivou, a decisão em si e as consequências que se seguem. O formato foi proposto por Michael Nygard num post de blog de 2011 intitulado "Documenting Architecture Decisions" e rapidamente virou o padrão da indústria por um motivo simples: meses depois de tomada uma decisão, ninguém lembra por quê. ADRs preservam o raciocínio para que mantenedores futuros — que com frequência incluem os autores originais — possam entender por que o sistema é do jeito que é sem ter que fazer engenharia reversa.

O template de Nygard tem cinco seções: Título (numerado — "ADR-0007: Usar PostgreSQL"), Status (Proposto, Aceito, Deprecado ou Substituído por ADR-N), Contexto (quais forças estão em jogo?), Decisão (o que escolhemos?) e Consequências (o que fica mais fácil e o que fica mais difícil?). A comunidade depois produziu refinamentos — MADR (Markdown Architectural Decision Records, hospedado em adr.github.io) é o padrão de fato — e um CLI chamado adr-tools, do Nat Pryce, automatiza o boilerplate.

Onde ADRs ficam e como são numerados

A localização convencional é docs/adr/ dentro do repositório git relevante, com arquivos nomeados 0001-usar-postgresql.md, 0002-deploy-no-kubernetes.md e por aí vai. Os números são sequenciais e nunca reutilizados — mesmo quando um ADR é deprecado, seu número é preservado para que referências cruzadas em commits e comentários de código continuem válidas. Quando uma nova decisão substitui uma antiga, o status do ADR antigo vira "Substituído por ADR-0017" e o contexto do novo cita o antigo. Um time saudável produz aproximadamente um ADR a cada uma ou duas semanas; longos hiatos costumam significar ou que nenhuma decisão significativa está sendo tomada, ou, mais provavelmente, que decisões estão sendo tomadas sem registro.

ADR vs RFC vs design doc

Uma RFC é o estágio de proposta — aberta a debate, possivelmente recusada. Um design doc é o plano detalhado para implementar algo já aprovado, cobrindo múltiplos componentes e decisões. Um ADR registra exatamente uma decisão já tomada; é curto (uma a duas páginas é o ponto ideal) e imutável depois de aceito. O pipeline natural é RFC → design doc → ADRs que destilam as escolhas-chave para a posteridade. ADRs também fazem parte do AWS Well-Architected Framework e são usados no Spotify, HashiCorp, Zalando e ThoughtWorks.

Anti-padrões e bons exemplos

Os modos de falha comuns: ADRs para decisões triviais (a escolha do nome de uma variável não precisa de ADR; a escolha de um banco precisa), "porquê" ausente (um ADR que lista o que foi escolhido mas não o que foi considerado e descartado é meio documento), ADRs longos demais (qualquer coisa acima de duas páginas provavelmente queria ser um design doc) e matriz de decisão ausente (quando múltiplas opções foram consideradas, uma tabela de critérios ponderados torna o raciocínio auditável). O repositório architecture-decision-record do Joel Parker Henderson no GitHub é a coleção pública canônica de exemplos e templates.

Perguntas frequentes

Quando devo escrever um ADR? Quando uma decisão for cara de reverter — escolha de banco, formato de API pública, plataforma de deploy, modelo de autenticação, message bus. Se a decisão é "vamos usar camelCase", não. Se a decisão é "vamos usar event sourcing", sim.

Qual o tamanho de um ADR? Uma a duas páginas. Se passar disso, você provavelmente embalou múltiplas decisões; divida em vários ADRs.

Existe template reutilizável? Sim — o template de Nygard (5 seções) e o template MADR são ambos de domínio público e amplamente adotados. Qualquer um é um ponto de partida defensável.

ADRs podem ser revisitados? O ADR em si é imutável, mas seu status pode mudar. Se uma decisão deixou de valer, escreva um novo ADR que substitui o antigo e atualize o status do antigo para Substituído por ADR-N. Nunca edite o histórico — o registro histórico é o objetivo todo.