No cenário dinâmico do desenvolvimento de software, a tomada de decisões arquiteturais é um ponto importante para o sucesso de um projeto. Então, o conceito de Architectural Decision Record (ADRs) surge como uma ferramenta valiosa para documenta-las com o menor esforço possível. Assim, inspirados pelo livro “Release It Design and Deploy Production-Ready Software” de Michael Nygard, os ADRs são registros que capturam o contexto, as opções consideradas, a decisão tomada e suas justificativas.
Aqui no blog temos diversos artigos sobre temas como Domain Driven Design, Kubernetes, Gestão, entre outros. Fique a vontade para conferir.
Sumário
Release it!
Michael Nygard em seu livro “Release It! Design and Deploy Production-Ready Software” fala sobre diversas técnicas voltadas a construção de um software robusto e confiável em ambiente de produção. Ele fala sobre coisas como tolerância a falhas, monitoramento, escalabilidade e como lidar com situações inesperadas. Um item interessante nesse contexto é o conceito do Architectural Decision Record que veremos em detalhes aqui no artigo.
Compreendendo o Architectural Decision Record
Já passou pela situação de ver um software desenvolvido sem qualquer documentação e sem entender muito bem porque uma determinada solução usa MongoDB, Cassandra ou CQRS? “Isso é raro mas acontece muito”, dizem. Não é difícil encontrar os “engenheiros de obra pronta”: são aqueles que encontram todos os defeitos, sabem tudo o que precisa ser feito para ficar ideal, mas não têm coragem para liderar nada.
Sistemas sem documentação certamente são problemas, mas documentação sem manutenção também. Portanto é fundamental ter um processo que garanta que a documentação sempre esteja adequada para o consumo de um ou mais sistemas.
Então, um Architectural Decision Record (ADR) é um documento que registra uma decisão arquitetural importante tomada durante o processo de desenvolvimento de software. Assim ele documenta o contexto em que a decisão foi tomada, as opções consideradas, a decisão tomada e os motivos por trás dessa decisão.
O objetivo principal de um ADR é fornecer um registro claro e conciso das decisões arquiteturais, facilitando a compreensão do sistema para as equipes atuais e futuras, além de fornecer um histórico útil para revisões e aprendizado. Ao registrar essas decisões de forma sistemática, as equipes podem evitar retrabalho e tomar decisões mais informadas ao longo do ciclo de vida do software.
Entenda que um ADR pode ser documentado em markdown, num documento word, numa lista do SharePoint ou card do Trello. Não importa, desde que expresse a decisão tomada e o seu porque, para quem interessar.
Architectural Decision Record como estratégia
Observe que uma decisão arquitetural pode influenciar qualquer camada da arquitetura, seja corporativa, de soluções, de aplicações ou tecnológica, embora seja mais evidente na última. Então, compreenda que decisões nos níveis corporativos afetarão diretamente o trabalho dos arquitetos corporativos e como ele será realizado: Isso resultará em uma cascata de impactos, afetando as arquiteturas de solução, aplicação e tecnologia.
Assim, para facilitar o entendimento, uma empresa pode decidir que cada squad terá autonomia para escolher a stack adequada; outra pode preferir a nuvem Azure devido à sua economia por meio de parcerias com a Microsoft; outra ainda pode optar pelo ActiveMQ em vez do RabbitMQ por razões específicas. Por isso, apenas as decisões mais relevantes são destacadas em um ADR, proporcionando maior utilidade em seu uso.
Architectural Decision Record na prática
O autor sugere um template como esse. Nele que o template tem um título, status, contexto, a decisão em si e as consequências. Vamos ver a seguir um exemplo de uma ADR para a escolha no player de nuvem para uma empresa.
Título: Adoção da Microsoft Azure como plataforma de nuvem exclusiva.
Status: Aprovada.
Contexto: Avaliação de provedores de nuvem para hospedar aplicações e serviços, considerando Oracle Cloud, AWS e GCP.
Decisão: Adotar a Microsoft Azure devido à integração com sistemas existentes e ampla gama de serviços.
Consequências: Simplificação da integração, redução da complexidade operacional, escalabilidade flexível e potencial redução de custos.
Note que o texto pode ser mais ou menos explicativo, devendo a empresa criar e manter processos que suportem o bom uso desse tipo de ferramenta.
Veja também que o exemplo acima usa uma quantidade limitada de campos, com base nas orientações do autor. Mas há diversos outros templates que podem ser usados ou mesclados para o uso prático em sua empresa. Veja a seguir um conjunto de outros campos de exemplo:
- Título: Um título descritivo para identificar a decisão arquitetural.
- Data: Data em que a decisão foi tomada.
- Responsável: Nome da pessoa ou equipe responsável pela decisão.
- Contexto: Descrição do contexto que motivou a decisão arquitetural.
- Opções Consideradas: Lista das opções de design que foram consideradas.
- Decisão: Descrição da decisão arquitetural tomada.
- Razão: Justificativa ou razão por trás da decisão.
- Consequências: Possíveis consequências da decisão tomada.
- Status: Estado atual da decisão (por exemplo, aprovada, em andamento, cancelada).
- Revisão: Data prevista para revisão da decisão ou status de revisão.
- Revisado por: Nome da pessoa responsável pela revisão.
- Notas Adicionais: Qualquer informação adicional relevante.
Processo de adoção
Quando uma empresa possui formalmente setores responsáveis por arquitetura isso tudo é mais natural. Mas mesmo quando não tem, há arquitetura e decisões, que muitas vezes são tomadas por pessoas que não têm a visão completa sobre o ambiente ou estratégias da organização. Por conta disso, processos precisam amparar a definição dessas decisões, a documentação, a visibilidade e manutenção delas.
Quem pode criar um ADR?
O nível de autonomia varia muito de empresa para empresa, mas empresas menos centralizadoras suportam a ideia de que qualquer um desenvolvedor pode sugerir, mas apenas líderes técnicos, sêniores ou arquitetos são os responsáveis por manter as decisões registradas. Decisões que substituem ou esbarram em outras precisam ser avaliadas toda vez que há alteração nessa estrutura. Além disso, é necessário ter clareza da abrangência da decisão: como eu disse no início, ela pode ser uma decisão de arquitetura corporativa, de soluções, de aplicação ou tecnológica; pode cobrir diversos sistemas ou apenas um, entre outras possibilidades.
Conclusão
Para finalizar, os Architectural Decision Records (ADRs) representam uma abordagem eficaz para a documentação e comunicação de decisões arquiteturais em projetos de software. Inspirados pela obra de Michael Nygard, eles fornecem um meio estruturado para registrar o raciocínio por trás das escolhas arquiteturais, permitindo uma melhor compreensão do sistema e facilitando a colaboração entre as equipes. Ao adotar os ADRs, as organizações podem promover uma cultura de transparência, consistência e aprendizado contínuo, contribuindo para o desenvolvimento de software mais robusto e confiável.
Ele atua/atuou como Dev Full Stack C# .NET / Angular / Kubernetes e afins. Ele possui certificações Microsoft MCTS (6x), MCPD em Web, ITIL v3 e CKAD (Kubernetes) . Thiago é apaixonado por tecnologia, entusiasta de TI desde a infância bem como amante de aprendizado contínuo.