Boas práticas de documentação de arquitetura com ADRs

1. Fundamentos dos ADRs (Architecture Decision Records)

Architecture Decision Records (ADRs) são documentos leves que capturam decisões arquiteturais importantes em um projeto de software. Cada ADR registra uma decisão específica, seu contexto, as alternativas consideradas e as consequências esperadas. O conceito foi formalizado por Michael Nygard em 2011, no artigo "Documenting Architecture Decisions", como uma resposta à necessidade de rastrear o "porquê" por trás das escolhas técnicas.

Em sistemas complexos e distribuídos, onde múltiplos times tomam decisões interdependentes, os ADRs evitam que o conhecimento arquitetural se perca com a rotatividade de pessoas ou com o passar do tempo. Eles funcionam como um "diário de bordo" da arquitetura, permitindo que novos integrantes entendam não apenas o que foi decidido, mas por que foi decidido daquela forma.

2. Estrutura canônica de um ADR

O template clássico proposto por Nygard contém cinco seções essenciais:

# Título: Breve descrição da decisão

## Status
[Proposto | Aceito | Depreciado | Substituído | Rejeitado]

## Contexto
Descreva o problema, as restrições e o cenário que motivam a decisão.

## Decisão
Registre a decisão tomada de forma clara e inequívoca.

## Consequências
Liste os impactos positivos e negativos, trade-offs e riscos assumidos.

Variações comuns incluem seções adicionais como "Alternativas Consideradas", "Prós/Contras" e "Referências". Abaixo, um exemplo completo para uma decisão de mensageria:

# ADR-001: Adoção do Apache Kafka para mensageria assíncrona

## Status
Aceito

## Contexto
O sistema de pedidos precisa processar 10.000 eventos/segundo com garantia de entrega.
Requisitos: ordenação por chave, replay de mensagens e tolerância a falhas.
Alternativas: RabbitMQ (entrega rápida, sem ordenação forte) e AWS SQS (sem ordenação).

## Decisão
Adotar Apache Kafka como barramento de eventos principal.
Justificativa: Kafka oferece ordenação por partição, retenção configurável e alta vazão.

## Consequências
Positivas: escalabilidade horizontal, baixa latência, ecossistema maduro (Kafka Connect, Streams).
Negativas: complexidade operacional (ZooKeeper, tuning de partições), maior consumo de disco.
Trade-off: maior latência individual (~10ms) vs. throughput massivo.

## Alternativas Consideradas
- RabbitMQ: rejeitado por falta de suporte nativo a replay e ordenação fraca.
- AWS SQS: rejeitado por não garantir ordenação FIFO em alta vazão.

3. Ciclo de vida e governança dos ADRs

Os ADRs seguem um ciclo de vida bem definido:

Proposto → Aceito → (opcional) Depreciado → Substituído
         → Rejeitado
  • 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 novo ADR que atualiza a decisão.
  • Rejeitado: proposta recusada formalmente.

A governança deve ser leve: uma revisão semanal em reunião de arquitetura, com aprovação por consenso ou por um arquiteto líder. Atualizações ocorrem quando o contexto muda significativamente (nova tecnologia, requisitos alterados, falha identificada).

4. Integração dos ADRs com o fluxo de desenvolvimento

A prática recomendada é versionar ADRs junto com o código, em um diretório docs/adr/ no repositório principal ou em um repositório dedicado de arquitetura. Os gatilhos para criação incluem:

  • Mudanças significativas de tecnologia (troca de banco, framework)
  • Decisões com trade-offs relevantes (consistência vs. disponibilidade)
  • Riscos identificados (escalabilidade, segurança, custo)
  • Adoção de novos padrões (CQRS, Event Sourcing, Saga)

Os ADRs devem ser tratados como parte do processo de Pull Requests: cada PR que implementa uma decisão arquitetural deve referenciar o ADR correspondente. Isso cria rastreabilidade entre decisão e implementação.

Exemplo de referência em PR:
"Este PR implementa a decisão ADR-001 (Kafka como barramento de eventos).
Ver docs/adr/001-kafka-messaging.md para contexto completo."

5. Boas práticas de redação e clareza técnica

