ADRs (Architecture Decision Records)

São documentos curtos que registram decisões técnicas significativas e o contexto que as motivou.

Eles funcionam como uma "cápsula do tempo", documentando não apenas o que foi escolhido, mas o porquê.

Por que os ADRs são importantes?

A arquitetura de um software evolui conforme as decisões são tomadas, e o ato de documentá-las protege o projeto contra o esquecimento.

• Compreensão histórica: Permite que novos membros da equipe entendam o histórico do sistema sem depender da memória de funcionários mais antigos.
• Foco no "Porquê": Evita que decisões passadas sejam questionadas sem o devido contexto técnico ou que sejam alteradas de forma inadequada.
• Alinhamento de equipe: Facilita a comunicação, pois o processo de escrita força a equipe a discutir os prós e contras das alternativas antes da implementação.

Estrutura básica de um ADR

Um ADR deve ser conciso e objetivo. Ele geralmente é versionado em formato Markdown no mesmo repositório do código e segue uma estrutura padrão:

• Título: Identificador único e um nome descritivo (ex: 001 - Uso do PostgreSQL para o banco de dados principal).
• Contexto: A situação atual, as restrições e o problema que exigiu uma decisão.
• Decisão: A solução escolhida para o problema.
• Opções consideradas: Outras alternativas mapeadas e os motivos pelos quais foram descartadas.
• Consequências: Os benefícios (prós) e os pontos negativos/desafios (contras) e impactos da escolha.
• Status: O estado atual (como Proposto, Aceito, Rejeitado ou Substituído).

Como os ADRs registram o ciclo de vida da arquiteturaA arquitetura de software é viva. Ao documentar cada escolha, o conjunto de ADRs ao longo do tempo forma um "log" detalhado do ciclo de vida arquitetural:

• Evolução do projeto: Cada ADR captura um marco ou mudança estrutural significativa no software.
• Substituição de decisões: Se uma tecnologia ou padrão se tornar obsoleto, um novo ADR é criado com o status de Substituído, referenciando a decisão original e o novo caminho adotado.
• Rastreabilidade: Permite compreender facilmente em qual momento do ciclo de vida do software uma determinada limitação ou tecnologia foi introduzida.Para saber mais sobre como implementar na prática e conferir os modelos recomendados, você pode consultar o guia prescritivo de arquitetura da AWS Architectural Decision Records ou a documentação do Microsoft Azure Well-Architected Framework.