Passamos duas semanas debatendo uma escolha de banco de dados que ja tinhamos feito e rejeitado um ano antes. Foi quando descobri os ADRs, e eles nos pouparam inumeras horas desde entao.

Melhores Praticas para Registros de Decisao de Arquitetura (ADRs)

A reuniao ja durava duas horas. Estavamos debatendo se deveriamos usar PostgreSQL ou MongoDB para um novo servico. Argumentos iam e vinham — integridade relacional, schemas flexiveis, familiaridade da equipe, complexidade operacional.

Entao alguem mencionou: "Nao tivemos exatamente essa mesma discussao no ano passado para o servico de usuarios?"

Silencio. Tivemos. Um ano atras, tinhamos gasto uma quantidade similar de tempo debatendo a mesma questao, escolhendo PostgreSQL no final. Mas ninguem lembrava do raciocinio. O engenheiro que liderou aquela discussao tinha saido da empresa. Entao la estavamos, tendo exatamente o mesmo debate do zero.

Foi quando descobri Registros de Decisao de Arquitetura (ADRs), e eles nos pouparam inumeras horas de relitigar debates resolvidos.

O Que e um ADR?

Um ADR e um documento curto que captura uma unica decisao arquitetural. Nao um documento de design cobrindo tudo sobre um sistema, apenas uma decisao:

O que decidimos
Por que decidimos
Quais alternativas consideramos
Quais sao as consequencias

O formato e deliberadamente leve. Um ADR deve caber em uma pagina. Se for mais longo, voce provavelmente esta documentando mais de uma decisao.

A Anatomia de um Bom ADR

Depois de escrever dezenas de ADRs e ler centenas mais, descobri que os melhores seguem uma estrutura consistente:

Titulo e Numero

Cada ADR recebe um numero sequencial e um titulo conciso:

ADR-0042: Usar PostgreSQL para o Servico de Pedidos

O numero importa. Cria uma linha do tempo de decisoes e torna os ADRs faceis de referenciar em discussoes: "Como decidimos no ADR-42..."

Status

ADRs tem estados de ciclo de vida:

Proposto: Ainda em discussao
Aceito: Decisao tomada, estamos seguindo isso
Descontinuado: Nao e mais relevante (novo ADR o substitui)
Rejeitado: Consideramos isso mas decidimos contra

O status rejeitado e particularmente valioso. As vezes voce quer capturar por que nao fez algo, para que equipes futuras nao proponham a mesma coisa.

Contexto

Aqui voce descreve a situacao que motivou a decisao. Qual problema estamos resolvendo? Quais restricoes temos? Quem e afetado?

## Contexto

O servico de pedidos precisa de armazenamento persistente para dados de pedidos.
Esperamos processar 50.000 pedidos por dia inicialmente, crescendo para 500.000
em dois anos. Pedidos tem uma estrutura bem definida mas podem precisar de campos
de metadados adicionais ao longo do tempo. A equipe tem experiencia com bancos
de dados relacionais e de documentos.

Seja especifico sobre restricoes. "Precisamos de conformidade ACID" e muito mais util do que "precisamos de confiabilidade." Leitores futuros precisam entender as forcas que moldaram a decisao.

Decisao

Declare a decisao claramente. Nao "poderiamos considerar" ou "deveriamos explorar" — o que realmente decidimos.

## Decisao

Usaremos PostgreSQL 15 como banco de dados principal para o servico de pedidos.

Escolhemos PostgreSQL porque:

- Conformidade ACID e necessaria para dados financeiros de pedidos
- Colunas JSON fornecem flexibilidade de schema para metadados
- Nossa equipe de infraestrutura tem experiencia operacional com PostgreSQL
- Padroes de consulta sao adequados para modelagem relacional

Alternativas Consideradas

Esta e a secao mais subestimada. Documentar o que voce nao escolheu e frequentemente tao valioso quanto documentar o que escolheu.

## Alternativas Consideradas

### MongoDB

Pros:

- Armazenamento JSON nativo
- Escalabilidade horizontal mais simples
- Evolucao de schema flexivel

Contras:

- Garantias de consistencia mais fracas
- Equipe menos familiarizada com operacoes
- Necessitaria ferramentas adicionais para transacoes

### DynamoDB

Pros:

- Totalmente gerenciado, operacoes minimas
- Excelentes caracteristicas de escalabilidade

Contras:

- Dependencia de fornecedor (AWS)
- Padroes de consulta limitados ao acesso por chave de particao/ordenacao
- Custo imprevisivel em alta escala

Quando alguem novo entra na equipe e pergunta "por que nao usamos MongoDB?", voce tem a resposta. Nao precisa agendar uma reuniao ou encontrar a pessoa que tomou a decisao original.

Consequencias

Toda decisao tem trade-offs. Seja honesto sobre eles.

## Consequencias

### Positivas

- Fortes garantias de integridade de dados
- Equipe pode aproveitar expertise existente em PostgreSQL
- Caracteristicas operacionais bem conhecidas

### Negativas

- Migracoes de schema requerem mais planejamento que bancos de documentos
- Escalabilidade horizontal mais complexa se excedermos capacidade de no unico
- Necessidade de implementar sharding a nivel de aplicacao se atingirmos limites

