O Registo de Decisões de Arquitetura: Por Que a Tua Equipa Precisa de Um
Todas as equipas de engenharia tiveram esta conversa. Um desenvolvedor abre um módulo, olha para uma implementação que parece desnecessariamente complexa e pergunta: "Por que foi construído assim?" O silêncio instala-se. A pessoa que tomou a decisão saiu há oito meses. Ninguém consegue explicar o raciocínio real.
A equipa faz uma de duas coisas. Ou deixa como está por medo ("provavelmente havia uma razão"). Ou refactoriza, reintroduzindo sem saber exatamente o problema que a implementação original foi concebida para evitar.
Os Architecture Decision Records resolvem isto. São uma das práticas mais simples e com maior ROI que uma equipa de engenharia pode adotar, e a maioria das equipas não as usa.
O que é Realmente um ADR
Um ADR é um documento curto — geralmente menos de uma página — que captura uma única decisão arquitetural. Não um documento de design. Não um RFC. Apenas um registo do que foi decidido, por que foi decidido e quais são as consequências esperadas.
O formato é deliberadamente mínimo. A estrutura mais utilizada tem cinco secções:
- Título. Uma frase nominal curta.
- Estado. Proposto, Aceite, Obsoleto ou Substituído.
- Contexto. Qual é a situação? Que forças estão em jogo?
- Decisão. O que decidimos? Declara-o claramente.
- Consequências. O que resulta desta decisão? Positivas e negativas.
Por Que a Secção de Contexto é Tudo
A decisão em si é geralmente óbvia ao olhar para o código. O que não consegues ver é o porquê. E é aí que reside todo o valor.
Um bom contexto captura o panorama decisional no momento: as alternativas existentes, os constrangimentos em que a equipa operava, as trocas avaliadas.
Exemplos de Bons Tópicos para ADRs
O limiar que uso: se a decisão é difícil de reverter, afeta múltiplas partes do sistema, ou será questionada por futuros membros da equipa, escreve um ADR.
Exemplos:
- Escolha de base de dados. "ADR-003: Usar PostgreSQL para dados transacionais e Redis para armazenamento de sessões."
- Abordagem de autenticação. "ADR-007: Implementar autenticação stateless baseada em JWT com tokens de atualização."
- Seleção de serviço de terceiros. "ADR-015: Usar Stripe para processamento de pagamentos."
Onde Vivem os ADRs
Isto é inegociável: os ADRs vivem no repositório de código. Não no Confluence. Não no Google Docs. No repositório, num diretório como /docs/adr/, versionado com o código que descrevem.
O Custo da Ausência de ADRs
Conhecimento tribal. As decisões arquiteturais vivem nas cabeças de quem as tomou. Quando essas pessoas saem, o conhecimento vai com elas.
Debates repetidos. Sem registo do porquê, as equipas revisitam as mesmas discussões de poucos em poucos meses.
Atrito no onboarding. Um novo membro da equipa tem de fazer engenharia inversa de toda a lógica arquitetural.
Começar Sem Burocracia
Da próxima vez que a tua equipa tomar uma decisão arquitetural significativa, faz com que a pessoa que a conduziu passe 20 minutos a escrevê-la em formato de cinco secções. Coloca-a num PR. Revê-a. Faz o merge. Este é o teu primeiro ADR.
Na Conectia, vimos que os ADRs fazem uma diferença particularmente grande em equipas distribuídas. Quando os nossos engenheiros sénior se juntam à equipa de um cliente, os ADRs existentes permitem-lhes entender a lógica arquitetural em dias em vez de semanas.
A construir uma equipa que toma boas decisões arquiteturais e as documenta? Fala com um CTO — os nossos engenheiros sénior LATAM trazem a disciplina da tomada de decisão estruturada para a tua codebase desde o primeiro dia.