Para garantir que os ADRs sejam úteis a longo prazo:

  1. Linguagem clara e objetiva: evite jargões desnecessários. Escreva para um desenvolvedor pleno que não participou da decisão.
  2. Documente alternativas descartadas: isso mostra que a decisão foi ponderada e evita que outros repitam o mesmo raciocínio.
  3. Evite viés de confirmação: registre honestamente os trade-offs, mesmo que a decisão final tenha sido unânime.
  4. Seja específico: em vez de "melhor desempenho", escreva "redução de latência de 200ms para 15ms em cenário de 10k req/s".
Exemplo de má prática:
"Decidimos usar PostgreSQL porque é melhor."

Exemplo de boa prática:
"Decidimos usar PostgreSQL (vs. MongoDB) porque:
- O modelo relacional é adequado aos dados altamente estruturados do domínio financeiro.
- Requisito de transações ACID elimina bancos NoSQL.
- A equipe já possui 3 anos de experiência com PostgreSQL, reduzindo risco de adoção."

6. ADRs em arquiteturas orientadas a eventos e microsserviços

Em arquiteturas distribuídas, os ADRs são particularmente valiosos para rastrear decisões que atravessam múltiplos serviços. Decisões típicas incluem:

  • Padrão Outbox: garantir consistência entre banco de dados e mensageria.
  • Saga: coordenação de transações distribuídas com compensação.
  • CQRS: separação entre leitura e escrita para escalabilidade.
  • Consistência eventual: aceitar atraso na propagação de dados.

Exemplo de ADR para escolha entre Kafka e RabbitMQ:

# ADR-005: Escolha do barramento de eventos para sistema de pagamentos

## Status
Aceito

## Contexto
O sistema de pagamentos precisa processar 50.000 transações/hora com garantia de entrega.
Requisitos críticos: ordenação por ID de transação, retenção de eventos por 30 dias para auditoria.

## Decisão
Adotar Apache Kafka com 12 partições (uma por mês de retenção).
Justificativa: ordenação por partição atende ao requisito de ordenação por ID.
Retenção configurável permite auditoria sem banco adicional.

## Consequências
Positivas: replay de eventos para correção, integração com Kafka Streams para processamento.
Negativas: necessidade de administração dedicada, custo de armazenamento (~2TB/mês).

## Alternativas Consideradas
- RabbitMQ: rejeitado por retenção limitada (filas são efêmeras) e sem ordenação garantida.
- AWS SQS FIFO: rejeitado por limite de 300 mensagens/segundo.

7. Ferramentas e automação para gestão de ADRs

Ferramentas open source facilitam a criação e manutenção de ADRs:

  • adr-tools (npm): CLI para criar, listar e gerenciar ADRs com templates.
  • log4brains: gera site de documentação a partir de ADRs Markdown.
  • MkDocs + plugins: converte diretório de ADRs em site navegável.

Automação recomendada:

# Template de ADR via adr-tools
adr new "Adoção do Kafka para mensageria"
# Resultado: docs/adr/001-adocao-do-kafka-para-mensageria.md

# Linting com markdownlint
markdownlint docs/adr/*.md --config .markdownlint.json

# Geração de site com log4brains
npx log4brains build

8. Cultura organizacional e adoção de ADRs

Para adotar ADRs com sucesso:

  1. Comece pequeno: proponha ADRs apenas para decisões com impacto significativo.
  2. Vincule a rituais existentes: inclua revisão de ADRs em cerimônias ágeis (planning, retrospectiva).
  3. Celebre vitórias: mostre como um ADR evitou retrabalho ou acelerou onboarding.
  4. Mensure o impacto: acompanhe métricas como tempo de onboarding de novos devs, número de decisões revisitadas e redução de incidentes por falta de documentação.

Métricas de sucesso:

- Redução de 40% no tempo de onboarding de novos arquitetos
- 95% das decisões arquiteturais têm ADR associado
- Zero incidentes causados por desconhecimento de decisões passadas

ADRs não são burocracia — são um investimento na memória institucional do time. Quando bem implementados, transformam a documentação de arquitetura de um fardo em um ativo estratégico.

Referências