### Riscos

- Pode ser necessario revisitar se volume de pedidos exceder 1M/dia
- Consultas em colunas JSON menos eficientes que bancos de documentos nativos

Esta secao e sobre honestidade intelectual. Nenhuma decisao e perfeita. Reconhecer os pontos negativos constroi confianca e ajuda equipes futuras a entender quando podem precisar revisitar a decisao.

Quando Escrever um ADR

Nem toda escolha tecnica precisa de um ADR. Use seu julgamento, mas aqui estao algumas diretrizes:

Escreva um ADR Quando...

A decisao afeta multiplas equipes ou servicos
A decisao seria cara de reverter
Voce esta escolhendo entre multiplas opcoes viaveis
Membros futuros da equipe podem questionar a escolha
A decisao resolve um debate tecnico significativo

Nao Escreva um ADR Quando...

A escolha e obvia e incontestada
A decisao afeta apenas uma pessoa ou um arquivo
E facilmente reversivel sem custo significativo
E um padrao que sua equipe sempre segue

Por exemplo: "Qual biblioteca JSON devemos usar?" provavelmente nao precisa de um ADR. "Devemos usar GraphQL ou REST para nossa API publica?" definitivamente precisa.

Erros Comuns Que Cometi

Erro 1: Escrever ADRs Depois do Fato

O melhor momento para escrever um ADR e durante o processo de decisao, nao semanas depois. Quando voce escreve depois, esquece as nuances, as alternativas que considerou e as restricoes especificas.

Agora escrevemos rascunhos de ADRs como parte do processo de tomada de decisao. A discussao acontece no documento do ADR, nao em threads do Slack que desaparecem.

Erro 2: Torna-los Muito Longos

Se seu ADR tem mais de uma pagina, voce provavelmente esta:

Documentando multiplas decisoes (divida em multiplos ADRs)
Incluindo detalhes de implementacao (guarde para documentos de design)
Explicando demais contexto obvio

A disciplina da brevidade forca clareza.

Erro 3: Nao Vincular ADRs Relacionados

Decisoes raramente existem isoladamente. Quando escolhemos Kafka para comunicacao orientada a eventos (ADR-0007), isso influenciou nossa escolha de banco de dados (ADR-0042) porque podiamos aceitar consistencia eventual.

Referencie ADRs relacionados:

## Decisoes Relacionadas

- Veja ADR-0007 para por que aceitamos consistencia eventual
- Substitui ADR-0003 que recomendava MongoDB

Erro 4: Abandonar a Pratica

ADRs fornecem valor ao longo do tempo. Um ou dois ADRs nao ajudam muito. Um corpus de 50+ ADRs, acumulados ao longo dos anos, se torna incrivelmente valioso. E um historico pesquisavel da sua evolucao arquitetural.

A tentacao e parar de escreve-los quando as coisas ficam corridas. Resista. Os dez minutos gastos escrevendo um ADR pouparao horas de reunioes depois.

Tornando ADRs Parte do Seu Fluxo de Trabalho

A parte mais dificil nao e escrever ADRs — e torna-los um habito. Eis o que funciona:

Armazene-os Com o Codigo

Coloque ADRs no seu repositorio, tipicamente em docs/adr/ ou docs/decisions/. Dessa forma:

Sao versionados com o codigo que descrevem
Aparecem em code reviews
Nao podem se tornar orfaos em alguma wiki

Crie um Template

Crie um template markdown que todos usem. Isso reduz fricao e garante consistencia.

Revise ADRs Trimestralmente

Defina um lembrete para revisar seus ADRs a cada trimestre:

Alguma decisao nao e mais relevante?
As circunstancias mudaram de forma que invalida nossas premissas?
Ha decisoes nao documentadas que deveriamos capturar?

Vincule ADRs a Diagramas de Arquitetura

E aqui que ferramentas como o Archyl brilham. Quando voce vincula um ADR a um componente especifico no seu diagrama C4, qualquer pessoa olhando aquele componente pode ver instantaneamente as decisoes que o moldaram.

"Por que esse servico fala com Kafka ao inves de diretamente com o banco de dados?" Clique no ADR vinculado e descubra.

Conclusao

Registros de Decisao de Arquitetura sao uma daquelas praticas que parecem overhead ate voce precisar deles. Ai sao inestimavel.

Aquela reuniao de duas horas sobre PostgreSQL vs MongoDB? Terminamos em dez minutos depois que alguem encontrou o ADR original. Todo o contexto estava la — as restricoes, as alternativas, o raciocinio. Rapidamente confirmamos que a decisao original ainda se aplicava e seguimos em frente.

Comece pequeno. Na proxima vez que fizer uma decisao arquitetural, tire quinze minutos para escrever um ADR. Coloque no seu repositorio. Daqui a seis meses, quando alguem perguntar "por que fizemos dessa forma?", voce tera a resposta.

Saiba mais sobre documentacao de arquitetura: Introducao ao Modelo C4 | Por Que a Documentacao Importa | Documentando Fluxos de Usuario

Melhores Praticas para Registros de Decisao de Arquitetura (ADRs) - Archyl Blog