ADRs: Architecture Decision Records

1. O que são ADRs e por que documentar decisões arquiteturais

Architecture Decision Records (ADRs) são documentos concisos que registram decisões arquiteturais significativas em um projeto de software. O conceito foi introduzido por Michael Nygard em 2011, como uma resposta à necessidade de capturar o raciocínio por trás das escolhas técnicas que moldam a arquitetura de um sistema.

Diferentemente da documentação tradicional — que frequentemente descreve o estado atual do sistema sem explicar como se chegou ali —, os ADRs focam no processo de tomada de decisão. Enquanto um documento de arquitetura convencional pode listar "usamos PostgreSQL como banco de dados", um ADR explica "por que escolhemos PostgreSQL em vez de MongoDB, considerando requisitos de consistência e transações".

Os principais benefícios incluem:

  • Rastreabilidade: qualquer membro da equipe pode entender decisões tomadas meses ou anos atrás
  • Contexto histórico: novos integrantes compreendem rapidamente as restrições arquiteturais
  • Alinhamento de equipe: todos participam e concordam com as decisões documentadas

2. Estrutura canônica de um ADR

A estrutura mais aceita segue o formato proposto por Nygard, com cinco campos essenciais:

# ADR 001: Escolha do Banco de Dados Relacional

## Status
Aceito

## Contexto
O sistema precisa armazenar dados financeiros com forte consistência ACID. 
A equipe avaliou opções NoSQL e relacionais. O volume estimado é de 10 milhões 
de transações por mês, com necessidade de consultas complexas e joins.

## Decisão
Adotaremos PostgreSQL 15 como banco de dados principal. A escolha baseia-se em:
- Suporte nativo a transações ACID
- Maturidade do ecossistema e comunidade ativa
- Capacidade de lidar com consultas analíticas via extensões como pg_stat_statements

## Consequências
Positivas: consistência forte, ferramentas maduras de backup e replicação
Negativas: escalabilidade vertical limitada para cargas extremas; custo de 
licenciamento de ferramentas complementares como ferramentas de sharding

Variações comuns incluem campos adicionais como "Opções Consideradas", "Prós e Contras", "Data" e "Autores". A recomendação é manter o formato enxuto, adicionando campos apenas quando agregarem valor real.

3. Ciclo de vida e estados de um ADR

Os estados típicos de um ADR seguem um ciclo de vida bem definido:

Proposto → Aceito → (opcional) Depreciado → Substituído
  • Proposto: decisão em discussão, aguardando revisão
  • Aceito: decisão aprovada e implementada
  • Depreciado: ainda válido, mas não recomendado para novos contextos
  • Substituído: substituído por um ADR mais recente

O fluxo de aprovação geralmente envolve:
1. Um arquiteto ou desenvolvedor sênior propõe o ADR
2. A equipe revisa em pull request ou reunião técnica
3. Após consenso, o ADR é aceito e mergeado no repositório

Para ADRs concorrentes, a prática recomendada é criar ADRs separados para cada opção, documentando as razões de rejeição no ADR vencedor.

4. Boas práticas na escrita de ADRs

Escrever ADRs eficazes requer disciplina e clareza:

Linguagem clara e objetiva: evite jargões desnecessários. Um ADR deve ser compreensível por desenvolvedores juniores e por stakeholders não técnicos.

Foco no "porquê": a seção de Contexto deve explicar o problema e as restrições, não apenas descrever a solução. Um bom ADR responde "por que essa decisão foi tomada, dadas as alternativas?"

Tamanho ideal: cada seção principal deve ter entre 1 e 3 parágrafos. ADRs muito longos perdem o propósito de serem registros rápidos de decisão.

Exemplo de seção de Contexto bem escrita:

## Contexto
Precisamos de um mecanismo de cache para reduzir latência em consultas de 
catálogo de produtos. O cache deve expirar automaticamente em 5 minutos e 
suportar invalidação por evento. A equipe tem experiência com Redis, mas 
também considera soluções gerenciadas como ElastiCache.

5. Integração de ADRs no fluxo de desenvolvimento

A integração eficaz de ADRs no fluxo de desenvolvimento segue estas práticas:

Versionamento com Git: armazene ADRs em um diretório docs/adr/ no repositório principal. Cada ADR é um arquivo Markdown nomeado sequencialmente (ex: 0001-escolha-banco.md).

Revisão via pull requests: ADRs propostos passam pelo mesmo processo de code review que código fonte. Isso garante discussão e consenso.

Ferramentas de suporte:

  • adr-tools: CLI para criar, listar e gerenciar ADRs
  • Log4brains: ferramenta com interface web para visualizar e navegar ADRs
  • Markdown Any Decision: extensão para ferramentas como Obsidian e VS Code

Relação com wikis: evite duplicação. Use ADRs como fonte primária e referencie-os em wikis corporativos com links diretos.

6. ADRs como fitness functions para evolutionary architecture

No contexto de arquitetura evolucionária, ADRs funcionam como registros de restrições arquiteturais que podem ser verificadas automaticamente via fitness functions.

Exemplo: um ADR que define política de latência pode acionar testes automatizados:

# ADR 012: Política de Latência para APIs de Pagamento

## Contexto
As APIs de pagamento precisam responder em menos de 200ms (p95) para 
evitar timeout em sistemas externos.

## Decisão
Implementar cache distribuído com Redis para consultas de saldo e 
limitar chamadas síncronas a serviços externos.

## Consequências
Positivas: latência previsível dentro do SLA
Negativas: complexidade operacional do Redis; necessidade de estratégia 
de cache warming

A fitness function correspondente seria um teste de performance que falha se o p95 ultrapassar 200ms, executado em cada pipeline de CI/CD.

7. Armadilhas comuns e como evitá-las

Superdocumentação: documentar cada pequena decisão técnica (ex: "usar tabs em vez de espaços") gera ruído. Defina um limiar claro — documente apenas decisões com impacto arquitetural significativo.

ADRs zumbi: ADRs aceitos mas nunca implementados ou revisados. Estabeleça revisões periódicas (ex: a cada trimestre) para verificar se ADRs ainda são relevantes.

Falta de engajamento: se apenas arquitetos escrevem ADRs, a equipe não se apropria. Incentive desenvolvedores a propor ADRs para decisões que afetam a arquitetura.

Solução: crie um template simples, realize workshops de escrita de ADRs e celebre boas decisões documentadas.

8. ADRs no contexto de observabilidade e OpenTelemetry

ADRs são particularmente úteis para registrar decisões sobre ferramentas e padrões de observabilidade, área onde escolhas técnicas têm impacto direto na capacidade de diagnóstico de sistemas.

Exemplo de ADR sobre padrão de span attributes no OpenTelemetry:

# ADR 023: Padrão de Span Attributes para Rastreamento Distribuído

## Status
Aceito

## Contexto
Precisamos padronizar os atributos de spans OpenTelemetry para garantir 
rastreabilidade consistente entre serviços. Atualmente, cada equipe usa 
nomes e formatos diferentes.

## Decisão
Adotar a nomenclatura semântica do OpenTelemetry (semconv) para:
- http.method, http.url, http.status_code
- db.system, db.statement para operações de banco
- Messaging system attributes para filas

## Consequências
Positivas: correlação entre traces de diferentes serviços; compatibilidade 
com ferramentas como Jaeger e Grafana Tempo
Negativas: necessidade de atualizar bibliotecas de instrumentação; 
treinamento das equipes

ADRs como este apoiam a rastreabilidade de mudanças em métricas e logs, permitindo que times entendam por que determinados padrões foram adotados e quais trade-offs foram considerados.

Referências